All of the dependencies run inside a Virtual Machine, so not a lot of software is required on the host system (your computer) to run the development version of 18xx Accountant. The only two requirements are Vagrant (version 1.9.1 and up should work) and Virtualbox (version 5.1.14 and up should work). To run the VM all that is required is the command
vagrant up
and Vagrant should take care of the rest. It is best to grab a cup of coffee because starting the VM will take a while. Vagrant takes care of installing all the actual dependencies: Angular2, Chrome for testing, PostgreSQL, two versions of Python and pyenv to manage them. Finally it will install the required Python packages.
The VM can be accessed through the command vagrant ssh and a live copy
of the repository lives in /vagrant/. For more details see the
Vagrant documentation.
To run the Django backend you need to log in on the VM and cd to
/vagrant/accountant/. Pyenv will automatically activate the development
environment when you enter that directory. The Django built-in test
server is sufficient for development, but you need to be able to access it
from outside of the VM, so the command to run it is:
python manage.py runserver 0.0.0.0:8000
This makes the test server accessible from your host machine, but it is not
possible yet to view the website. The VM provisioning script takes care of
setting up the database and migrations, so there is no need to worry about
that until you start editing models. The only missing piece is the
front-end, During development the Django test server mostly functions as a
backend while Angular serves a live front-end, for instructions on how to
do that see below. It is also possible to let Django
serve the backend, to do this you need to go to the main directory
/vagrant and run the script ./build-ng-app.sh. This will automatically
transpile the Angular2 front-end and copy it to the appropriate place so
that Django can serve it. See
Running functional tests for more details on
the script. Every time the Angular2 app gets updated you need to run this
command again to see the changes. After you do this you can view the
website like regular on http://localhost:8000/. It is possible to view
the REST API on http://localhost:8000/api/.
Although it is possible to let Django serve the front-end, it is easier to
let Angular2 take care of it. When you edit the source for the front-end
then Angular2 will automatically update your browser. To run the Angular2
front-end all you need to do is cd to /vagrant/ngApp/ and run the
command:
npm start
This command is set up to automatically reload the page in the browser when the app gets updated. It also forwards API requests to the Django backend so that you can work with a fully functioning system. Interactions with the front-end are reflected on http://localhost:8000/api/. To access the front end you can visit http://localhost:4200/.
Because this project adheres to the Test-Driven Development paradigm it is important to know how to run the tests. This section describes how to do that.
Running the functional tests is the most complicated part of testing. It
requires that you've build the Angular2 app since that is what the tests
interact with. This can be done by running ./build-ng-app.sh in the
/vagrant/ directory. This will build the Angular2 app with the right
settings and copies the result to where Django expects to find it. All
parameters given to the script are passed on to the build step. This is
mostly useful for enabling production mode by adding the --prod flag.
The front-end is build in debug mode by default.
After building the Angular2 app the functional tests can be run by
navigating to the Django directory (/vagrant/accountant/) and running
the following command:
python manage.py test functional_tests
This will use Selenium to test the website if it functions as expected.
Next to the functional tests it is also necessary to test the back-end, this can be done by running the command
python manage.py test core interface
in the /vagrant/accountant/ directory. It is also possible to execute
python manage.py test
to run the functional tests and unit tests at the same time.
Testing Angular2 is a bit more involved, you need to run the Angular2 test
server and visit the page. The test server can be run by navigating to
/vagrant/ngApp and running the command
npm test
This starts the test server, you can access it by navigating to
http://localhost:9876/. The page will automatically start the tests and
you can see the test output in your console window. You can also see this
output in the console of the web development tools in your browser
(usually they can be accessed by pressing F12). This page will always
reload and rerun all the tests when you update the Angular2 code. If you
want to only run a subset of the tests and/or control when to run the
tests you can do this by pressing the DEBUG button on the top right. For
more information you can check the
Angular2 docs.
The back-end and front-end have different methods of obtaining the code
coverage. For the code coverage of the Angular2 app you must run the
following command in the /vagrant/ngApp/ directory:
ng test -sr -cc --browsers Chromium
This command will output the results to the ngApp/coverage/ directory
in the repository. When you open the index.html file in that directory
with your browser you can explore the coverage. It is a known bug that
the coverage for constructors is not reported correctly.
To obtain the coverage for the backend you must run the following command
in the /vagrant/accountant/ directory:
coverage run manage.py test
This will run the unit tests and the functional tests so it can take a while, but it is necessary to run all suites to get a good overview of the coverage. Next you need to run
coverage html
to create a coverage report. You can view the coverage report by opening
the file accountant/htmlcov/index.html in your browser.
Provisioning and deploying to a server is handled by Ansible. Unfortunately Ansible does not work with Python 3.4.2 which is the version used for development. During setup of the VM Python 3.6.0 was also installed. You can enable this for a single console by executing the command:
pyenv shell ansible
It has all the requirements to run the website installed, and it also
supplies Ansible. To deploy you first need to create an inventory file so
that Ansible knows which server to deploy to and how to access it. The
inventory also holds some of the configuration options. An example
inventory file can be found in deploy/inventory.example, it should be
pretty explanatory on what you need to set the variables to, although it
might be wise to consult the
Ansible documentation. Once you have an
inventory file you can deploy to your server running the following command
in the /vagrant/ directory:
ansible-playbook -i <your inventory file> -K deploy/deploy.yml
This command will first ask you for your sudo password. If this does not
require a password you can leave out the -K. The command will compile
the Angular2 front-end in production mode if this has not already been
done, this can take a while without output so you need to be patient.
Ansible will install all necessary software on your server and configure
it to serve the application on the domain you specified in the inventory
file. It will also create a database account and store it in the file
deploy/credentials/postgrespassword which does what the name suggests.
If you loose this file then Ansible will not be able to manage the
database any more. Next to this file is also a secret_key file, this is
to set Django's SECRET_KEY setting and it is not as important to not
loose this file.
The deployment script assumes that you want to serve the website over HTTPS only. It expects that there is a small separate configuration file which specifies how the site should be served over a secure connection, no reference file is supplied at the moment. The software also assumes that the server is running Debian Jesse, although it is likely to work fine on other Debian based distros as well. It also assumes that systemd is present on the system.
The application source and data will be present at
/var/www/sites/<your domain>/ where there is a virtualenv to contain all
Python dependencies. nginx is used to serve all the files in the static/
folder to the user, including the Angular2 app. The deployment script
registers a gunicorn service with systemd, it will use your domain in the
name of the service. systemd is automatically restarted after deployment.
Testing against a staging server is quit similar to running the functional
tests. The only difference is that you need to tell Django that you want
to test against an external server. This is done by adding the -s or
--staging flag to the test command. The --staging takes two
parameters, the first is the URL that the website can be accessed at, the
second parameter is the inventory file that you used to deploy to the
server. The new testing command becomes
python manage.py test -s <url> <inventory> functional_tests
Only the functional tests can be run against a staging server, all other tests are always ran on the local machine. WARNING: Running the functional testsagainst the staging server will clear the database between each test, so if you accidentally run the tests against your production server you will loose all your data.
The deploy script installs the following software which is all required to run the website
nginx
Python 3 (3.4.2 on Debian Jesse)
git
PostgreSQL