Skip to content

Latest commit

 

History

History
209 lines (136 loc) · 5.42 KB

INSTALL.rst

File metadata and controls

209 lines (136 loc) · 5.42 KB
Raw

Installation

The Zaaktypecatalogus (ZTC) is developed in Python using the Django framework and the Django Rest Framework.

For platform specific installation instructions, see the "deployment" folder.

Getting started

Quick start using Docker

The easiest way to get started is by using Docker Compose.

  1. Clone or download the code from Github in a folder like ztc:

    $ git clone [email protected]:VNG-Realisatie/catalogi-api.git ztc
Cloning into 'ztc'...
...

$ cd ztc

  2. Start the database and Zaaktypecatalogus services:

    $ docker-compose up -d
Starting ztc_db_1 ... done
Starting ztc_web_1 ... done

  3. Create an admin user for our Zaaktypecatalogus and load initial data. If different container names are shown above, use the container name ending with _web_1:

    $ docker exec -it ztc_web_1 /app/src/manage.py createsuperuser
Username: admin
...
Superuser created successfully.

$ docker exec -it ztc_web_1 /app/src/manage.py loaddata admin_index groups
Installed 5 object(s) from 2 fixture(s)

  4. Point your browser to http://localhost:8000/ to access the Zaaktypecatalogus with the credentials used in step 3.

    If you are using Docker Machine, you need to point your browser to the Docker VM IP address. You can get the IP address by doing docker-machine ls and point your browser to http://<ip>:8000/ instead (where the IP is shown below the URL column):

    $ docker-machine ls
NAME      ACTIVE   DRIVER       STATE     URL
default   *        virtualbox   Running   tcp://<ip>:<port>

  5. To shutdown the services, use docker-compose down.

More Docker

If you just want to run the Zaaktypecatalogus as a Docker container and connect to an external database, you can build and run the Dockerfile and pass several environment variables. See src/ztc/conf/docker.py for all settings.

$ docker build . && docker run \
    -p 8000:8000 \
    -e DJANGO_SETTINGS_MODULE=ztc.conf.docker \
    -e DATABASE_USERNAME=... \
    -e DATABASE_PASSWORD=... \
    -e DATABASE_HOST=... \
    --name ztc

$ docker exec -it ztc /app/src/manage.py createsuperuser

Loading initial data

The container will load any fixtures it can find at startup time. The default location is /app/fixtures, so you can mount a volume containing JSON fixtures to populate your database initially.

You can override this location through the FIXTURES_DIR environment variable. Only *.json files are considered.

Developers

Prerequisites

You need the following libraries and/or programs:

  • Python 3.4 or above
  • Python Virtualenv and Pip
  • PostgreSQL 9.1 or above

Setting up your local development environment

For developers who are familiar with Django, this project should be straight forward to set up.

  1. Grab the code.

  2. Create a PostgreSQL database and database user. By default, the database, database user, and password are all ztc.

  3. Create and activate your virtual environment:

    $ virtualenv env
$ source env/bin/activate

  4. Install all required Python libraries:

    $ pip install -r requirements/dev.txt

  5. Copy src/ztc/conf/local_example.py to src/ztc/conf/local.py and modify it to your likings.

  6. Link the static files, create the database tables and load initial data:

    $ python src/manage.py collectstatic --link
$ python src/manage.py migrate

  7. Create a super user:

    $ python src/manage.py createsuperuser

  8. Start the webserver:

    $ python src/manage.py runserver

  9. Done!

You can find the API documentation at:

You can find the admin interface at:

API Access token

The API requires a valid access token. You can generate one in the admin at http://localhost:8000/admin/oauth2_provider/accesstoken/, with scope read write.

Next, configure your API Client (Postman) or similar to use the auth: add the header Authorization: Bearer <token>.

Testsuite

To run the test suite:

$ pip install -r requirements/dev.txt
$ python src/manage.py test ztc

Settings

All settings for the Zaaktypecatalogus can be found in src/ztc/conf. The file local.py overwrites settings from the base configuration.

There are no specific settings for the Zaaktypecatalogus. See Django Rest Framework settings for all API related settings.

Commands

Commands can be executed using:

$ python src/manage.py <command>

There are no specific commands for the Zaaktypecatalogus. See Django framework for all default commands, or type python src/manage.py --help.