localzet/deployer repository overview

⁠Localzet Deployer

Localzet Deployer is a self-hosted CI/CD control plane for teams that want to run deployments from GitHub Webhooks without depending on GitHub-hosted build minutes.

It is designed for Docker- and Portainer-based environments where you want to receive a webhook, build and publish an image, redeploy a stack, and keep operational history in one place.

⁠What It Does

• Receives GitHub push webhooks
• Validates X-Hub-Signature-256
• Maps repository + branch to a project configuration
• Runs queued deployment jobs with per-project locking
• Executes build, publish, redeploy, and health check steps
• Stores job and deployment history in PostgreSQL
• Streams live logs to the built-in web UI
• Supports manual redeploy and rollback

⁠Typical Use Case

A common setup looks like this:

1. GitHub sends a push webhook to Localzet Deployer
2. Localzet Deployer checks the branch and project mapping
3. The configured pipeline builds and publishes an image
4. Portainer is triggered through a webhook
5. A health check confirms the deployment result
6. Operators can review logs, history, and trigger rollback if needed

⁠Included Components

The container image provides:

• the Rust orchestrator service
• the built-in operator web UI
• API endpoints for jobs, deployments, retries, redeploys, and rollback

External dependencies are expected to be provided by your runtime stack:

• PostgreSQL
• Docker socket access
• optional private registry
• optional Portainer webhook target

⁠Quick Start

1. Download the runtime config template:

mkdir -p /opt/deployer
curl -fsSL https://raw.githubusercontent.com/localzet/deployer/main/config/app.prod.toml.example \
  -o /opt/deployer/app.toml

1. Edit /opt/deployer/app.toml and set:

• github_webhook_secret
• auth.api_token
• PostgreSQL connection settings
• registry credentials
• Portainer webhook URL
• health check URL

1. Run the stack:

services:
  orchestrator:
    image: localzet/deployer:latest
    environment:
      CICD_CONFIG: /app/config/app.toml
      RUST_LOG: info,tower_http=info
    ports:
      - "8080:8080"
    volumes:
      - /opt/deployer:/app/config:ro
      - cicd-workspace:/workspace/repos
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-bookworm
    environment:
      POSTGRES_DB: cicd
      POSTGRES_USER: cicd
      POSTGRES_PASSWORD: cicd
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

  registry:
    image: registry:2
    volumes:
      - registry-data:/var/lib/registry
    restart: unless-stopped

volumes:
  cicd-workspace:
  postgres-data:
  registry-data:

1. Start it:

docker compose up -d

1. Open:

http://localhost:8080

⁠Required Runtime Access

This image is intended to run with access to:

• a mounted configuration file
• a PostgreSQL database
• /var/run/docker.sock

Without Docker socket access, build and image-management steps will not work.

⁠Main Endpoints

• GET /healthz
• GET /api/dashboard
• GET /api/projects
• GET /api/jobs
• GET /api/jobs/:id
• GET /api/jobs/:id/events
• GET /api/deployments
• POST /api/projects/:id/redeploy
• POST /api/deployments/:id/rollback
• POST /api/jobs/:id/retry
• POST /api/jobs/:id/cancel
• POST /api/webhooks/github

⁠Configuration Model

Runtime behavior is controlled through app.toml.

The configuration supports:

• webhook secret validation
• API token authentication
• PostgreSQL connectivity
• project mapping by repository and branch
• action-aware pipeline steps
• manual redeploy and rollback flows

Pipeline step templates support variables such as:

• $IMAGE_REFERENCE
• $STABLE_IMAGE_REFERENCE
• $JOB_ACTION
• $SOURCE_DEPLOYMENT_ID

⁠Image Tags

Recommended tags:

• latest
• main
• sha-<shortsha>
• release tags such as v1.0.0

⁠Source Code

GitHub repository:

https://github.com/localzet/deployer⁠

⁠License

GNU Affero General Public License v3.0 only.