Rundeck: Runbook Automation

By Kokil Thapa | Last reviewed: September 2026

Your on-call engineer should not need root SSH access to restart PHP-FPM after every deploy. Rundeck: Runbook automation gives operators a web UI and API to run pre-approved tasks on tagged servers, with logs, notifications, and role-based access baked in. I have maintained production Laravel stacks on Ubuntu with Linux system administration workflows for years, and Rundeck fills a gap that raw cron and ad-hoc SSH scripts never close. This guide covers install, job design, ACLs, and how Rundeck compares to tools you may already use.

What is Rundeck runbook automation and when should you use it?

Rundeck is an open-source runbook and job orchestration server. You define jobs — sequences of steps that run on one or more nodes — and grant users permission to execute them without direct server access. Each run produces a timestamped log you can search during incident review.

Runbook automation differs from application CI/CD. Your GitLab pipeline builds assets and runs Deployer; Rundeck handles operational tasks that do not belong in every deploy: clearing cache, rotating logs, restarting queue workers, or running a one-off database repair. On sister legal-tech sites I maintain with Deployer 7 and GitLab CI, Rundeck-style patterns reduce the number of people who need production SSH keys.

Use Rundeck when you have recurring operational tasks, multiple environments, and a small team where not everyone should hold root access. Skip it when a single cron on one server covers everything, or when Ansible playbooks already give you a full UI through AWX or Semaphore with no extra need.

Good runbooks start with clear intent. Before you install anything, list the top ten tasks your team runs manually each month. Restart services, flush Redis, trigger backups, and scale workers belong here. Map each task to a target node tag such as env:production or role:web. That inventory work pays off faster than any plugin.

How do you install and configure Rundeck for production?

Rundeck runs on Java and stores job definitions in its database. The official project documentation at docs.rundeck.com covers Docker, RPM, and Debian packages. For a small Nepali agency stack on Ubuntu 24 with MySQL 8.4 LTS or PostgreSQL 18, a dedicated VM with 2 vCPU and 4 GB RAM is a sensible starting point.

Install on Ubuntu with Docker Compose

Docker is the fastest path to a working lab. Pin the image tag in production rather than using latest.

# docker-compose.yml (minimal lab stack)
services:
  rundeck:
    image: rundeck/rundeck:5.8.0
    ports:
      - "4440:4440"
    environment:
      RUNDECK_GRAILS_URL: https://rundeck.example.com
      RUNDECK_DATABASE_DRIVER: org.postgresql.Driver
      RUNDECK_DATABASE_URL: jdbc:postgresql://db:5432/rundeck
      RUNDECK_DATABASE_USERNAME: rundeck
      RUNDECK_DATABASE_PASSWORD: ${RUNDECK_DB_PASSWORD}
    volumes:
      - rundeck-data:/home/rundeck/server/data
volumes:
  rundeck-data:

Place Rundeck behind Nginx or Apache with TLS. Use Let's Encrypt the same way you would for a Laravel app. Restrict port 4440 to your VPN or office IP range. Default admin credentials must be changed on first login.

Configure framework.properties and node inventory

Rundeck discovers nodes through a resources.xml file, SSH, or plugins like Ansible inventory. For Laravel fleets I usually start with a static YAML file and graduate to dynamic inventory once tags stabilise.

# /etc/rundeck/project.properties (excerpt)
resources.source.1.type=file
resources.source.1.config.file=/var/rundeck/projects/production/resources.xml
resources.source.1.config.format=resourcexml
resources.source.1.config.generateFileAutomatically=true
resources.source.1.config.includeServerNode=true

Each node entry needs hostname, username, and tags. Rundeck uses SSH key-based auth from its service account. Generate a dedicated key pair; never reuse a developer's personal key.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <node name="web-01" hostname="10.0.1.10" username="rundeck"
        tags="env:production,role:web,stack:laravel" osFamily="unix"/>
  <node name="web-02" hostname="10.0.1.11" username="rundeck"
        tags="env:production,role:web,stack:laravel" osFamily="unix"/>
</project>

Grant the Rundeck user passwordless sudo only for commands your jobs require. A common pattern is a single /usr/local/bin/rundeck-allowed wrapper vetted in git. That beats handing out unrestricted sudo.

Wire notifications and external auth

