Getting started

This section is a guide to checking out the source and getting a development machine configured. More information on development is found in the Developer’s guide.

Fork the upstream repository

The repository at https://github.com/uisautomation/gauth-webapp is configured to disallow pushing to master. You’ll need to fork the repository into your personal account and then open pull requests from your personal repository into the main repository.

Set up cloud integrations

In order to make sure any branches you develop in your fork are tested, visit the following cloud tool sites, sign in with GitHub and add your new fork:

1. Add your repository to Circle CI.
2. Go to Codecov and add your fork as a watched repo. Make sure to enable the Codecov integration.

Clone the repository locally

Clone the remote upstream repository locally and configure the push URL to be your local user fork. This means that git push commands will modify your local fork but git pull commands will automatically fetch from the upstream repository.

$ git clone git@github.com:uisautomation/gauth-webapp.git
$ cd gauth-webapp
$ git remote set-url origin --push git@github.com:$USER/gauth-webapp.git

Note

Make sure to replace $USER with your GitHub user name. If your GitHub user name happens to be the same as your local user name, on Unix-y systems this will be done by magic!

It is also worth setting up an explicit remote for your personal repository. Sometimes you’ll want to push or pull from it.

$ git remote add $USER git@github.com:$USER/gauth-webapp.git

Running a development server

There is a docker-compose file at the top-level of the Google Auth Webapp repository which contains configuration allowing the application container to be launched in a development mode. In this mode the application repository is mounted read-only as a volume within the container over the top of the application code so changes are reflected within the container without need to rebuild it.

The local repository is mounted read-only because any files written by the application will appear in the local repository as a root-owned file which can be troublesome.

To run the development server:

$ ./compose.sh development

This makes use of the gauthwebapp.settings.developer settings, launches a PostgreSQL container for the development server and a MailHog server to monitor outgoing email. The web app is available at http://localhost:8000/ and the MailHog instance at http://localhost:8025/.

Note

If the requirements/*.txt files are modified, you’ll need to re-build the container image via docker-compose build.

Occasionally, it is useful to get an interactive Python shell which is set up to be able to import the application code and to make database queries, etc. You can launch such a shell via:

$ ./compose.sh development exec development_app python3 ./manage.py shell

Running tests

The test-suite can be run within the container using a PostgreSQL database in the following way:

$ ./tox.sh

Additional options can be passed to tox by appending them to the command. E.g.

$ ./tox.sh -e doc

Output generated by tox is persisted into a volume called “tox-data”. See the docker-compose configuration for the specifics.

Next steps

See the Developer’s guide for what to do next.