deploy-lab-plugin

Deploy Lab Plugin

Produce canonical Docker and Docker Compose configuration for a lab plugin.

Default Assumptions

When the user omits details, apply these defaults without asking:

• Port: 8080 (override only if the user specifies a different port)
• Env file: env_file: .env in the Compose service stanza
• Healthcheck defaults: interval: 30s, timeout: 10s, retries: 3, start_period: 10s
• No external volumes unless the user explicitly mentions persistent data or a data directory
• No inter-service networking unless the user mentions other Compose services
• Language selection: infer from trigger phrase or project files (Cargo.toml → Rust, pyproject.toml/setup.py → Python, package.json → TypeScript/Node)

If a required input cannot be inferred (e.g., the plugin name or the list of required env vars), ask before generating files.

Canonical Container Shape

A conforming plugin container:

• uses a multi-stage Dockerfile (builder stage + minimal runtime stage)
• runs as a non-root user in the runtime stage
• exposes a /health endpoint on the plugin's HTTP port returning HTTP 200
• reads all config from environment variables — no baked-in secrets
• has an entrypoint.sh that validates every variable in .env.example before starting the server
• is declared in docker-compose.yaml with env_file, named volume mounts, and a healthcheck directive
• has a .dockerignore that excludes .env, dev artifacts, and test data

Language Layer Directories

Use the correct canonical template base for the target language:

• Python — ~/workspace/plugin-templates/py/
• Rust — ~/workspace/plugin-templates/rs/
• TypeScript / Node — ~/workspace/plugin-templates/ts/

Specialize the template with the plugin's package name, binary or module entrypoint, correct port, required env var names, and any extra system packages needed at runtime. Do not invent new layer ordering or USER patterns outside what the template establishes.

Gather Inputs First

Before writing container files, confirm or infer:

• plugin name and language (Python, Rust, TypeScript)
• HTTP port the server listens on (default: 8080)
• required environment variables from .env.example
• any volume mounts (data directories, socket paths)
• whether the plugin needs network access to other Compose services

Reviewing Existing Container Config

Check for these common drift patterns:

• single-stage Dockerfile (no builder/runtime split)
• USER root in the runtime stage
• baked-in secrets or hardcoded URLs in the image
• missing healthcheck in Compose
• /health endpoint absent or not returning HTTP 200
• .env referenced via inline environment: block instead of env_file:
• no .dockerignore or patterns that are too broad (e.g., * ignoring everything)
• entrypoint.sh that does not validate all vars from .env.example

Produce a findings list with file references before making any changes.

Updating Container Config

When modifying an existing config:

1. Identify the specific gap from the findings list
2. Apply the targeted change — avoid rewriting stable layers unnecessarily
3. Verify entrypoint.sh still validates all env vars after any .env.example additions
4. Confirm the Compose healthcheck interval/timeout matches the server's actual startup time
5. Re-test locally with just build && just up before considering complete

Deploy Strategy

Standard homelab deploy workflow:

1. CI builds and pushes the image on a tagged release (see pipeline-lab-plugin)
2. The Compose file is checked into the plugin repo
3. Secrets are provided via .env on the host — never committed to git
4. Deploy command on the host:

   docker compose pull
   docker compose up -d
   

Rollback

To roll back to a prior release, pin the previous image tag in docker-compose.yaml and redeploy:

# docker-compose.yaml — pin to prior tag to roll back
services:
  my-plugin:
    image: ghcr.io/owner/my-plugin:1.2.3   # was: 1.3.0

Then apply:

docker compose up -d

The running container is replaced with the pinned version. No scale-to-zero step is needed. After confirming the rollback is stable, either fix forward and cut a new release, or update the pinned tag to the correct prior version permanently.

To confirm the rollback succeeded:

docker compose ps
docker compose logs my-plugin --tail 50
curl -sf http://localhost:8080/health

Required Output

At minimum, produce:

• Dockerfile — multi-stage, non-root runtime stage
• entrypoint.sh — validates all vars from .env.example, then execs the server
• docker-compose.yaml — service with env_file, healthcheck, correct port
• .dockerignore — excludes .env, dev artifacts, test data
• Confirmation or stub of /health endpoint in server code
• Summary of assumptions made (port, volumes, env vars, language template used)

Verification

After generating or updating container files:

# Validate Compose config parses cleanly
docker compose config --quiet

# Check shell syntax on entrypoint
bash -n entrypoint.sh

# Build the image locally
just build

# Start and confirm health
just up
curl -sf http://localhost:8080/health && echo "healthy"

# Check logs for startup errors
docker compose logs my-plugin --tail 50

Related Skills

• scaffold-lab-plugin — creates the initial plugin structure that this skill containerizes
• pipeline-lab-plugin — CI builds and pushes the image that this skill's Compose file references
• align-lab-plugin — use to audit and fix an existing Docker config for canonical drift