Portainer

If you run your Docker host through Portainer, good news: you can deploy Perch as a stack right from the Portainer UI, no terminal required.

Deploy as a stack

Open your environment

In Portainer, go to the environment you want to deploy Perch on.

Create a new stack

Click Stacks in the left sidebar, then Add stack. Give it a name (e.g. perch).

Paste the compose YAML

Select Web editor and paste in the compose definition below.

perch-stack

services:
  hub:
    image: lxghtblvee/perch-hub:latest
    ports:
      - "8484:8484"
    environment:
      PERCH_HUB_TOKEN: ${PERCH_HUB_TOKEN}
      PERCH_DB_HOST: db
      PERCH_DB_USER: perch
      PERCH_DB_PASS: ${PERCH_DB_PASS}
      PERCH_DB_NAME: perch
      PERCH_ADMIN_EMAIL: ${PERCH_ADMIN_EMAIL}
      PERCH_ADMIN_PASSWORD: ${PERCH_ADMIN_PASSWORD}
    volumes:
      - hub-uploads:/app/apps/hub/uploads
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  agent:
    image: lxghtblvee/perch-agent:latest
    environment:
      PERCH_HUB_URL: http://hub:8484
      PERCH_HUB_TOKEN: ${PERCH_HUB_TOKEN}
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - agent-data:/data
    depends_on:
      - hub
    restart: unless-stopped

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: perch
      POSTGRES_PASSWORD: ${PERCH_DB_PASS}
      POSTGRES_DB: perch
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U perch -d perch"]
      interval: 5s
      timeout: 5s
      retries: 10
    restart: unless-stopped

volumes:
  db-data:
  agent-data:
  hub-uploads:

Fill in your secrets

Scroll down to Environment variables and add the four values below. This keeps them out of the stack definition, which is the safer way to do it. Then click Deploy the stack.

Variable	Value
`PERCH_HUB_TOKEN`	A long random string, `openssl rand -hex 32`
`PERCH_DB_PASS`	A strong database password
`PERCH_ADMIN_EMAIL`	Your admin account email
`PERCH_ADMIN_PASSWORD`	Your admin account password

Upgrading

Open the perch stack under Stacks and click Pull and redeploy. Portainer grabs the latest images and restarts the services for you.

Note

Database migrations run on hub startup automatically, so there’s nothing extra to do after a redeploy.

Monitoring other hosts

To watch other machines from Portainer, you have two options:

Add the host to Portainer as an environment, then deploy the agent service there as its own stack:

services:
  agent:
    image: lxghtblvee/perch-agent:latest
    environment:
      PERCH_HUB_URL: https://your-hub-url
      PERCH_HUB_TOKEN: your-secret-token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - agent-data:/data
    restart: unless-stopped

volumes:
  agent-data:

SSH into the other host and run the agent with docker run or a minimal compose file. See the Docker Compose guide for the command.