Configure email or Slack webhooks under Project Settings → Notifications. LDAP, OIDC, and SAML integrations ship with Enterprise tiers; the open-source build supports local users plus API tokens. Store API tokens in your secrets manager, not in job definitions committed to git.

How do you create your first runbook job in Rundeck?

Jobs can be built in the UI or stored as YAML under version control. Git-backed jobs are easier to review in pull requests and align with how you already treat build pipeline automation best practices. The Rundeck job definition format is documented in the Job YAML reference.

Example: restart PHP-FPM and reload Laravel queues

This job targets all production web nodes, restarts PHP 8.4 FPM, and signals queue workers. Adjust paths for your PHP version and deploy layout.

# jobs/restart-web-stack.yaml
- defaultTab: nodes
  description: Restart PHP-FPM and Laravel queue workers on web tier
  executionEnabled: true
  group: laravel-ops
  name: Restart Web Stack
  nodeFilterEditable: false
  nodefilters:
    filter: 'tags: role:web + env:production'
  notification:
    onfailure:
      plugin:
        type: slack-webhook
        configuration:
          webhookUrl: ${option.slackWebhook}
  scheduleEnabled: false
  sequence:
    commands:
    - script: |
        #!/bin/bash
        set -euo pipefail
        sudo systemctl restart php8.4-fpm
        cd /var/www/current
        sudo -u www-data php artisan queue:restart
        sudo -u www-data php artisan config:cache
    keepgoing: false
    strategy: node-first
  uuid: restart-web-stack-prod

Import the job with the CLI:

rd jobs load --file jobs/restart-web-stack.yaml --project production --format yaml

Add job options for safer self-service. A dropdown for environment with values staging and production prevents typos. Use an approval workflow plugin or Rundeck Enterprise change-request steps before production runs if your compliance team requires it.

Job options, workflows, and error handling

Rundeck supports multi-step workflows with conditions. A typical deploy-adjacent runbook might:

1. Run a health check against /health.
2. Put the node in maintenance mode via php artisan down.
3. Execute the maintenance command.
4. Run smoke tests with curl.
5. Bring the node back with php artisan up.

Set keepgoing: false on destructive steps so a failed health check aborts the chain. Log output streams back to the Rundeck UI in real time. Export logs to S3 or your log aggregator if you need long-term retention beyond the default database store.

For JSON payloads in webhook-triggered jobs, validate structure before execution. A quick sanity check with your internal JSON formatter tool during development catches malformed API bodies early.

How does Rundeck compare to Ansible, Jenkins, and Laravel Envoy?

Teams often ask whether Rundeck replaces Ansible or CI servers. In practice these tools overlap but serve different primary jobs. Rundeck excels at human-triggered operational runbooks with a friendly UI. Ansible excels at declarative configuration drift correction. Jenkins and GitLab CI excel at build-test-deploy pipelines tied to git events.

I still use Deployer 7 with GitLab CI for Laravel releases on projects like Adventure Third Pole Trek. Rundeck sits beside that stack, not instead of it. For ad-hoc remote tasks from a developer laptop, Laravel Envoy for remote task automation remains lighter when you trust every operator with SSH. Once the team grows past three people, Rundeck ACLs become worth the overhead.

Ansible can execute the same shell commands Rundeck runs. The difference is operator experience and audit. AWX adds a UI comparable to Rundeck; choosing between them often comes down to which tool your team already knows. Read Ansible roles and Galaxy reusable automation if your gap is configuration drift, not runbook UI.

Some teams chain tools: CI deploys code, Rundeck job triggered by webhook clears opcode cache, Ansible playbook runs weekly security updates. Keep boundaries clear so no single job both deploys git HEAD and reformats disks.

What ACL and security patterns work for Rundeck runbook automation?

Access control is where Rundeck earns its keep. ACL policies live in YAML under aclpolicy/ and define who may run, read, or edit which jobs. The open-source project ships examples in the Rundeck GitHub repository.

Sample ACL policy for developers vs operators

# aclpolicy/dev-runbooks.yaml
description: Developers can run staging jobs only
context:
  project: production
for:
  job:
    - equals:
        group: laravel-ops
      allow: [read]
    - match:
        name: '.*'
        group: staging-ops
      allow: [read, run]
  node:
    - match:
        tags: 'env:staging'
      allow: [read]
by:
  group: developers

