Installation

Conveyor ships as a single Go binary with an embedded SQLite database. The only hard requirement before it will start is an AES-256-GCM encryption key.

Generate an encryption key

Every Conveyor instance needs a 64-character hex string (32 bytes) used to encrypt SSH private keys, GitHub tokens, and managed .env file contents at rest. Generate one with the bundled CLI:

docker run --rm ghcr.io/smitmartijn/conveyor:latest /app/conveyor-cli generate-key

Save the output somewhere safe. You’ll set it as CONVEYOR_ENCRYPTION_KEY.

Danger

Back up this key separately from your database. If it’s lost, every encrypted value in the database (SSH private keys, GitHub tokens, and .env contents) is permanently unrecoverable, even if the SQLite file itself is intact. See Backups.

Docker Compose (recommended)

1. Create a docker-compose.yml:

   services:
     conveyor:
       image: ghcr.io/smitmartijn/conveyor:latest
       ports:
         - "8080:8080"
       volumes:
         - ./conveyor-data:/data
       environment:
         - CONVEYOR_ENCRYPTION_KEY
         - CONVEYOR_ADMIN_EMAIL
         - CONVEYOR_ADMIN_PASSWORD
         - CONVEYOR_BASE_URL
       restart: unless-stopped

2. Create a .env file next to it:

   CONVEYOR_ENCRYPTION_KEY=<the key you generated>
   CONVEYOR_ADMIN_EMAIL=admin@example.com
   CONVEYOR_ADMIN_PASSWORD=changeme
   CONVEYOR_BASE_URL=http://localhost:8080

3. Start it:

   docker compose up -d

4. Open http://localhost:8080 and log in with the admin credentials from .env.

CONVEYOR_ADMIN_EMAIL and CONVEYOR_ADMIN_PASSWORD only create a user on first boot, when the database has no users yet. They’re ignored on every subsequent start. See Configuration for the full list of environment variables, including TLS and cookie settings.

Plain Docker

Without Compose, generate the key, then run the image directly with a volume for persistent data:

docker run -d \
  --name conveyor \
  -p 8080:8080 \
  -v conveyor-data:/data \
  -e CONVEYOR_ENCRYPTION_KEY=<your-key> \
  -e CONVEYOR_ADMIN_EMAIL=admin@example.com \
  -e CONVEYOR_ADMIN_PASSWORD=changeme \
  -e CONVEYOR_BASE_URL=http://localhost:8080 \
  --restart unless-stopped \
  ghcr.io/smitmartijn/conveyor:latest

The image runs as an unprivileged user internally; its entrypoint takes care of making /data writable on first start, whether you use a named volume or a bind mount.

From source

Requires Go 1.25+ and make.

git clone https://github.com/smitmartijn/conveyor.git
cd conveyor

# Install dependencies
go mod download

# Generate an encryption key
go run ./cmd/cli generate-key

# Set environment variables
export CONVEYOR_ENCRYPTION_KEY=<generated-key>
export CONVEYOR_DATA_DIR=./data
export CONVEYOR_ADMIN_EMAIL=admin@example.com
export CONVEYOR_ADMIN_PASSWORD=changeme

# Build and run
make run

This builds and runs the cmd/server binary directly on your machine, useful for development or for running Conveyor without Docker on a host that already has Go available.

Upgrading

To upgrade a Docker Compose install, pull the new image tag and recreate the container:

docker compose pull
docker compose up -d

Your data (the SQLite database, SSH keys, and TLS certificates if using self-signed mode) lives entirely under the mounted /data volume and is untouched by the image upgrade. Take a backup before upgrading across major versions.

Next steps

Continue to your first deployment to add a server and deploy a project.