VPS Tutorials
Metabase on a VPS: Docker, read-only sources and recovery
Deploy Metabase with PostgreSQL and HTTPS, separating the writable application database from restricted reporting sources. Review licensed sharing and cache controls, query performance, subscriptions and recoverable backups.

Metabase connects databases to questions, charts, dashboards and scheduled reports. A VPS can host internal business analytics without copying every dataset to a managed BI platform, although queries and exports still move data into the application. Use only drivers and features supported by your chosen edition; a database such as ClickHouse may require a matching driver.
This Ubuntu 24.04/Docker/PostgreSQL guide separates the application database from reporting sources. Test source permissions before inviting users.
| Workload | CPU | RAM | Disk | Starting approach |
|---|---|---|---|---|
| Personal lab | 2 vCPU | 4 GB | 40 GB SSD | Small source and limited concurrency |
| Small team | 4 vCPU | 8 GB | 80 GB NVMe | Separate application DB and backup capacity |
| Multiple sources | 8 vCPU | 16 GB+ | 160 GB NVMe+ | Separate analytical workloads and bound queries |
These budgets include Java heap, results, background work and PostgreSQL; measure actual demand. Point working A/AAAA records for bi.example.com at the VPS, permit required management/80/443, and keep database/internal ports private. Redis is not required by this example. See VPS sizing.
sudo apt update
sudo apt install -y ca-certificates curl git openssl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/metabase
sudo chown -R "$USER":"$USER" /opt/metabase
cd /opt/metabase
mkdir -p backups
Review the root installer or use supported packages; Docker access is powerful. Avoid metabase/metabase:latest, pin application/database/plugin versions and record digests. Protect .env with chmod 600.
The application database stores users, questions, dashboards, permissions and encrypted connection details. It needs writes and migrations; read-only access is for reporting sources, not this application database.
MB_DB_TYPE=postgres
MB_DB_DBNAME=metabase
MB_DB_PORT=5432
MB_DB_USER=metabase
MB_DB_PASS=change-a-long-password
MB_DB_HOST=postgres
MB_JETTY_PORT=3000
MB_ENCRYPTION_SECRET_KEY=replace-with-a-random-secret
Generate and preserve MB_ENCRYPTION_SECRET_KEY in a supported format. Replacing it can make existing stored credentials unreadable.
services:
postgres:
image: postgres:16
restart: unless-stopped
environment:
POSTGRES_DB: metabase
POSTGRES_USER: metabase
POSTGRES_PASSWORD: ${MB_DB_PASS}
volumes:
- postgres_data:/var/lib/postgresql/data
metabase:
image: metabase/metabase:v0.56.0
restart: unless-stopped
depends_on:
- postgres
ports:
- "127.0.0.1:3000:3000"
env_file:
- .env
volumes:
postgres_data:
The pinned v0.56.0 sketch is an older baseline, not the current stable release. Check release notes and an explicitly supported upgrade path before selecting a new version. Use a dedicated application database owner with required schema rights; PostgreSQL's POSTGRES_USER bootstrap account is a superuser, not a least-privilege report user. Do not reuse it for production reporting sources.
docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 metabase
Wait for initialization/migrations and check logs. depends_on alone does not prove PostgreSQL readiness; add a version-appropriate DB healthcheck/dependency if needed. Temporary startup unavailability is no reason to delete its volume.
Reach http://127.0.0.1:3000 through an SSH tunnel for private onboarding; configure the final HTTPS site URL afterward.
- Give reporting users read-only access to required schemas/tables only.
- Use private networking, with TLS when the route is not trusted.
- Name each source and record its owner/purpose.
- Put heavy analytics on replicas, a warehouse or summaries rather than the transaction database.
Test a small question for connectivity, encoding, time zone and permissions before creating dashboards. Keep passwords/tokens and unnecessary personal data out of SQL questions and public comments. A replica is not automatically free of sensitive data.
sudo apt install -y nginx certbot python3-certbot-nginx
sudo nano /etc/nginx/sites-available/metabase
server {
listen 80;
server_name bi.example.com;
client_max_body_size 20m;
location / {
proxy_pass http://127.0.0.1:3000;
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;
}
}
sudo ln -s /etc/nginx/sites-available/metabase /etc/nginx/sites-enabled/metabase
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d bi.example.com
Enable the site only once; inspect an existing symlink before repeating ln -s. Verify DNS, certificate renewal and the final Metabase site URL. Caddy is another gateway option. For redirect/cookie/iframe problems, check HTTPS and X-Forwarded-Proto; use only trusted proxy forwarding. Configure embedding deliberately rather than disabling security headers globally.
- Give ordinary members approved, appropriately masked collections/dashboards.
- Let analysts build questions with database permissions that prohibit production writes.
- Limit administrator membership and separate everyday analysis accounts.
- Use dedicated groups and dashboards for external audiences, testing actual access.
Collection visibility does not by itself provide tenant or row-level isolation. Sandboxing, advanced embedding, audit and other controls can depend on license/version. Disable unnecessary public links, inventory existing share tokens, and scope integration credentials. A public link grants access to whoever has it; do not use it as authentication.
- Inspect slow queries, full scans and missing indexes.
- Build summaries/materialized views where justified.
- Use result caching/refresh options available in the selected edition; verify licensing and sensitive-data behavior.
- Bound query concurrency, timeouts and result size using supported application/database controls.
- Move costly analytics to a suitable read-only replica or warehouse.
Stagger refresh jobs and account for a cold cache triggering many queries. Cached results are neither backups nor an authorization boundary.
Configure and test password reset, subscriptions and alerts. Verify SPF/DKIM/DMARC, actual sender IP PTR and the relay's outbound port/TLS. A relay provider normally controls PTR. Test a single administrator recipient first.
docker compose logs --tail=200 metabase | grep -Ei "email|pulse|error"
Remove departed recipients and verify who receives potentially sensitive exports. A successful SMTP test does not verify scheduled delivery.
Back up the application database separately from every reporting database you also maintain:
mkdir -p /opt/metabase/backups
docker compose exec -T postgres pg_dump -U metabase metabase | gzip > /opt/metabase/backups/metabase-$(date +%F).sql.gz
cp .env docker-compose.yml /opt/metabase/backups/
docker compose config > /opt/metabase/backups/compose-$(date +%F).yaml
Enable pipefail and verify dump success. Preserve the actual Compose filename, environment, encryption key and compatible plugins/drivers; protect expanded configuration. Encrypt .env and offsite copies. At least monthly, restore the matching application version in isolation and test login, source connections, questions, dashboards, permissions and subscriptions without sending real reports. See restore drills.
- Record image digest, Java settings, PostgreSQL and driver versions.
- Back up application DB and configuration.
- Test the supported migration path, queries, dashboards, subscriptions and embedding.
- Schedule maintenance and start the deliberately pinned new image.
- Wait for successful migrations, inspect logs/health and reopen access.
docker compose pull
docker compose up -d
docker compose logs --tail=300 metabase
docker compose ps
An older image must not be pointed blindly at a migrated application DB. Restore the matching backup in isolation before rolling back. Preserve encryption keys across both paths.
Check Nginx, application and PostgreSQL logs, private port 3000, readiness and database credentials.
Separate web/Java pressure, application DB pressure and reporting-source query cost. Inspect connections, returned rows and supported cache behavior.
Check SMTP credentials, TLS, sender DNS, outbound policy and background logs. Distinguish direct test-mail errors from scheduled tasks.
Check PostgreSQL WAL, Docker logs, exports, retained backups and temporary data. Verify recoverable offsite copies before cleanup; never manually delete active WAL files.
- Application and PostgreSQL are healthy with deliberate versions.
- HTTPS, forwarding, site URL and cookies are correct.
- Reporting sources use restricted read-only credentials and private access.
- Permissions, public links, embedding and integration tokens are tested.
- SMTP, reset, subscriptions and alerts work.
- Application DB, maintained source data, configuration and keys have offsite copies.
- An isolated restore is tested and timed.
Begin with one restricted source and a few useful dashboards, measuring query cost before adding automation.
Further reading: