Skip to main content

Self-hosted DBtune on Docker Compose

Overview​

DBtune can be self-hosted on a single VM using Docker Compose. This is the simplest deployment option, recommended if you are not running Kubernetes.

If you are running a Kubernetes cluster, see the Kubernetes self-hosted guide instead. For general background on self-hosting, see the self-hosted deployment overview.

How to host​

The self-hosted platform ships as a single offline bundle — dbtune-self-hosted-<version>.tar — that already contains every image alongside the compose stack. No container registry access is required, which makes it suitable for air-gapped environments.

Once DBtune has enabled self-hosting for your organization, the bundle is available to download directly from the platform: open your organization page and download the latest self-hosted release. That single archive is everything you need.

  1. Setup requirements
  • dbtune-self-hosted-<version>.tar — the bundle downloaded from your organization page. It contains all images plus docker-compose.yml, .env.self-hosted, load-images.sh and setup-self-hosted.sh.
  • A Linux host (x86_64).
  • docker (Engine 24+ with the Compose v2 docker compose subcommand), or podman with podman-compose — runs the stack and configures volumes and networking.
  1. Download and extract the bundle
  • Download dbtune-self-hosted-<version>.tar from your organization page in the platform, copy it to your server, then unpack it: 
    tar -xf dbtune-self-hosted-<version>.tar
    cd dbtune-self-hosted-<version>
  1. Load the bundled images
  • Every image ships inside the bundle, so there is no registry login or docker pull. 
    ./load-images.sh docker    # or: ./load-images.sh podman
  1. Run the setup helper (recommended)
  • Generates secure values (e.g. DJANGO_SECRET_KEY, DJANGO_SUPERUSER_API_KEY) and prompts for required fields (FRONTEND_URL, superuser email and password). 
    chmod +x ./setup-self-hosted.sh
    ./setup-self-hosted.sh
  1. Configure environment variables
  • Open the included .env.self-hosted file.
  • Read the comments in that file and fill in the CHANGEME fields with your actual values.
  • Pay special attention to:
    • Database, password, and secret key settings.
    • SMTP/email settings for password reset and notifications.
  1. Start the platform
  • The bundle already pins every image version, so no manual tag editing is required. 
    docker compose --env-file .env.self-hosted up -d
  • Only the main web interface (default port 8000) is open externally. You may optionally expose influxdb and prefect-server to access their UIs.
  • All other components communicate privately inside Docker.
  1. Access the application
  • Visit http://your-server:8000 (replace with your server address or port).
  • Log in with your configured superuser (see .env.self-hosted).

System Requirements​

The images used are the following:

  • postgres - Primary database for most operations.
  • influx - Timeseries database.
  • redis - KV cache
  • dbtune-platform - The main platform application
  • dbtuner - The optimization service
  • dbtune-indigo - Index recommendation engine (self-contained; runs its own ephemeral PostgreSQL internally, no external database required)
  • prefect - Distributed task scheduling

System requirements primarily scale according to the number of connected databases, and concurrent tuning sessions. Services gracefully degrade under load spikes, but monitoring is advised.

An air-gapped setup for 5-10 databases with 1-2 concurrent tuning sessions, where gaurantee of low latency is not a concern when under load.

  • Minimal: (2vCPU, 8GB RAM)
  • Recommended: (4vCPU, 16GB RAM)

When scaling for your requirements, please monitor usage and adjust accordingly.

Email/SMTP Setup​

  • Real email (SMTP) is required for password resets and notifications.
  • Enter your SMTP provider's details in the environment file. Example for Gmail: 
    EMAIL_HOST=smtp.gmail.com
    EMAIL_PORT=587
    EMAIL_USE_TLS=True
    EMAIL_FROM=your@email.com
    EMAIL_HOST_PASSWORD=your-app-password
  • If your organization uses another provider (Exchange, Office365, SES, etc.) fill in those corresponding details.
  • We do not recommend using test relays or Mailpit in production.

Other notes​

  • Ensure required ports are open (default: 8000 for web).
  • For advanced features, SSO, or customization, contact support or see extended documentation.

Upgrade​

Data (postgres_data, influxdb-data, prefect-data, redis-data) lives under ./volumes/ inside each bundle's own folder — it is not a Docker-managed volume shared across versions. Extracting the new bundle into a fresh directory starts that directory's ./volumes/ empty. Skipping step 2 below will bring the new version up with a blank database.

  1. Download the latest self-hosted bundle from your organization page and extract it alongside the old one, then cd into it. Do not run docker compose up yet.
  2. Copy your data across: cp -R ../<old-bundle-dir>/volumes ./volumes.
  3. Load the new images: ./load-images.sh docker (or podman).
  4. Reconcile your config, don't blind-copy it. Diff your old .env.self-hosted against the new bundle's and carry your values into the new file, keeping any keys the release added. A release can introduce new required variables; compose reads them as ${VAR:?}, so a missing key fails docker compose up immediately rather than starting on a stale value.
  5. Carry over the secrets your data was created with — POSTGRES_PASSWORD, PREFECT_DB_PASSWORD, INFLUXDB_INIT_PASSWORD, INFLUXDB_TOKEN — not just user-facing settings like FRONTEND_URL. If you run ./setup-self-hosted.sh on the new bundle, it regenerates these randomly; overwrite them with the originals afterward, or the new containers can't authenticate against the copied data.
  6. Apply: docker compose --env-file .env.self-hosted up -d. Compose recreates the changed containers against the copied data.

The bundle already pins every image version, so there is nothing to look up manually.

DBtune agent​

The DBtune agent can be set up as it is normally done with the DBtune SaaS platform, where the agent runs outside of the Docker network, communicating via the open 8000 port.

If you wish to host the DBtune agent inside the Docker network via docker compose alongside the platform stack, you will need to update the server_url to point to the web container inside the Docker Compose network.

The agent is the same as the agent in the SaaS solution — more information can be found in the DBtune documentation. The agent is open-source and written in Go.

Programmatic access​

The DBtune REST API enables you to programmatically retrieve database information and recommendations. The API uses resource-oriented URLs, returns request responses in JSON format, and uses standard HTTP status codes.

To get started, please refer to the DBtune API documentation.

Security​

The self-hosted deployment of DBtune works in an air-gapped environment, requiring no internet access. This makes it ideal for enterprise offline deployments.

Last updated on