Skip to main content
The public repository ships a Compose file that runs Meteroid with all its infrastructure on one machine: PostgreSQL, ClickHouse, Redpanda (Kafka-compatible) and a local directory for object storage. Use it to try Meteroid or for a small installation. For production, prefer Kubernetes with managed databases.

​
Install

1

Get the deployment files

The files live in docker/deploy of the meteroid-oss/meteroid repository: docker-compose.yml, .env.example, and the ClickHouse configuration under volume/. Check out the tag of the release you run, so the files match it:
2

Set the secrets

Replace the four placeholder secrets in .env before the first start:DATABASE_PASSWORD is inserted into the database URL, so a hexadecimal value avoids characters that would need escaping.
Never change SECRETS_CRYPT_KEY once set: it encrypts your connector credentials (see the configuration reference). Keep a copy of .env with your backups.
3

Set the public URLs

The browser talks to the API directly, so the web app needs the addresses at which your users reach it. The defaults work when you open Meteroid on the same machine:
.env
On a server, replace localhost with its address or domain name. METEROID_PUBLIC_URL is the address of the web app, used in links Meteroid generates (emails, portal and checkout links). The API and the worker also take the REST API’s public URL from VITE_METEROID_REST_API_EXTERNAL_URL, for file links and the OAuth and SSO callbacks.
4

Start Meteroid

The first start downloads the images and runs the database migrations, which takes a few minutes. Follow it with docker compose logs -f meteroid-api.
5

Create the first account

Open http://localhost:3000 and sign up: the first account creates the organization. When SMTP is configured, a new account must first confirm its email address.

​
Services and ports

The Compose file publishes the database and broker ports on the host as well. On a machine reachable from the internet, restrict them with a firewall, or remove their ports: entries.

​
Configure optional settings

Compose passes to each container only the variables listed under its environment: in docker-compose.yml; a variable that is only in .env is not seen by Meteroid. Optional settings (S3 storage, Redis, SMTP, Google sign-in, outbound webhooks, OpenTelemetry) are listed there, commented out. To use one, uncomment its lines in both meteroid-api and meteroid-worker, then set the values in .env. For a setting that is not listed, such as LICENSE_KEY, add a line to the environment: of both services. To turn off the anonymous telemetry report, uncomment METEROID_TELEMETRY=off in the same two services. See the configuration reference for every setting. With the default file:// object storage, the API and the worker share the object_store_data volume.

​
Update Meteroid

Back up the database first: an upgrade cannot be undone except by restoring a backup. Take docker/deploy from the tag of the new release if its files changed, reapply your changes to docker-compose.yml, then:
The images run latest, so docker compose pull takes the newest release. To stay on one release, set METEROID_VERSION in .env, for example 2.0.0, and change it when you upgrade. Coming from a 1.0.0 release candidate, 0.19 or an older build? Follow Upgrading to 2.0 instead.

​
Backups

The data lives in these volumes: docker compose down -v deletes these volumes, and your data with them. Back up PostgreSQL with pg_dump, for example:
Use the user and database names of your .env (DATABASE_USER, DATABASE_NAME) if you changed them. Store the dump, and your .env, away from the machine.