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/django-boilerplate 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¶

Visit the following cloud tool sites, sign in with GitHub and add your new fork:

Add your repository to Travis CI.
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/django-boilerplate.git
$ cd django-boilerplate
$ git remote set-url origin --push git@github.com:$USER/django-boilerplate.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/django-boilerplate.git

Install any requirements¶

Usually you’ll want to use the tox automation tool to run tests, etc but you can run the application within your virtualenv by installing the default requirements:

$ pip install -r requirements.txt

The -e flag to pip will cause the install to use symlinks rather than copying which allows for in-place modification of the source without having to re-install.

Set up local configuration¶

The developer settings are configured to load some settings from the environment. These are settings which are either sensitive or dependent on third-party sources.

It is recommended that you create a file names setupenv.sh in the root directory of the application and add contents similar to the following:

# Template "setupenv.sh" file.
#
# Use this file to create a "setupenv.sh" file in the root of the repository
# which can be used to configure the environment with sensitive or
# local-specific values. Activate before running application as a developer
# via: "source setupenv.sh".
#
# THIS FILE IS ONLY OF USE DURING DEVELOPMENT. IT PLAYS NO ROLE IN DEPLOYMENT.

export SECRET_KEY="your-secret-here"

Start the development server¶

There is a docker-compose file at the top-level of the webapp repository which contains configuration allowing the application container to be launched in a development mode.

$ docker-compose up devserver

Before you can authenticate against the API, you must create an OAuth2 client application. The scripts/create-client.sh will create a suitable client with the id “testclient”.

After creating the “testclient” client, you can browse the API docs at http://localhost:8000/ui. Click the “Authorize” button to obtain an access token as “testclient”. Remember to select all of the required scopes.

You can also browse the API docs for the lookupproxy at http://localhost:8080/ui.

Next steps¶

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