Skip to main content

Self-hosted DBtune

Background​

DBtune offers a self-hosted deployment option for enterprise customers. Self-hosting is particularly valuable in two scenarios:

  • For organizations requiring an air-gapped environment due to regulatory compliance and information security requirements. If you are not sure if you need an air-gapped environment, you don’t need an air-gapped environment.
  • For cases needing specific customizations or integrations that are only possible in a self-managed environment. For example, if you are a software provider you may want to integrate your service more tightly with the DBtune optimizer. This is common for partners who adopt a value added reseller (VAR) or original equipment manufacturer (OEM) commercial model.

The self-hosted deployment delivers the complete feature set of the DBtune SaaS while giving you the added benefits of enhanced security, customization options, and infrastructure control. However, your team will be responsible for maintenance, updates, and infrastructure management.

How to host​

  1. Setup Requirements
  • self-hosted.zip - We will provide a ./docker-compose.yml, ./.env.self-hosted and a ./setup-self-hosted.sh file.
  • Github - We will provide access to your github account to pull the necessary images.
  • docker - This is used fetch and run the required images.
  • docker-compose - Deploy the stack as well as configure volumes and networking.
  • gh CLI - This is 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.5.11
  • Please note, this version may not reflect the latest stable version. If updating, please 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 UI's 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 setup as it normally done with DBtune Saas platform, where the agent is run outside of the docker-network, communicating via the open 8000 port.

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

Please note that this 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 GoLang.

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