Quick start: Docker Compose

This setup runs the published ShipLean image and PostgreSQL 18. Docker Compose stores the database and uploaded files in named volumes. It publishes the app on port 8080 and binds PostgreSQL to the local machine only.

1. Download the two files

Create a folder for this deployment, then save these files into it:

• docker-compose.yml
• .env

Open .env and set SHIPLEAN_ADMIN_EMAIL and SHIPLEAN_ADMIN_PASSWORD to the email address and a strong password for the first instance admin. Set POSTGRES_PASSWORD to a long random password of letters and digits. Keep this file private.

2. Start ShipLean

From that folder, run:

docker compose up -d

Open http://localhost:8080 and sign in with the admin email and password from .env. Create your first project from the app. The first administrator is created when no instance admin exists. After you sign in, remove both SHIPLEAN_ADMIN_EMAIL and SHIPLEAN_ADMIN_PASSWORD from .env. They only set up the first admin. ShipLean does not use them to sign you in after setup.

3. Check the service

The health endpoint returns the running version:

curl --fail http://localhost:8080/health

If the app is not ready yet, read the service logs with docker compose logs -f shiplean and run the health request again.

Compose file

services:
  shiplean:
    image: ${SHIPLEAN_IMAGE:-ghcr.io/shiplean/shiplean}
    restart: unless-stopped
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SHIPLEAN_DB_CONNECTION: Host=postgres;Port=5432;Database=shiplean;Username=postgres;Password=${POSTGRES_PASSWORD}
      SHIPLEAN_BLOB_ROOT: /data/blobs
      SHIPLEAN_ADMIN_EMAIL: ${SHIPLEAN_ADMIN_EMAIL}
      SHIPLEAN_ADMIN_PASSWORD: ${SHIPLEAN_ADMIN_PASSWORD}
    volumes:
      - shiplean-blobs:/data/blobs

  postgres:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_DB: shiplean
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - shiplean-pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d shiplean"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  shiplean-pgdata:
  shiplean-blobs:

Environment file

POSTGRES_PASSWORD=replace-with-a-long-random-value
SHIPLEAN_ADMIN_EMAIL=you@example.com
SHIPLEAN_ADMIN_PASSWORD=replace-with-a-unique-password

Use a different value for each secret before you start. Compose reads .env automatically. The app and database use named volumes, so their data survives when containers are replaced. This example publishes the app directly over HTTP for a local trial. For a public deployment, put a TLS reverse proxy in front of the app and read production setup.

Next: connect an agent or put ShipLean behind TLS.