Local development server¶

The following instructions assume that you have are using Linux or OSX. For instructions under Windows, please help us by adapting them and filing a pull request.

Clone the Quetzal repository:

$ git clone git@github.com:quetz-al/quetzal.git

Install Docker. Make sure you are able to create Docker images by following the test Docker installation instructions.
Create a virtual environment with your favorite virtual environment manager, but make sure it is a Python 3 environment. Then, install the requirement libraries:
```
$ python3 -m venv ${HOME}/.virtualenvs/quetzal-env
$ source ${HOME}/.virtualenvs/quetzal-env/bin/activate
$ pip install -r requirements-dev.txt
```

At this point, you will need to prepare your Google Cloud Platform credentials (if you are going to use Google buckets to save data files) and prepare SSL certificates.

Google Cloud Platform¶

Using Google buckets to save data needs some preparations described in Google Cloud Platform preparations. For a development server you need to follow the Project, Credentials and APIs instructions.

SSL¶

Quetzal uses HTTPS for all its API operations. This needs a SSL certificate that can be generated as follows.

First, create a SSL key and certificate using openssl:

$ mkdir -p conf/ssl
$ openssl req -x509 -newkey rsa:4096 \
  -keyout conf/ssl/mysite.key -out conf/ssl/mysite.crt \
  -days 365 -nodes

Optionally, but highly recommended, generate a DH exchange key prime number:

$ openssl dhparam -out conf/ssl/dhparam.pem 2048

Note that these are auto-signed keys and they are only suitable for a development or testing scenario. When deploying on a production server, the recommended approach is to use Let’s Encrypt as a certificate authority and CertBot to obtain the final, signed certificates. However, you will still need these auto-signed keys as a temporary solution until CertBot runs the first time.

Docker-compose¶

We are almost ready to have a Quetzal development server ready. This local server runs as a multi-container application managed by docker-compose.

Read the configuration entries in config.py and change them accordingly in the docker-compose.yaml file.

If you are going to use Google buckets to store data, follow the instructions concerning the Google Cloud Platform and verify the configuration variables with the QUETZAL_GCP_ prefix.

If you prefer saving your files locally, set the QUETZAL_DATA_STORAGE to 'file' and ignore the instructions related to Google Cloud Platform.
Build your docker-compose services:
```
$ docker-compose build
```
Run Quetzal through docker-compose:
```
$ docker-compose up
```
If this the first time you run Quetzal, you need to setup the database, create some roles and users. You can do this while the server is running with the following script:
```
$ docker-compose exec web ./init.sh
```

Usage notes¶

If you want to stop the Quetzal application, use:

$ docker-compose stop

To reset and erase the Quetzal application, use:

$ docker-compose down

Warning

Using docker-compose down will erase your database. You will lose your data. Use this only to reset and start a fresh Quetzal application.