Skip to content

Latest commit

 

History

History
135 lines (92 loc) · 5.52 KB

HowToStart.adoc

File metadata and controls

135 lines (92 loc) · 5.52 KB
Raw

How to start

Setting up an ACCU conference website development environment

Original by Felix Petriconi, amendments by Russel Winder

Introduction

These instructions assume that you have an Debian Sid or Ubuntu 16.04 (or later) installation with Python 3 and Git available and your Git environment configured. Other platforms may be used, obviously, but have not been tested.

Forking and cloning the Git repository

To set up your working clone:

This should give you a fully working set up.

The basic workflow is to make changes in your local clone, push them to your fork on GitHub, and then make pull requests to the mainline. It is important though always to work against the up to date mainline so whenever you want to make any changes, first make sure your fork and local clone are up to date with the mainline:

  • Fetch the latest changes from the mainline: git fetch mainline

  • Update the local repo with the mainline changes: git merge mainline/master

  • Update your fork on GitHub: git push

A crucial local amendment

Because of the way the build works, it is important to add a symbolic links from specific places in the directory hierarchy to other specific places in the hierarchy. So from the working directory you should:

On Windows 7 or later * create_links.bat

On Linux, Mac, etc. * ./create_links.sh

This is a "do once for each new clone". The link is not present in the repository because of compatibility problems of handling symbolic links between Windows and the other systems, and it is not needed for the deployed website, it is only needed for running the test server in your local clone.

Getting the toolchain

So as to build the website you will need Python 3, the Nikola framework, the Flask framework, SQLAlchemy, SQLite, and the Asciidoctor system. To run the Flask-based subsystem tests you will need PyTest and Hypothesis.

Although it is generally good to use packages whenever possible, there are some aspects of the required setup that mean we must use pip and packages from PyPI. Always avoid using pip as superuser to put packages from PyPI into the platform package managed area. Always use pip into your personal area, i.e. when using pip always use the --user option.

The Debian and Ubuntu packages for Nikola are Python 2 based, so Nikola is installed using pip. There are some Flask related packages but there are some (important for our situation here) missing packages. The Debian and Ubuntu package for everything else are up to date and so can be used.

  • Ensure the following packages are installed (other packages will be installed as dependencies):

    • python3

    • python3-pip

    • python3-hypothesis

    • python3-pep8

    • python3-pytest

    • asciidoctor

  • From within the working directory:

    • Install Nikola: pip3 install --user -r static_nikola_part/requirements.txt

    • Install Flask: pip3 install --user -r flask_application_part/pip_requirements.txt

If you find that the asciidoctor package is not working or is not available then you can:

  • Install Ruby: sudo aptitude install ruby

  • Install Asciidoctor: sudo gem install asciidoctor

  • You may also want to install the PDF generator: sudo gem install asciidoctor-pdf

Updating the toolchain

As well as regularly updating the platform packages to ensure being as up to date as possible, it is important to keep the package installed with pip as up to date as possible. So every so often, perhaps at the beginning of each session, you might want to:

  • Upgrade Nikola: pip3 install --upgrade --user -r static_nikola_part/requirements.txt

  • Upgrade Flask: pip3 install --upgrade --user -r flask_application_part/pip_requirements.txt

Building the website

It is always important to have the static material up to date and built. The reason for this is that the Flask application assumes it can access the static material – hence the symbolic link we put in place during creation of the working directory. In particular all the styling data for the Flask application is stored in the static material – long story but it is the right set up for this website.

Build the static part:

  • cd static_nikola_part/

  • nikola build

  • cd ..

Running the application

The Flask application assumes the presence of a SQLite database file. Running the tests uses the same file as when you run the application for interactive sessions, so if you want the preserve data from an interactive session make sure you backup the flask_application_part/accuconf.db and flask_application_part/accuconf_test.db files for putting back in place later.

To create an initial database:

  • cd flask_application_part/

  • ./cli.sh create_database

  • cd ..

To run all the tests:

  • py.test-3 pytest flask_application_part

or if that fails for some reason:

  • python3 -m pytest flask_application_part

To run the Flask application for interactive use (but remember the point about there must be a database and the tests are destructive of the database):

  • ./runapp.py

You should now be able to navigate to http://localhost:8000 with any reasonable browser and use the website from your working directory.