Edit page in Livemark
(2024-11-18 23:56)

Installation

This document contains additional information on deploying dribdat to a web server.

Quickstart

The following section explains installation options, followed by environment variables you can use to tweak your installation. See also the README guide, and our new frontend microservice Backboard.

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.

Cloud scripts

The installation of dribdat on some cloud providers has been facilitated with quick-deploy scripts. See Configuration below for a list of variables you can set to customize your instance.

With Ansible

Use the dribdat Ansible role for a straightforward production deployment using Ansible.

See Configuration below for a list of variables you can set to customize your instance.

With Docker

Containerized Docker builds are available at https://hub.docker.com/r/dribdat/dribdat

To deploy dribdat using a local Docker or Podman build, 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

See Configuration below for a list of variables you can set to customize your instance.

From source

See deployment notes in the Developer guide for more information on setting up your build.

Configuration

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

Features

The following environment variables 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). The following providers are supported:

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

You may then wish to disable non-SSO logins using DRIBDAT_ALLOW_LOGINS and registrations with DRIBDAT_NOT_REGISTER - or at least enable moderation of non-SSO accounts with DRIBDAT_USER_APPROVE and an SMTP provider for e-mail activation.

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:

See example connection in the Troubleshooting guide.

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).

Large language model

If you would like to enable automated challenge and AI-enhanced project suggestions, you can connect OpenAI or compatible service, for example the API endpoint of LM Studio, or the LiteLLM proxy.

Advanced server settings

These parameters can be used to improve the production setup:

Tips for your deployment

Here are some additional instructions for your installation. See also the troubleshooting and contributing docs.

Custom default 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.

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 (if your files are in /srv/dribdat)
    alias /srv/dribdat/dribdat/static;
    expires 2d;
  }
}