How to Install Woodpecker CI on RHEL 10

Introduction

Setting up install woodpecker ci on a RHEL 10 server is a common task for system administrators, DevOps engineers, and site reliability engineers. This guide explains how to Install Woodpecker CI on RHEL 10, with all the commands you need, the SELinux and firewalld considerations to keep in mind, and how to validate the result on the live system.

Prerequisites

The procedure assumes you are working on a fully patched RHEL 10 machine. Run sudo dnf upgrade -y before continuing so you start from a known good baseline. SELinux should be in enforcing mode (the default), and firewalld should be running. You will also need a user account with sudo privileges configured in /etc/sudoers.d/.

Step 1: Update RHEL 10 and Enable Repositories

Ensure your RHEL 10 system is fully patched before installing new software. The AppStream repository is enabled by default on registered systems and provides the modular packages needed for most modern workloads. If you are running this inside a Kickstart automation or an Ansible role, capture every command into version control so the deployment can be re-run from scratch against a fresh VM at any time.

sudo dnf upgrade -y
sudo dnf repolist enabled

Step 2: Install Required Packages

Install the woodpecker-server package along with any supporting dependencies from the standard RHEL 10 repositories. dnf will automatically resolve and pull in libraries, language runtimes, and configuration files. Pay attention to file ownership and permissions here — a service that is misconfigured at the file-system level will fail in subtle, hard-to-diagnose ways even though dnf reports a clean install.

sudo dnf install -y woodpecker-server

Step 3: Apply the Initial Configuration

Now configure the component for your environment. Always keep a backup copy of the original configuration file so you can roll back quickly if something goes wrong, and prefer editing files in /etc/ over modifying the package defaults inside /usr/share/. If you are running this inside a Kickstart automation or an Ansible role, capture every command into version control so the deployment can be re-run from scratch against a fresh VM at any time.

sudo cp /etc/woodpecker/woodpecker.conf /etc/woodpecker/woodpecker.conf.bak
sudo nano /etc/woodpecker/woodpecker.conf  # edit settings as required

Step 4: Enable and Start the woodpecker Service

systemd is responsible for service lifecycle on RHEL 10. The enable --now flag both starts the service immediately and configures it to launch automatically at every boot, which is the behavior you almost always want for a server-side component. Pay attention to file ownership and permissions here — a service that is misconfigured at the file-system level will fail in subtle, hard-to-diagnose ways even though dnf reports a clean install.

sudo systemctl enable --now woodpecker
sudo systemctl status woodpecker --no-pager

Step 5: Open the Required Firewalld Port

firewalld is the default firewall on RHEL 10 and uses nftables under the hood. Open only the specific port required for this service, and prefer named services over raw port numbers where they exist because they survive port-number changes upstream. Pay attention to file ownership and permissions here — a service that is misconfigured at the file-system level will fail in subtle, hard-to-diagnose ways even though dnf reports a clean install.

sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

Step 6: SELinux Considerations

SELinux runs in enforcing mode by default on RHEL 10. If your service needs to write outside its default directories, bind to non-standard ports, or connect outbound to other services, you will need to set the appropriate boolean or label the files. The commands below are a typical starting point. Pay attention to file ownership and permissions here — a service that is misconfigured at the file-system level will fail in subtle, hard-to-diagnose ways even though dnf reports a clean install.

sudo semanage port -a -t http_port_t -p tcp 8000
# only if you change the listening port
sudo ausearch -m AVC -ts recent

Step 7: Inspect Service Logs

All systemd-managed services on RHEL 10 stream their output to the journal, which is searchable, indexed, and persists across reboots once you create /var/log/journal. Use journalctl to follow logs in real time and to investigate startup failures. If you are running this inside a Kickstart automation or an Ansible role, capture every command into version control so the deployment can be re-run from scratch against a fresh VM at any time.

sudo journalctl -u woodpecker -e --no-pager
sudo journalctl -u woodpecker -f

Troubleshooting Common Issues

If the service refuses to start, the first place to look is the systemd journal — every service on RHEL 10 logs there by default. Filter to the last boot to avoid wading through historical entries. The second most common class of problem on a fresh install is SELinux denials, especially when a service tries to read from or write to a directory that is not labelled with its expected type. Use ausearch -m AVC -ts recent to look for denials, and either set the correct file context with semanage fcontext + restorecon or flip the relevant boolean. Finally, if the service starts but is unreachable, double-check firewalld with firewall-cmd --list-all and confirm the runtime configuration matches the permanent one.

sudo journalctl -b --priority=err
sudo ausearch -m AVC -ts recent
sudo firewall-cmd --list-all

Best Practices and Hardening

For any production deployment on RHEL 10 you should track configuration in a version control system, apply security errata regularly with dnf-automatic, and centralise log collection so that a compromised host cannot quietly erase its own audit trail. Run periodic OpenSCAP compliance scans against the CIS or DISA STIG profile to catch drift. If the service exposes a network port, place it behind a reverse proxy or VPN where possible and rotate any credentials it uses on a schedule. Snapshot the system (using Stratis, LVM, or your hypervisor) before every major change so you have a fast rollback path.

sudo dnf install -y dnf-automatic
sudo systemctl enable --now dnf-automatic.timer
sudo oscap xccdf eval --profile xccdf_org.ssgproject.content_profile_cis /usr/share/xml/scap/ssg/content/ssg-rhel10-ds.xml

Verification

After completing every step, run a quick set of checks to confirm the deployment is healthy on RHEL 10. Examine the systemd unit state to make sure no units have failed, look for any SELinux denials in the audit log, inspect the listening sockets to confirm the service is bound to the expected interface and port, and finally make a real client request to validate end-to-end functionality. If any of those four checks fail, return to the troubleshooting section before treating the deployment as complete.

sudo systemctl --failed
sudo ausearch -m AVC -ts recent || true
sudo ss -tulpn
sudo journalctl --since "10 minutes ago" --priority=warning

Conclusion

By following this guide you have a working install woodpecker ci setup on RHEL 10 that follows Red Hat’s recommended practices. The system is ready for production use: services are enabled at boot, log output flows to the systemd journal, and the firewall is locked down to only the ports you opened. Schedule regular dnf-automatic security updates to keep it that way.

Looking forward, consider encoding the steps above as an Ansible role so the procedure becomes reproducible across your entire fleet, and add a Prometheus scrape config (or a Zabbix template) so the service is monitored from the moment it starts. Pair the deployment with a backup strategy — restic, borgbackup, or rsnapshot all work well on RHEL 10 — so that recovery from data loss is a matter of minutes rather than hours.