Deploy Apache Superset with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it practical to self-host Apache Superset as your business intelligence and data visualization platform.

This guide walks you through deploying the full Superset stack: the web application, Celery background workers, PostgreSQL metadata database, Redis cache, and automatic HTTPS.

Prerequisites

• A VPS with at least 4 vCPUs, 4 GB RAM, and 20 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., superset.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  superset:
    image: apache/superset:latest
    restart: unless-stopped
    ports:
      - "8088:8088"
    environment:
      - SUPERSET_SECRET_KEY=${SUPERSET_SECRET_KEY}
      - DATABASE_HOST=superset-db
      - DATABASE_PORT=5432
      - DATABASE_DB=superset
      - DATABASE_USER=superset
      - DATABASE_PASSWORD=${DB_PASSWORD}
      - REDIS_HOST=superset-redis
      - REDIS_PORT=6379
      - SQLALCHEMY_DATABASE_URI=postgresql://superset:${DB_PASSWORD}@superset-db:5432/superset
      - CELERY_RESULT_BACKEND=redis://superset-redis:6379/0
      - CELERY_BROKER_URL=redis://superset-redis:6379/1
    volumes:
      - ../files/superset-home:/app/superset_home
    depends_on:
      superset-db:
        condition: service_healthy
      superset-redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8088/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 120s

  superset-init:
    image: apache/superset:latest
    restart: "no"
    environment:
      - SUPERSET_SECRET_KEY=${SUPERSET_SECRET_KEY}
      - SQLALCHEMY_DATABASE_URI=postgresql://superset:${DB_PASSWORD}@superset-db:5432/superset
      - ADMIN_USERNAME=${ADMIN_USERNAME:-admin}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - ADMIN_EMAIL=${ADMIN_EMAIL:-admin@example.com}
    depends_on:
      superset-db:
        condition: service_healthy
    command: >
      bash -c "
        superset db upgrade &&
        superset fab create-admin --username $${ADMIN_USERNAME} --firstname Admin --lastname User --email $${ADMIN_EMAIL} --password $${ADMIN_PASSWORD} || true &&
        superset init
      "

  superset-worker:
    image: apache/superset:latest
    restart: unless-stopped
    command: ["celery", "--app=superset.tasks.celery_app:app", "worker", "--pool=prefork", "-O", "fair", "-c", "2"]
    environment:
      - SUPERSET_SECRET_KEY=${SUPERSET_SECRET_KEY}
      - SQLALCHEMY_DATABASE_URI=postgresql://superset:${DB_PASSWORD}@superset-db:5432/superset
      - CELERY_RESULT_BACKEND=redis://superset-redis:6379/0
      - CELERY_BROKER_URL=redis://superset-redis:6379/1
    depends_on:
      superset-db:
        condition: service_healthy
      superset-redis:
        condition: service_healthy

  superset-beat:
    image: apache/superset:latest
    restart: unless-stopped
    command: ["celery", "--app=superset.tasks.celery_app:app", "beat", "--pidfile=/tmp/celerybeat.pid", "-s", "/tmp/celerybeat-schedule"]
    environment:
      - SUPERSET_SECRET_KEY=${SUPERSET_SECRET_KEY}
      - SQLALCHEMY_DATABASE_URI=postgresql://superset:${DB_PASSWORD}@superset-db:5432/superset
      - CELERY_RESULT_BACKEND=redis://superset-redis:6379/0
      - CELERY_BROKER_URL=redis://superset-redis:6379/1
    depends_on:
      superset-db:
        condition: service_healthy
      superset-redis:
        condition: service_healthy

  superset-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=superset
      - POSTGRES_USER=superset
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - ../files/superset-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U superset"]
      interval: 10s
      timeout: 5s
      retries: 5

  superset-redis:
    image: redis:7-alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

Note: The superset-init container runs once on first deployment to initialize the database schema and create the admin user, then exits. On subsequent deployments it will attempt to run again but the || true ensures it doesn't fail if the admin already exists.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
SUPERSET_SECRET_KEY	Flask secret key for session encryption	openssl rand -base64 42 output
DB_PASSWORD	PostgreSQL database password	a-strong-random-password
ADMIN_USERNAME	Initial admin username	admin
ADMIN_PASSWORD	Initial admin password	a-strong-admin-password
ADMIN_EMAIL	Admin user email	admin@yourdomain.com

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you. Generate SUPERSET_SECRET_KEY by running openssl rand -base64 42 on your server. This key must remain consistent across deployments.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/superset-home — Superset home directory (custom configs, uploaded dashboards)
• ../files/superset-db-data — PostgreSQL database files (dashboards, charts, data source configs)

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths because Dokploy may clean them during redeployment.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., superset.yourdomain.com)
3. Set the container port to 8088
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your Superset container.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — the init container should run first, then all other services start
3. Check the Logs tab for superset-init. Look for: Superset initialized after database migrations complete
4. Check the Logs tab for superset. Look for: Running on http://0.0.0.0:8088
5. Open https://superset.yourdomain.com in your browser — you should see the Superset login page
6. Log in with your ADMIN_USERNAME and ADMIN_PASSWORD credentials

Troubleshooting

Superset shows "Internal Server Error" on first visit The init container may still be running database migrations. Wait for superset-init to complete, then restart the main superset container. Check the init container logs for migration progress.

Dashboard reports and scheduled queries not running Ensure both superset-worker and superset-beat containers are healthy. The worker processes async tasks while beat schedules them. Check their logs for Redis connection errors.

Cannot connect to external databases To connect Superset to external data sources, you may need to install additional database drivers. Create a custom Docker image extending apache/superset with pip install for your database driver (e.g., mysqlclient, clickhouse-driver).

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about Apache Superset in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running Apache Superset.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.