SEC.01
The playbook
The run starts read-only: the recon probes decide what happens next. The steps that follow are adapted to the distribution and state found — a real machine is rarely clean.
- 01reconDocker Engine + compose plugin installed and service active?
- 02reconalready deployed? existing containers, volumes and /opt/woodpecker (→ do not regenerate secrets)
- 03reconports 8000 (local Woodpecker), 80/443 (reverse proxy) free, or held by what?
- 04reconreverse proxy already in place (Caddy/nginx) to reuse?
- 05recondistro, version, architecture and package manager (apt-get → Debian/Ubuntu, dnf → RHEL/Fedora/Rocky/Alma)
- 06reconfirewall active (ufw/firewalld) → open 80/443 only
- 07reconat least 1 GB of RAM and a few GB free
- 08actInstall Docker Engine (if missing)verify
- 09actGenerate the secretsverify
- 10actWrite /opt/woodpecker/compose.yamlverify
- 11actStart Woodpeckerverify
- 12actHTTPS reverse proxy for ${domain}verify
SEC.02
What it verifies
Each step ships its own check. The run only moves on when the check passes, so what the recipe reports as done is what is actually on the server.
- 01verifyInstall Docker Engine (if missing)Verified by
systemctl is-active docker && docker compose version - 02verifyGenerate the secretsVerified by
stat -c "%a %n" /opt/woodpecker/server.env /opt/woodpecker/agent.env - 03verifyWrite /opt/woodpecker/compose.yamlVerified by
docker compose -f /opt/woodpecker/compose.yaml config -q && echo ok - 04verifyStart WoodpeckerVerified by
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8000/healthz - 05verifyHTTPS reverse proxy for ${domain}Verified by
curl -s -o /dev/null -w '%{http_code}' https://${domain}/healthz
SEC.03
Guardrails
Non-negotiable instructions the run must respect, whatever it finds on the server.
OAuth secrets and the agent secret are never displayed (no cat of the .env files) and never regenerated if they exist. Port 8000 stays on 127.0.0.1; only the HTTPS proxy is public. Registration closed (WOODPECKER_OPEN=false): the agent has access to the Docker socket, so any user can run code as root. OAuth callback to declare in the forge: https://<domain>/authorize.
SEC.04
Variables
What you choose before launching — the recipe fills in the rest.
| Name | Meaning |
|---|---|
| ${domain} | Domain |
| ${forge} | Forge |
| ${forge_url} | Forge URL (Gitea/Forgejo/GitLab) |
| ${oauth_client} | OAuth client ID |
| ${oauth_secret} | OAuth client secret |
| ${admin} | Admin account (forge username) |
SEC.05
How a recipe runs in Servor
Servor is zero-knowledge: the platform cannot execute anything on its own. When you launch this recipe, a run reads the reconnaissance, plans the steps and asks for your approval. Each approved command is signed by your browser — with a key the server never sees — then relayed verbatim to the agent, which verifies the signature locally before executing.
search by intent — type “firewall”, get ufw
- 01Read-only reconnaissance before any change
- 02Every command signed by your browser, approved by you
- 03Each step verified before the run moves on, every run kept in the history
SEC.06
Deploy on Servor button
Maintain Woodpecker CI or a project that needs it? Put this button in your README or on your site: one click and your users install it on their own server.
Dark background
Light background[](https://servor.app/deploy/install-woodpecker)SEC.07
More ci/cd recipes
- 01GitHub Actions RunnerSelf-hosted GitHub Actions runner under a dedicated user, registered as a systemd service.
- 02GitLab RunnerGitLab Runner from the official repo, registered with the Docker or shell executor.
- 03Ansible (control node)Ansible installed as a control node from the distro packages.
- 04systemd serviceDaemonize a command into a managed systemd service (auto-restart, at boot).
- 05Scheduled task (cron)Add a scheduled task via a systemd timer (logged, catches up if missed).
Verified recipe
Run this recipe on your server
Connect a server, launch the recipe, and approve each step as Servor executes and verifies it. Free plan, no card required.