Edit page in Livemark
(2024-12-18 16:42)

Installation

The following section explains installation options, followed by environment variables you can use to tweak your installation. See also the README guide.

Overview

The core of Dribdat is developed in Python, with an API based on open standards: Linked Data (JSON-LD), Web-friendly metadata (Schema.org), data packages (Frictionless Data), and web authentication (OAuth). A range of integrations are available to enable sending e-mails, uploading files, or activating AI coaches.

There are several frontends available, from the default web site in Bootstrap, to a Vue.js-based Single Page App (Backboard), an older multiplatform chatbot (Dridbot) and a new Tailwind-based dashboard (Rustboard).

With all these options, you might be wondering: what is a good way to start? This page should help you with a basic installation of Dribdat in a short time.

Please keep in mind that our Open Collective is a great way to contribute or get additional support from the maintainers!

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 Docker

Containerized Docker builds are available at Docker Hub. 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.

With Docker Compose

We also provide a couple of other Docker Compose configurations: for example, you can instantiate a lightweight SQLite version like this:

docker compose -f docker-compose.sqlite.yml up -d

For a first-time setup, you may need to 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.

With Ansible

Use the dribdat Ansible role for a straightforward production deployment using Ansible. Thanks to Mint Systems for maintaining these scripts.

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

From source

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.

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 (if an e-mail server is configured, they can still use that), and registrations with DRIBDAT_NOT_REGISTER

E-mail activation or moderation (activation in admin area) of non-SSO accounts can be forced with DRIBDAT_USER_APPROVE

You can find more advice in the Troubleshooting guide.

Spam shield

To try to reduce spam issues on your Dribdat instance, we encourage you to use an OAuth provider (as above) with competency in this area. Basic form validation using Google Recaptcha and compatible providers like Friendly Captcha, is available:

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;
  }
}