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 ``scrips/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:8080/ui. Click the "Authorize" button to obtain an access
token as "testclient". Remember to check that the ``lookup:anonymous`` scope is
selected.

Next steps
``````````

See the :doc:`developer` for what to do next.