Edit page in Livemark
(2022-12-02 12:00)

This document contains additional information on deploying dribdat.

Deployment guide

The following section details environment variables you can add to tweak your installation. See also the README guide, and our new frontend microservice Backboard.

With Python

Details on starting the application directly with Python are detailed in the Developer guide. You will still want to refer to the Configuration section below.

With Docker (recommended)

To deploy dribdat using Docker or Podman, use the included docker-compose.yml file as a starting point. This, by default, persists the PostgreSQL database outside the container, on the local filesystem in the .db folder.

For a first-time setup, perform the initial migrations as follows:

docker-compose run --rm dribdat ./release.sh

At this point you should be ready to start with Docker Compose:

docker-compose up -d

With cloud hosting

We have battle-tested and tweaked installation of dribdat with the following cloud providers:

Deploy on Heroku

Deploy with Vercel

Deploy with Linode

Configuration

Optimize your dribdat instance with the following environment variables in production:

Server settings

These parameters can be used to improve the production setup:

Features

The following options can be used to toggle application features:

Statistics

Support for Web analytics can be configured using one of the following variables:

If you are required by law to use a cookie warning or banner, you can add this through your community code configuration.

Mail

If you would like people to be able to activate their accounts and reset passwords, you can connect to an SMTP mailing service (use Mailgun, or any other). Note that this is not really needed when you use OAuth (see next session) and disable registration completely.

Authentication

OAuth 2.0 support for Single Sign-On (SSO) is currently available using Flask Dance, and requires SSL to be enabled (using SERVER_SSL=1 in production or OAUTHLIB_INSECURE_TRANSPORT in development). You may wish to disable non-SSO logins using DRIBDAT_NOT_REGISTER.

Register your app with the provider, and set the following variables:

You can find more advice in the Troubleshooting guide.

File storage

For uploading images and other files directly within dribdat, you can configure S3 through Amazon and compatible providers:

Due to the use of the boto3 library for S3 support, there is a dependency on OpenSSL via awscrt. If you use these features, please note that the product includes cryptographic software written by Eric Young (eay@cryptsoft.com) and Tim Hudson (tjh@cryptsoft.com).

Custom content

To customize some of the default content, you can edit the template include files in the folder dribdat/templates/includes, for example you will find there the default quickstart.md and stages.yaml definitions.

Make sure your changes will not be overwritten is you are using ephemeral storage (e.g. Heroku) for your deployment. In a future release we may provide an environmental variable for configurations hosted elsewhere. For now, copy the files from a secure location during a deployment step.

Using a proxy server

We encourage the use of Gunicorn to run the application in production. Here is an example with 4 workers:

gunicorn -w 4 -b 127.0.0.1:5000 "dribdat.app:init_app()"

A web proxy server is typically also used in production to optimize your deployment, add SSL certificates, etc. Here is an example configuration using nginx if you are running your application on port 5000:

upstream dribdat-cluster {
  server localhost:5000;
}
server {
  listen 80;
  server_name my.dribdat.net;

  # File size limit for uploads
  client_max_body_size 10m;
  keepalive_timeout 0;
  tcp_nopush on;
  tcp_nodelay on;

  # Configure compression
  gzip on; gzip_vary on;
  gzip_types text/plain text/css application/x-javascript text/xml application/xml application/xml+rss text/javascript;

  location / {
    # In case archived URLs were bookmarked
    rewrite ^(.*).html$ $1;
    # Set up the Proxy
    proxy_redirect off;
    proxy_pass http://dribdat-cluster;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP  $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  location /static {
    # To host assets directly from Nginx
    expires 2d;
    alias /srv/dribdat/dribdat/static;
  }
}