How to Install Apache Superset on Ubuntu 24.04 with Docker

Apache Superset is an open-source business intelligence platform: it connects to SQL databases through SQLAlchemy and lets you explore data in SQL Lab, build charts without code and combine them into interactive dashboards. In this tutorial you will run an official Superset release with Docker Compose on Ubuntu 24.04, keep it bound to localhost, publish it through Nginx with a Let's Encrypt certificate, and then connect a PostgreSQL database and build a first chart.

Note

The Superset project documents Docker Compose as a convenient way to run a release on a single machine, not as its reference production architecture (that is the Helm chart on Kubernetes). The setup below suits a small team or an internal analytics server.

Prerequisites

A server running Ubuntu 24.04 LTS with at least 2 vCPUs, 4 GB of RAM (8 GB is more comfortable) and 20 GB of free disk, for example a CubePath VPS.
A non-root user with sudo privileges.
Docker Engine and the Docker Compose plugin installed from Docker's official repository (Compose 2.24 or newer).
A domain name, referred to as your_domain, with an A record pointing to your_server_ip.
UFW enabled with OpenSSH allowed.

Step 1 - Downloading the Superset release

Superset ships its Compose files in the source repository, so you clone it and check out the tag of the release you want to run. Find the latest version on the Superset releases page and use it in place of 5.0.0 below:

cd ~
git clone https://github.com/apache/superset.git
cd superset
git checkout tags/5.0.0

Confirm you are on the tag:

git describe --tags

5.0.0

Checking out the tag matters: the Compose file and the helper scripts under docker/ must match the image version you run.

Step 2 - Setting a secret key and admin password

Default settings live in docker/.env. Instead of editing that tracked file, put your overrides in docker/.env-local, which the Compose files load after docker/.env if it exists.

Generate a random secret key. Superset uses it to sign session cookies and to encrypt database passwords stored in its metadata database, so never change it after the first start:

openssl rand -base64 42

Create the override file:

nano docker/.env-local

Add the following, replacing the placeholders with the generated key and a strong password of your own:

SUPERSET_SECRET_KEY=paste_the_generated_key_here
ADMIN_PASSWORD=your_strong_password
SUPERSET_LOAD_EXAMPLES=yes

ADMIN_PASSWORD is used by the init container when it creates the admin user on first start. SUPERSET_LOAD_EXAMPLES=yes loads sample datasets and dashboards, which is useful to check the installation; set it to no if you do not want them.

Step 3 - Binding Superset to localhost

The Compose file publishes port 8088 on all interfaces. Docker writes its own iptables rules, so a published port is reachable from the Internet even if UFW does not allow it. Since Nginx will be the only public entry point, override the mapping so Superset listens on 127.0.0.1 only.

Create an override file:

nano docker-compose.override-local.yml

services:
  superset:
    ports: !override
      - "127.0.0.1:8088:8088"

The !override tag (Compose 2.24+) replaces the port list instead of appending to it.

Step 4 - Starting Superset

Export the version tag so the Compose file pulls the matching images, then start the stack with both files:

export TAG=5.0.0
docker compose -f docker-compose-image-tag.yml -f docker-compose.override-local.yml up -d

The first start pulls the images, runs the database migrations, creates the admin user and, if enabled, loads the examples. This takes several minutes. Follow the init container until it finishes:

docker compose -f docker-compose-image-tag.yml -f docker-compose.override-local.yml logs -f superset-init

Press Ctrl+C when the log stops and shows the init step as complete. Then check the services:

docker compose -f docker-compose-image-tag.yml -f docker-compose.override-local.yml ps

The superset, superset-worker, superset-worker-beat, db and redis services should be running (and healthy where a health check exists), while superset-init has exited. Confirm the web server answers only on localhost:

curl -s http://127.0.0.1:8088/health

OK

To avoid typing both -f flags every time, you can define a shell alias:

echo "alias sscompose='TAG=5.0.0 docker compose -f $HOME/superset/docker-compose-image-tag.yml -f $HOME/superset/docker-compose.override-local.yml'" >> ~/.bashrc
source ~/.bashrc

The rest of the tutorial uses sscompose.

Step 5 - Publishing Superset through Nginx with HTTPS

Install Nginx and Certbot:

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

Create a server block:

sudo nano /etc/nginx/sites-available/superset

