Quick start with Docker

The MiniPAM server image contains the API and the web interface. One container, one port (8091), and one volume for the SQLite database.

Pre-alpha

Images are not published to a registry yet. Build the image from a checkout of the repository, as shown below. Published images will follow the public release, planned for Q1 2027.

1. Build the image

From the repository root:

docker build -f deployments/docker/server.Dockerfile -t minipam-server .

The build compiles the web interface and installs the Python server. It takes a few minutes the first time.

2. Create the configuration file

The server reads its settings from one file. Copy the image's file into a local minipam-config.yml:

docker run --rm minipam-server cat config.yml > minipam-config.yml

It already has the right paths for the container. Only bootstrap-token needs a value: the single-use secret for creating the first admin from the browser. Generate one with openssl rand -hex 32 and set it:

minipam-config.yml

server:
  services:
    web-api:
      authentication:
        bootstrap-token: "paste-the-generated-token-here"

Every other setting is explained in the full example.

3. Start the container

Mount minipam-config.yml over the configuration in the image:

docker run -d --name minipam \
  -p 8091:8091 \
  -v minipam-data:/var/lib/minipam \
  -v "$PWD/minipam-config.yml:/app/app-server/config.yml:ro" \
  --restart unless-stopped \
  minipam-server

Or with Docker Compose:

compose.yaml

services:
  minipam:
    image: minipam-server
    ports:
      - "8091:8091"
    volumes:
      - minipam-data:/var/lib/minipam
      - ./minipam-config.yml:/app/app-server/config.yml:ro
    restart: unless-stopped

volumes:
  minipam-data:

docker compose up -d

Check that it answers:

curl http://localhost:8091/health

It prints {"status":"ok"}.

4. Create the first admin

Open http://localhost:8091 and follow Create the first admin and inventory. After that, restart the container whenever you change minipam-config.yml: docker restart minipam, or docker compose restart.

Where things live

In the container	What it is
/var/lib/minipam	Data volume. Holds database.db.
/app/app-server/config.yml	Server configuration. Your minipam-config.yml.
Port 8091	Web interface, REST API, live events, and agents

Keep the data volume on a local disk, as above, not on a network share; see Upgrades and backups. The container runs as the unprivileged user minipam (uid 10001).

Put MiniPAM behind a reverse proxy for HTTPS. See Run behind a reverse proxy.

Try it with demo data

The repository also has a demo stack: a server, a demo agent that replays recorded discovery data, and an admin user created for you. Use it to look around, not to keep real inventory.

The demo stack also uses port 8091. Stop the minipam container first (docker stop minipam), or set MINIPAM_APP_PORT in .env to another port and use that port below.

cp deployments/dev-docker/.env.example deployments/dev-docker/.env
# Edit .env and set MINIPAM_DEMO_ADMIN_PASSWORD
docker compose --env-file deployments/dev-docker/.env \
  -f deployments/dev-docker/docker-compose.yml up --build -d

Sign in at http://localhost:8091 with MINIPAM_DEMO_ADMIN_USERNAME and MINIPAM_DEMO_ADMIN_PASSWORD from .env. Stop it with down, and add --volumes to erase its database.