Danse !

La carte d'un incroyable territoire chorégraphique

Table of content

• Give a try
• Installation
• Deployment
• Structure
• Development

Give a try

On a Debian-based host - running at least Debian Stretch:

$ sudo apt install python3 virtualenv git make
$ git clone https://forge.cliss21.org/cliss21/danse
$ cd danse/

$ make init
A configuration will be created interactively; you can uncomment:
 ENV=development

$ make serve

Then visit http://127.0.0.1:8000/ in your web browser.

Installation

Requirements

On a Debian-based host, you will need the following packages:

• python3
• GDAL < 3.0 (e.g. libgdal20 in Debian Buster)
• python3-psycopg2 (in case of PostgreSQL database with PostGIS extension)
• libsqlite3-mod-spatialite (in case of SQLite database)
• virtualenv
• make
• git (recommended for getting the source)

Quick start

It assumes that you already have the application source code locally - the best way is by cloning this repository - and that you are in this folder.

1. Define your local configuration in a file named config.env, which can be copied from config.env.example and edited to suits your needs.

   Depending on your environment, you will have to create your database and the user at first.

2. Run make init.

   Note that if there is no config.env file, it will be created interactively.

That's it! Your environment is now initialized with the application installed. To update it, once the source code is checked out, simply run make update.

You can also check that your application is well configured by running make check.

Deployment

Database

It is recommended to use a PostgreSQL database. Due to the use of GeoDjango, you will have to install PostGIS extension too. On a Debian-based host, you will need postgis in addition of postgresql package.

Once the database is created, connect to it using psql and turn it into a spatial database with:

CREATE EXTENSION postgis;

Web application

Here is an example deployment using NGINX - as the Web server - and uWSGI - as the application server.

The uWSGI configuration doesn't require a special configuration, except that we are using Python 3 and a virtual environment. Note that if you serve the application on a sub-location, you will have to add route-run = fixpathinfo: to your uWSGI configuration (from v2.0.11).

In the server block of your NGINX configuration, add the following blocks and set the path to your application instance and to the uWSGI socket:

root <app_instance_path>/frontend/dist;
index index.html;

# Frontend
location / {
  try_files $uri $uri/ @frontend;
}
location @frontend {
  rewrite ^(.+)$ /index.html last;
}

# Backend (Admin & API)
location ~ ^\/admin\/static\/(.*)$ {
  alias <app_instance_path>/var/static/$1;
  # Optional: don't log access to assets
  access_log off;
}
location ~ ^\/(?:admin|api)(?:$|\/) {
  include uwsgi_params;
  uwsgi_pass unix:<uwsgi_socket_path>;
}

# Media files
location ~ ^\/media\/(.*)$ {
  alias <app_instance_path>/var/media/$1;

  expires max;
  add_header Pragma public;
  add_header Cache-Control "public, immutable";
}

# Caching for frontend static files
location ~* \.(?:css|js|woff2?|svg|gif|jpe?g|png)$ {
  etag off;
  expires max;
  add_header Pragma public;
  add_header Cache-Control "public, immutable";
}

Structure

Overview

All the application files - e.g. Django code including settings, templates and statics - are located into danse/.

Two environments are defined - either for requirements and settings:

• development: for local application development and testing. It uses a SQLite3 database and enable debugging by default, add some useful settings and applications for development purpose - i.e. the django-debug-toolbar.
• production: for production. It checks that configuration is set and correct, try to optimize performances and enforce some settings - i.e. HTTPS related ones.

Local changes

You can override and extend statics and templates locally. This can be useful if you have to change the logo for a specific instance for example. For that, just put your files under the local/static/ and local/templates/ folders.

Regarding the statics, do not forget to collect them after that. Note also that the local/ folder is ignored by git.

Variable content

All the variable content - e.g. user-uploaded media, collected statics - are stored inside the var/ folder. It is also ignored by git as it's specific to each application installation.

So, you will have to configure your Web server to serve the var/media/ and var/static/ folders, which should point to /media/ and /static/, respectively.

Development

The easiest way to deploy a development environment is by using the Makefile.

Before running make init, ensure that you have either set ENV=development in the config.env file or have this environment variable. Note that you can still change this variable later and run make init again.

There is some additional rules when developing, which are mainly wrappers for manage.py. You can list all of them by running make help. Here are the main ones:

• make serve: run a development server
• make test: test the whole application
• make lint: check the Python code syntax

License

Danse ! is developed by Cliss XXI and licensed under the AGPLv3+.