server {
    listen 80;
    listen [::]:80;
    server_name your_domain;

    client_max_body_size 50m;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

The longer read timeout gives slow SQL Lab queries and dashboard loads time to finish. Enable the site, test the configuration and reload Nginx:

sudo ln -s /etc/nginx/sites-available/superset /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Open HTTP and HTTPS in the firewall, then request a certificate:

sudo ufw allow 'Nginx Full'
sudo certbot --nginx -d your_domain

Certbot edits the server block to serve HTTPS and redirect HTTP.

Superset needs to trust the X-Forwarded-* headers from Nginx, otherwise it builds redirect URLs with http://. The Docker setup imports docker/pythonpath_dev/superset_config_docker.py if it exists, so create it:

nano docker/pythonpath_dev/superset_config_docker.py

ENABLE_PROXY_FIX = True

Recreate the containers to apply it:

sscompose up -d --force-recreate

Browse to https://your_domain and log in as admin with the password you set in ADMIN_PASSWORD. If you loaded the examples, the Dashboards menu lists several sample dashboards.

Step 6 - Connecting a PostgreSQL database

The Superset image includes the PostgreSQL driver. Create a read-only user on the database you want to analyze; a reporting tool rarely needs write access. On the database server, for example:

CREATE ROLE superset_ro WITH LOGIN PASSWORD 'your_db_password';
GRANT CONNECT ON DATABASE shop TO superset_ro;
GRANT USAGE ON SCHEMA public TO superset_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO superset_ro;

Make sure the database accepts connections from your_server_ip (listen_addresses and pg_hba.conf on PostgreSQL, plus its firewall).

In Superset, go to Settings > Database Connections > + Database, choose PostgreSQL and fill in host, port, database name, user and password. You can also switch to the SQLAlchemy URI form:

postgresql+psycopg2://superset_ro:your_db_password@db_host:5432/shop

Click Connect. Superset tests the connection before saving it. Under Advanced > SQL Lab you can enable Expose database in SQL Lab; leave Allow DML disabled for a read-only reporting user.

For other engines, add the driver to docker/requirements-local.txt (one pip package per line, for example mysqlclient for MySQL) and recreate the containers with sscompose up -d --force-recreate. The bootstrap script installs those packages when the containers start.

Step 7 - Exploring data in SQL Lab

Open SQL > SQL Lab, select your database and schema, and run a query to confirm Superset can read your tables:

SELECT date_trunc('day', created_at) AS day,
       count(*) AS orders,
       sum(amount) AS revenue
FROM orders
GROUP BY 1
ORDER BY 1 DESC
LIMIT 30;

Run it with Ctrl+Enter. From the result pane you can save the query or create a dataset from it, which makes the result available to charts.

Step 8 - Building a chart and a dashboard

Charts are built on datasets. To register a physical table, go to Datasets > + Dataset, choose the database, schema and table, and click Create dataset and create chart.

Pick a chart type, for example Line Chart, and click Create new chart.
Set the time column (such as created_at) as the X-axis and choose a time grain, for example Day.
Add a metric, for example SUM(amount).
Click Update chart to render it, then Save, and in the save dialog add it to a new dashboard.

Open the dashboard from Dashboards, click Edit dashboard to resize or rearrange charts, and add native filters from the filter panel on the left so viewers can change the time range or other columns.

Step 9 - Managing users and roles

Superset ships with built-in roles:

Role	Access
Admin	Everything, including security settings
Alpha	Access to all data sources, can create and edit charts and dashboards, no user management
Gamma	Only the data sources and dashboards explicitly granted through extra roles
sql_lab	Grants access to SQL Lab; combine with other roles

Create users in Settings > List Users. A common pattern is to give analysts Alpha plus sql_lab, and business users Gamma plus a custom role that grants datasource access on the datasets they need, created in Settings > List Roles. Do not edit the built-in roles, because superset init resets them on upgrade.

Troubleshooting

The init container fails or the web UI never comes up. Read the logs with sscompose logs superset-init and sscompose logs superset. A missing or changed SUPERSET_SECRET_KEY and a lack of memory are the usual causes; check free -h and docker stats.

502 Bad Gateway from Nginx. Superset is not listening yet or crashed. Check curl -s http://127.0.0.1:8088/health and sscompose ps.

Redirects go to http:// after login. ENABLE_PROXY_FIX = True is missing or the containers were not recreated after adding it.

"Could not load database driver". The driver package is not installed. Add it to docker/requirements-local.txt and recreate the containers.

The admin password is not accepted, or you forgot it. Older init scripts ignore ADMIN_PASSWORD and create admin with the password admin. Either way, reset it from the CLI inside the container:

sscompose exec superset superset fab reset-password --username admin --password your_new_password

Upgrading

Back up the metadata database first, then check out the new tag and restart with the new TAG:

sscompose exec -T db pg_dump -U superset superset > ~/superset-metadata-$(date +%F).sql
cd ~/superset
git fetch --tags
git checkout tags/NEW_VERSION

Update the version in your sscompose alias, run source ~/.bashrc, and start the stack with sscompose up -d. The init container applies the database migrations.

Conclusion

You now have Apache Superset running from an official release image, reachable only through Nginx over HTTPS, with a PostgreSQL data source, a chart and a dashboard. From here you can connect more databases, set up alerts and reports (which need an SMTP server configured in superset_config_docker.py), or restrict what each team sees with custom roles and row level security under Settings > Row Level Security.

On this page