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​

  1. Setup requirements
  • self-hosted.zip — DBtune will provide a ./docker-compose.yml, ./.env.self-hosted and a ./setup-self-hosted.sh file.
  • GitHub — DBtune will provide access to your GitHub account to pull the necessary images.
  • docker — Used to fetch and run the required images.
  • docker-compose — Deploys the stack and configures volumes and networking.
  • gh CLI — Used to fetch a token for authentication so Docker can pull the necessary images.
  • jq (optional) — Command line utility for parsing JSON responses from gh, can be substituted with a manual step.
  1. Clone or download the release
  • Unpack/copy the self-hosted.zip directory to your server.
  1. GHCR authentication (required)
  • Before pulling images, log in to GitHub Container Registry with docker. 
    gh auth refresh --scopes read:packages # required for docker to pull images
    GH_USERNAME=$(gh api user --jq .login)  # You can simply replace with your gh username
    gh auth token | docker login ghcr.io -u "$GH_USERNAME" --password-stdin
  • You can verify this worked by pulling the image: 
    docker pull --platform linux/amd64 ghcr.io/dbtuneai/dbtune-platform:3.14.13
  • This version may not reflect the latest stable version. If updating, refer to the available package versions at:
    • https://github.com/dbtuneai/dbtune-platform/pkgs/container/dbtune-platform
    • https://github.com/dbtuneai/dbtune-platform/pkgs/container/dbtuner
  1. Run the setup helper (recommended)
  • This script will generate secure values (e.g., DJANGO_SECRET_KEY, DJANGO_SUPERUSER_API_KEY) and prompt you for required fields (superuser email, password etc.).
cd self-hosted
chmod +x ./setup-self-hosted.sh
./setup-self-hosted.sh
  1. Configure environment variables
  • Open the included .env.self-hosted file.
  • Read the instructions/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
  • Ensure the docker-compose.yml contains the dbtune-platform and dbtuner image versions you wish to use.
  • Run: 
    docker compose --env-file .env.self-hosted up -d
  • Only the main web interface (default port 8000) is open externally. You have the option to expose the influx and prefect-server to access their UIs if required.
  • 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
  • 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.

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