Start mado with Docker Compose

First, start a development environment from source and check that it works in your browser. You need Git, Docker, and Docker Compose v2.

Install Docker and Git

macOS

If you have Homebrew, run the following in a terminal.

brew install git
brew install --cask docker
open -a Docker

Complete the setup on Docker Desktop's first-run screen and wait for it to finish starting. If you don't have Homebrew, install it by following the Homebrew installation instructions. You can check the Docker Desktop requirements in the official instructions for macOS.

Set up a local development environment on Ubuntu

Install Git and curl, then use Docker's official install script for development environments.

sudo apt-get update
sudo apt-get install -y git curl
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

If you don't have permission to run the Docker commands that follow, run them with sudo. To install Docker on a production machine, use the official instructions for installing from the apt repository.

Check the installation

git --version
docker version
docker compose version

Make sure that docker version also shows the Server section.

Get the source and the configuration file

git clone https://github.com/aida0710/mado-s3-datacatalog.git
cd mado-s3-datacatalog
cp .env.example .env
openssl rand -hex 32

Set the value generated by the last command as ENCRYPTION_KEY in .env. This key is used to encrypt the S3 credentials you save, so keep it stored after you start using mado.

AUTH_MODE=local in .env.example lets you try mado with Local Users. To use DataLineage, separately prepare a compatible Dataset Registry and its Bearer token, and Marquez if needed. For the Registry specification, see the API contract.

Start the development environment

docker compose -f compose.dev.yaml up -d --build postgres api-internal media-worker front
docker compose -f compose.dev.yaml ps

Start the services that Storage needs first. Once PostgreSQL is healthy, create the initial Admin. After you configure the connection to the Registry, you can start OpenLineage ingest with docker compose -f compose.dev.yaml up -d --build api-lineage.

Create the initial Admin

docker compose -f compose.dev.yaml exec api-internal \
  npm run auth:bootstrap-admin:dev -- --username admin

At New admin password:, enter an initial password, and enter the same value at Confirm password:. The initial password must be at least 8 bytes. After your first login, change it to a password of at least 12 bytes. Each alphanumeric character counts as 1 byte, and most Japanese characters count as 3 bytes. The characters you type are not shown on screen.

Open http://localhost:5173 in your browser and log in with the username admin and the password you set. If you are asked to change your password on first login, complete that step, then register a connection.

After you log in, add S3-compatible storage from Settings.

After you log in, add S3-compatible storage from Settings.

Use a dedicated configuration and a TLS proxy in production

To start the production setup from source, use compose.prod.yaml. The main settings in .env are as follows.

Setting	Description
POSTGRES_PASSWORD	Password for PostgreSQL administration
DASHBOARD_PASSWORD	Password that matches the one in DATABASE_URL_RW / DATABASE_URL_RO
LINEAGE_DB_PASSWORD	Password for the DB role used by OpenLineage
WORKER_DB_PASSWORD	Password for the DB role dedicated to the audio analysis worker
ENCRYPTION_KEY	32-byte encryption key in hex
AUTH_MODE	One of local, oidc, or hybrid
AUTH_COOKIE_SECURE	true when you use HTTPS
ALLOWED_ORIGINS	Origin of the URL that browsers use
DATASET_REGISTRY_URL / DATASET_REGISTRY_TOKEN	Connection settings for the compatible Registry. Required in production

In a new environment, create the Admin before you start the web entry point.

docker compose -f compose.prod.yaml build
docker compose -f compose.prod.yaml up -d postgres
docker compose -f compose.prod.yaml run --rm api-internal \
  node dist/scripts/bootstrap-admin.js --username admin
docker compose -f compose.prod.yaml up -d --build

The UI listens on 127.0.0.1:8080, and the entry point dedicated to sending OpenLineage events listens on 127.0.0.1:8081. Put a TLS proxy inside your intranet in front of the UI. If you expose the endpoint that pipelines send events to, connect a separate TLS hostname to 8081.

Updating an existing DB requires applying migrations in a specific order. Follow the DB update procedure. If you use a release bundle, see the bundle installation steps.