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
:doc:`Developer's guide <developer>`.

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:

1. Add your repository to  `Travis CI <https://travis-ci.org/>`_.
2. Go to `Codecov <https://codecov.io/>`_ 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.

.. code-block:: bash

    $ 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.

.. code-block:: bash

    $ git remote add $USER git@github.com:$USER/django-boilerplate.git

Install any requirements
````````````````````````

Usually you'll want to use the `tox <https://tox.readthedocs.io/>`_ automation
tool to run tests, etc but you can run the application within your virtualenv by
installing the default requirements:

.. code-block:: bash

    $ 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:

.. literalinclude:: ../setupenv.example.sh
    :language: bash

Start the development server
````````````````````````````

There is a `docker-compose <https://docs.docker.com/compose/>`_ file at the
top-level of the webapp repository which contains configuration allowing the
application container to be launched in a development mode.

.. code-block:: bash

    $ 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 :doc:`developer` for what to do next.