Documentation

Installing Micro BI

Beta — v1.0.0-beta.4

Micro BI is self-hosted business intelligence software. This guide walks you through deploying it on your own server using Docker Compose — no build step required, just pull and run.

Requirements

A Linux server (or VM) with Docker and Docker Compose v2 installed
At least 2 GB RAM and 10 GB free disk space (more if you expect large ETL imports)
An open port for the web interface (default 8080) and, if you plan to use SFTP data sources, port 2222
A Micro BI beta license key — request one at microbi.app, you'll receive it by email

1. Download the deployment package

Extract the deploy/ folder we sent you — it contains everything you need:

deploy/
├── docker-compose.prod.yml
└── .env.example

2. Configure your environment

cp .env.example .env
nano .env

Every value marked [ZMIEŃ] / CHANGE_ME must be changed before starting:

Variable	What to set it to
`POSTGRES_PASSWORD`	A strong password of your choice. Must match the password embedded in `DATABASE_URL` below it.
`DATABASE_URL`	Same password as above; the rest of the connection string stays as-is.
`JWT_SECRET_KEY`	Random string — generate with `openssl rand -hex 32`
`SERVICE_TOKEN`	Another random string, same command.
`APP_PUBLIC_URL`	The address people will use to reach Micro BI, e.g. `http://203.0.113.10:8080`
`CORS_ORIGINS`	Same value as `APP_PUBLIC_URL`, comma-separated if more than one.
`ACTIVATION_SERVER_URL`	Leave as `https://activation.microbi.app/api/v1`
`HTTP_PORT`	Port you'll access Micro BI on. Default `8080`.
`MICROBI_TAG`	Leave as `beta` for automatic updates, or pin a specific version.

Never put a # comment on the same line as a value. Docker Compose treats everything after = — including a trailing comment — as part of the value itself. Put comments on their own line, above the variable.

3. Start Micro BI

docker compose -f docker-compose.prod.yml up -d

This pulls the four pre-built images, starts PostgreSQL, Redis, and all Micro BI services, and automatically runs database migrations on first start.

docker compose -f docker-compose.prod.yml ps

All services should show Up (Postgres and Redis should show Up (healthy)).

4. First-time setup

Open http://<your-server>:8080 in a browser. Since this is a fresh installation, you'll be automatically taken to a setup wizard to create your first admin account — no database access required.

5. Activate your license

Go to Settings → License, paste your license key, and click Activate. Your installation will show as Pro during the beta.

Updating

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Your data is untouched by this process — only application containers are replaced. Migrations run automatically.

Never run docker compose down -v — the -v flag deletes all volumes, meaning all your data. A plain down (without -v) is always safe.

Backups

Micro BI stores data in four Docker volumes: postgres_data, duckdb_data, uploads, etl_inbox. Back these up regularly:

docker run --rm -v micro-bi_postgres_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/postgres_backup_$(date +%Y%m%d).tar.gz -C /data .

Repeat for the other volumes with the appropriate name.

Troubleshooting

Backend keeps restarting / migration errors in logs

Check docker compose -f docker-compose.prod.yml logs backend. The most common cause is a typo or trailing comment in .env.

502 Bad Gateway

Usually means the backend container isn't reachable yet. Give it a minute after startup; if it persists, check the backend and frontend logs.

Can't activate a license

Confirm your server can reach https://activation.microbi.app (no firewall blocking outbound HTTPS) and that the key was copied exactly, with no extra spaces.

Need help? contact@microbi.app

What to expect during the beta

This is beta software: expect occasional bugs, and please back up your data. When the beta concludes, licenses transition to the Free tier (5 users, 2 projects, 20 data sources) unless you purchase a Pro subscription — we'll give advance notice by email. See our Terms of Service for details.