If your team is spending hours exporting CSVs and building manual reports, you're in the right place. This guide shows you how to deploy Apache Superset on Ubuntu 24.04 using Docker Compose - with Nginx as a reverse proxy, a free HTTPS certificate from Let's Encrypt, and a data source connected via a read-only user. Superset works with 81+ databases including PostgreSQL, MySQL, MariaDB, SQL Server, Snowflake, BigQuery, and more - the steps are the same regardless of which database you connect.
What this guide uses: Ubuntu 24.04 (Linux) as the host OS and AWS RDS MySQL as the data source. These are examples - see the sections below on how to adapt for Windows, other Linux distros, and other databases.
What Is Apache Superset?
Apache Superset is an open-source business intelligence platform that lets users explore data in a connected SQL database and build charts and dashboards directly in the browser - no code required. It is comparable to Tableau or Power BI, released under the Apache 2.0 licence, and used in production at companies like Airbnb, which runs Superset inside Kubernetes serving over 600 daily users.
Superset does not store your reporting data. It sends queries to the database you connect, receives the results, and draws them as charts. Its own metadata database only holds users, saved charts, dashboards, and connection settings - your actual business data never moves.
Key Features
- No-code chart builder - pick a dataset, choose a chart type, set metrics and filters. Dozens of chart types: bar, line, pie, tables, maps, heatmaps, scatter, and more.
- SQL Lab - a built-in SQL editor for ad-hoc queries, with query history and the option to turn any result into a chart.
- Dashboards - combine charts on one page with shared filters and cross-filtering between charts.
- Semantic layer - define calculated columns and reusable metrics so everyone reports from the same numbers.
- Wide database support - connects to PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, Amazon RDS, Redshift, BigQuery, Snowflake, ClickHouse, Databricks, Hive, Presto, Trino, and 60+ more.
- Security and roles - built-in roles (Admin, Alpha, Gamma, SQL Lab) with per-dataset permissions. Supports OAuth, LDAP, and SSO.
- Caching - query results can be cached in Redis to reduce load on the source database.
- REST API and embedding - automate administration and embed dashboards in other applications.
Typical Uses
- Operational and business dashboards - bookings, revenue, traffic, or KPIs over time.
- Ad-hoc data exploration by analysts and developers using SQL Lab.
- Replacing manual spreadsheet reports with always-current dashboards accessible from a link.
- Giving non-technical users self-service access to selected tables, with a read-only database user.
What Databases Can Superset Connect To?
According to the official Superset database documentation, Superset supports 81 databases with varying levels of feature support. Every database that has a Python DB-API driver and a SQLAlchemy dialect can be connected.
The most commonly connected databases and their drivers:
Database | Driver Package | SQLAlchemy URI Format |
PostgreSQL / RDS PostgreSQL | psycopg2-binary | postgresql+psycopg2://user:pass@host:5432/db |
MySQL / RDS MySQL | pymysql cryptography | mysql+pymysql://user:pass@host:3306/db |
MariaDB | pymysql | mysql+pymysql://user:pass@host:3306/db |
Amazon Redshift | sqlalchemy-redshift | redshift+redshift_connector://user:pass@host:5439/db |
Google BigQuery | sqlalchemy-bigquery | bigquery://project/dataset |
Snowflake | snowflake-sqlalchemy | snowflake://user:pass@account/db |
Microsoft SQL Server | pymssql | mssql+pymssql://user:pass@host:1433/db |
The key principle: each database needs its own driver installed inside the Superset Docker image. Step 2.2 shows how to do this. The same process applies for every database - you just change the driver package name and the SQLAlchemy URI.
Where Can Superset Be Installed?
Superset runs wherever Docker runs. This guide uses Ubuntu 24.04 on a Linux server, but the Docker Compose stack works on:
Host Environment | Notes |
Ubuntu / Debian Linux | This guide - the most common self-hosted path |
RHEL / CentOS / Amazon Linux | Replace apt commands with yum/dnf; Docker steps are identical |
Windows (via Docker Desktop) | Install Docker Desktop for Windows, then run the same docker compose commands in PowerShell or WSL2 |
macOS (via Docker Desktop) | Install Docker Desktop for Mac, then run the same commands in Terminal |
Any cloud VM | AWS EC2, GCP Compute Engine, Azure VM, DigitalOcean - all work the same way |
Kubernetes | Recommended for large-scale production; use the Apache Superset Kubernetes Operator |
The Nginx and Let's Encrypt steps in this guide are Linux-specific. On Windows or macOS locally, skip those and access Superset directly at http://localhost:8088.
Installation Methods
The official Superset documentation describes three installation routes:
Method | Best For | Trade-off |
Docker Compose (this guide) | Pilots, small teams, development | Simpler than Kubernetes. You maintain the Compose files and back up the metadata DB yourself. Less robust than Kubernetes for large-scale production. |
Kubernetes | Production at scale | Best-practice approach (docs recommend the Apache Superset Kubernetes Operator). Needs Kubernetes skills. Supports autoscaling and zero-downtime rolling updates. |
PyPI (Python) | Environments without containers | No container knowledge needed, but the most hands-on work to deploy and maintain each component. |
For related context on running Docker workloads securely on a shared server, see our guide on [INTERNAL LINK: Docker security hardening for shared Ubuntu servers].
Prerequisites
Before starting, confirm the following:
- A server running Ubuntu 24.04 (or adapt commands for your OS - see the OS table above)
- A DNS A record for your domain (e.g. superset.example.com) pointing to your server's public IP
- Ports 80 and 443 open to the internet (needed for certificate issuance and renewal)
- Port 8088 must not be public - it will be bound to localhost only
- Nginx installed (sudo apt install -y nginx)
- A data source database reachable from the server (MySQL on port 3306, or PostgreSQL on port 5432, etc.)
Step 1 - Install Docker and Docker Compose
Install Docker from the official repository:
Cap container logs immediately - uncapped logs can fill the disk and take down other services:
Step 2 - Create the Superset Project Directory
Pin a specific release version - never use latest or master tags in production.
- Environment File
Generate secrets directly into the file so they never appear in terminal output or shell history:
- Dockerfile (Install the Database Driver)
The official Superset image does not include database drivers for your data source. Add the driver for whichever database you plan to connect to.
For MySQL / AWS RDS MySQL (this guide):
For PostgreSQL / AWS RDS PostgreSQL - change the driver line to:
For multiple databases at once (e.g. MySQL + PostgreSQL):
After changing the Dockerfile, always rebuild: docker compose build superset && docker compose up -d.
- Superset Configuration
ENABLE_PROXY_FIX = True is required when running behind Nginx - without it, Superset cannot correctly read the client's real IP address from proxy headers.
- Docker Compose File
The mem_limit values protect other workloads on the same server. Superset is bound to 127.0.0.1 only.
- Build, Start and Initialise
All three containers should show Up. Then initialise - enter the admin password at the prompt:
Run these one block at a time. Verify the app is responding locally:
Step 3 - Configure Nginx and HTTPS
- DNS
It must return your server's public IP before proceeding to Certbot.
- Nginx Server Block
Use reload, not restart - on a server hosting other sites, a restart causes a brief outage for all of them.
- HTTPS Certificate
- Secure Cookie Settings
Once HTTPS is confirmed working:
Step 4 - Connect a Data Source
This section covers how to connect your actual reporting database to Superset. The UI steps are identical for every database type. What changes is the driver you installed in Step 2.2 and the SQLAlchemy URI format.
- Create a Read-Only Database User
Always connect Superset to a read-only user. This prevents any chart query from accidentally modifying data. Use a read replica or reporting copy where one exists.
MySQL / AWS RDS MySQL:
PostgreSQL / AWS RDS PostgreSQL:
If no database client is installed on your server, use a throwaway container:
Make sure the database's security group or firewall allows inbound connections from your Superset server's IP (port 3306 for MySQL, 5432 for PostgreSQL).
- Add the Connection in Superset
The steps are the same for every database type:
- Go to Settings → Database Connections → + Database
- Select your database type from the list, or choose Other to enter a URI manually
- Choose Connect this database with a SQLAlchemy URI string
- Enter the connection URI for your database (see formats below)
- Click Test Connection - if it succeeds, you will see a green confirmation
- Under Advanced, confirm Allow DML is off (this prevents any write operations from the UI)
- Click Connect to save
MySQL / AWS RDS MySQL:
PostgreSQL / AWS RDS PostgreSQL:
On-premise MySQL (use your server's IP or hostname instead of an RDS endpoint):
On-premise PostgreSQL:
URL-encode special characters in the password (@ → %40, # → %23).
- Driver and URI Reference
The table below shows the driver and URI for the most commonly used databases. For all 81 supported databases, see the official Superset database documentation.
Database | Driver (add to Dockerfile) | SQLAlchemy URI |
MySQL / RDS MySQL | pymysql cryptography | mysql+pymysql://user:pass@host:3306/db |
PostgreSQL / RDS PostgreSQL | psycopg2-binary | postgresql+psycopg2://user:pass@host:5432/db |
MariaDB | pymysql | mysql+pymysql://user:pass@host:3306/db |
Amazon Redshift | sqlalchemy-redshift | redshift+redshift_connector://user:pass@host:5439/db |
Google BigQuery | sqlalchemy-bigquery | bigquery://project/dataset |
Snowflake | snowflake-sqlalchemy | snowflake://user:pass@account/db |
MS SQL Server | pymssql | mssql+pymssql://user:pass@host:1433/db |
- Explore Your Data
SQL Lab: Go to SQL → SQL Lab, choose the database from the dropdown, and run a query directly.
Charts: Go to Datasets → + Dataset, pick the database, schema, and table, then create a chart and add it to a dashboard.
Day-to-Day Operations
Task | Command |
Check status | cd /opt/superset && docker compose ps |
View logs | docker compose logs --tail=100 superset |
Check resource usage | docker stats --no-stream |
Restart Superset | docker compose restart superset |
Upgrade | Change VER in .env → docker compose build superset && docker compose up -d → superset db upgrade → superset init |
Full rollback | docker compose down -v (deletes metadata) - remove Nginx block and DNS record |
Security Checklist
Port 8088 is bound to 127.0.0.1 and blocked in the firewall
The initial admin password has been changed after first login
Named user accounts created with appropriate roles (Gamma or Alpha) - not sharing the admin account
Self-registration is off (the Superset default)
The data source user is SELECT-only, limited to the schemas and tables users actually need
.env is backed up and never committed to version control
The metadata DB volume (db_data) is included in server backups
For managing backups of Docker volumes, see our guide on [INTERNAL LINK: backing up Docker volumes and container data on Ubuntu].
Troubleshooting
Symptom | Cause | Fix |
Container restarts: No module named 'MySQLdb' | MySQL driver not installed | Add pymysql to Dockerfile (Step 2.2) and rebuild |
Container restarts: No module named 'psycopg2' | PostgreSQL driver not installed | Add psycopg2-binary to Dockerfile and rebuild |
exec fails: 'container is restarting' | App is crash-looping | Run docker compose logs --tail=60 superset to find the real error first |
create-admin rejects the command | --email flag is missing | Any email address is accepted - the flag is required |
Test Connection times out | DB security group blocks Superset server | Add inbound rule allowing the Superset server's IP on port 3306 or 5432 |
Test Connection: access denied | Wrong credentials or host pattern mismatch | Recheck the user GRANT and that the @'host' matches the server's IP |
Certbot fails | A record not live, or ports 80/443 blocked | Run dig +short yourdomain.com - must return server IP first |
Login loops | SESSION_COOKIE_SECURE is on while site is still HTTP | Disable it until HTTPS is confirmed working |
Memory pressure on shared host | Containers have no memory ceiling | Keep mem_limit values in the Compose file |
FAQ
Does Superset work with PostgreSQL (psql)?
Yes - PostgreSQL is one of the best-supported databases in Superset. Install psycopg2-binary in the Dockerfile (Step 2.2) and use the postgresql+psycopg2:// URI format. This works for on-premise PostgreSQL, AWS RDS PostgreSQL, AWS Aurora PostgreSQL, Google AlloyDB, and any PostgreSQL-compatible database.
Can I install this on Windows?
Yes. Install Docker Desktop for Windows, then run the same docker compose commands in PowerShell or WSL2. The Nginx and Let's Encrypt steps in this guide are Linux-specific - on a local Windows machine you would access Superset directly at http://localhost:8088 without Nginx.
Can I connect more than one database?
Yes. Each database connection is independent. Go to Settings → Database Connections and add as many sources as needed. Each one needs its driver installed in the Dockerfile. If you add a new driver later, rebuild the image: docker compose build superset && docker compose up -d.
Does Superset store my business data?
No. Superset only stores its own metadata - users, saved charts, dashboards, and connection settings. The actual data stays in your connected database. Every chart runs a live query against that database when loaded.
What's the difference between Alpha and Gamma roles?
Alpha users can create and manage their own charts, dashboards, and database connections. Gamma users can only view and interact with dashboards they have been given access to. For most business end users, Gamma is the right role
What happens if I change the SUPERSET_SECRET_KEY?
All stored database credentials become unreadable and must be re-entered manually. Treat the secret key like an encryption master key - back it up and never rotate it casually.
Conclusio
Deploying Apache Superset with Docker Compose gives teams a self-hosted BI platform they control completely - no per-seat licensing, no data leaving the network, and support for virtually any SQL database you're already running. Whether you're connecting MySQL on AWS RDS, a self-hosted PostgreSQL server, or planning to add Snowflake and BigQuery later, the connection process is the same five steps in the Superset UI. You just need the right driver in the Docker image.
