--- title: "How to Install Apache Superset on Ubuntu 24.04 with Docker" description: "Deploy Apache Superset on Ubuntu 24.04 with Docker Compose, serve it through Nginx with HTTPS, connect a PostgreSQL database and build your first dashboard." category: "Data Engineering" language: en source: https://cubepath.com/docs/data-engineering/superset-data-visualization-installation updated: 2026-09-25 --- # 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](https://github.com/apache/superset/releases) and use it in place of `5.0.0` below: ```bash cd ~ git clone https://github.com/apache/superset.git cd superset git checkout tags/5.0.0 ``` Confirm you are on the tag: ```bash git describe --tags ``` ```output 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: ```bash openssl rand -base64 42 ``` Create the override file: ```bash nano docker/.env-local ``` Add the following, replacing the placeholders with the generated key and a strong password of your own: ```ini 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: ```bash nano docker-compose.override-local.yml ``` ```yaml 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: ```bash 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: ```bash 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: ```bash 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: ```bash curl -s http://127.0.0.1:8088/health ``` ```output OK ``` To avoid typing both `-f` flags every time, you can define a shell alias: ```bash 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: ```bash sudo apt update sudo apt install -y nginx certbot python3-certbot-nginx ``` Create a server block: ```bash sudo nano /etc/nginx/sites-available/superset ``` ```nginx 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: ```bash 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: ```bash 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: ```bash nano docker/pythonpath_dev/superset_config_docker.py ``` ```python ENABLE_PROXY_FIX = True ``` Recreate the containers to apply it: ```bash 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: ```sql 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: ```text 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: ```sql 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**. 1. Pick a chart type, for example **Line Chart**, and click **Create new chart**. 2. Set the time column (such as `created_at`) as the X-axis and choose a time grain, for example **Day**. 3. Add a metric, for example `SUM(amount)`. 4. 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: ```bash 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`: ```bash 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**.