Operators in the ops group get run access on production job groups. Developers see production jobs read-only but can execute staging equivalents. Never grant admin to run-only users.

Security practices that survive audits

• Store secrets in Rundeck Key Storage or HashiCorp Vault plugins, not in job YAML.
• Enable job execution history retention aligned with your compliance window.
• Require job option confirmation for destructive actions like database truncate.
• Restrict Rundeck API tokens to IP ranges or short TTLs.
• Review ACL diffs in pull requests the same way you review application code.

Pair Rundeck with the incident patterns in on-call and incident response runbook documentation. When pager duty fires, the on-call engineer opens a pre-built Rundeck job instead of improvising shell history from three months ago.

What are common Rundeck runbook automation mistakes in production?

Most failures I have seen are organisational, not technical. Teams import fifty jobs before they define node tags. Operators cannot find the right restart job during an outage. Fix taxonomy first: group jobs by service, environment, and risk level.

Another recurring issue is running jobs as root when a service account suffices. Laravel artisan commands should execute as www-data. Database admin tasks need a separate job with tighter ACL and optional approval.

Stale node inventory causes silent no-ops. Automate inventory refresh from your cloud provider or Ansible. After every autoscaling event, nodes must appear in Rundeck within minutes.

Do not duplicate your entire CI pipeline inside Rundeck. Build and test stay in GitLab CI. Rundeck handles post-deploy operational steps and break-glass procedures documented in write effective runbooks guides.

Finally, test jobs in staging with the same ACL groups you use in production. A job that works when run as admin often fails when a developer triggers it under restricted permissions. Catch that before Dashain traffic spikes hit your eCommerce clients.

For broader automation strategy across build, test, and ops, see build automation: a complete guide and Python for DevOps automation. If you need help wiring runbooks into an existing Laravel fleet, AI integration and automation services and support and maintenance cover the operational layer beyond application code.

Key Takeaways

• Rundeck runbook automation centralises approved ops tasks with ACLs, scheduling, and searchable execution logs.
• Install on a dedicated VM with TLS, git-backed YAML jobs, and SSH keys scoped to a Rundeck service account.
• Use node tags like env:production and role:web so jobs target the right servers without hard-coded hostnames.
• Keep CI/CD in GitLab or Jenkins; use Rundeck for human-triggered and scheduled operational runbooks.
• Define ACL policies per group before exposing production jobs to the wider team.
• Chain health checks and smoke tests in multi-step workflows so failed runs abort safely.

People Also Ask

Is Rundeck free for production use?

The open-source Rundeck Community edition is free and sufficient for many small teams. Enterprise adds advanced ACL workflows, SSO integrations, and commercial support. Start with Community on a single project; upgrade when compliance or SSO requirements appear.

Can Rundeck replace Ansible entirely?

No. Ansible declares desired server state; Rundeck executes procedural runbooks on demand. Many teams use both, or connect Rundeck to Ansible inventory and playbooks through plugins. Pick the tool that matches whether the task is drift correction or operator self-service.

How do you trigger Rundeck jobs from CI after deploy?

Call the Rundeck API with a token at the end of your pipeline. Pass the git SHA as a job option so logs tie back to the release. Keep deploy and post-deploy restart as separate steps so a failed restart does not roll back a good build.

Does Rundeck work with Windows servers?

Yes. Rundeck supports WinRM nodes alongside SSH Unix nodes. Tag Windows hosts with osFamily: windows and use PowerShell script steps. Mixed fleets are common in agencies that manage both Linux Laravel apps and Windows file servers.

Ship safer operations with Rundeck runbook automation

Rundeck: Runbook automation turns tribal shell knowledge into repeatable, auditable jobs your whole team can trust. Start with five high-value tasks — PHP-FPM restart, queue restart, cache flush, log rotation, backup verify — and expand only after ACLs and node tags are stable. Pair it with your existing GitLab CI and Deployer workflow rather than replacing it.

If you want help designing runbooks for a Laravel or WordPress fleet in Nepal or abroad, review the Notary Kathmandu deployment pipeline case study and reach out via contact us. You can also explore enterprise application development and Chef infrastructure automation for related patterns. For day-to-day scripting hooks, git hooks for automation and regression testing automation round out a sensible ops toolchain. Visit kokil.com.np or read more on the blog and about me page.