Distribution packages

tip

For a full list of operating systems and architectures that Woodpecker is built for, including which components are available on each, see Supported platforms.

Official packages

• DEB
• RPM

DEB and RPM packages are built for linux/amd64 and linux/arm64. For other architectures, use the binary tarballs or container images linked from the Supported platforms page.

The pre-built packages are available on the GitHub releases page. The packages can be installed using the package manager of your distribution.

RELEASE_VERSION=$(curl -s https://api.github.com/repos/woodpecker-ci/woodpecker/releases/latest | grep -Po '"tag_name":\s"v\K[^"]+')

# Debian/Ubuntu (x86_64)
curl -fLOOO "https://github.com/woodpecker-ci/woodpecker/releases/download/v${RELEASE_VERSION}/woodpecker-{server,agent,cli}_${RELEASE_VERSION}_amd64.deb"
sudo apt --fix-broken install ./woodpecker-{server,agent,cli}_${RELEASE_VERSION}_amd64.deb

# CentOS/RHEL (x86_64)
sudo dnf install https://github.com/woodpecker-ci/woodpecker/releases/download/v${RELEASE_VERSION}/woodpecker-{server,agent,cli}-${RELEASE_VERSION}-1.x86_64.rpm

The package installation will create a systemd service file for the Woodpecker server and agent along with an example environment file. To configure the server, copy the example environment file /etc/woodpecker/woodpecker-server.env.example to /etc/woodpecker/woodpecker-server.env and adjust the values.

/usr/local/lib/systemd/system/woodpecker-server.service

[Unit]
Description=WoodpeckerCI server
Documentation=https://woodpecker-ci.org/docs/administration/server-config
Requires=network.target
After=network.target
ConditionFileNotEmpty=/etc/woodpecker/woodpecker-server.env
ConditionPathExists=/etc/woodpecker/woodpecker-server.env

[Service]
Type=simple
EnvironmentFile=/etc/woodpecker/woodpecker-server.env
User=woodpecker
Group=woodpecker
ExecStart=/usr/local/bin/woodpecker-server
WorkingDirectory=/var/lib/woodpecker/
StateDirectory=woodpecker

[Install]
WantedBy=multi-user.target

/etc/woodpecker/woodpecker-server.env

WOODPECKER_OPEN=true
WOODPECKER_HOST=${WOODPECKER_HOST}
WOODPECKER_GITHUB=true
WOODPECKER_GITHUB_CLIENT=${WOODPECKER_GITHUB_CLIENT}
WOODPECKER_GITHUB_SECRET=${WOODPECKER_GITHUB_SECRET}
WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

After installing the agent, copy the example environment file /etc/woodpecker/woodpecker-agent.env.example to /etc/woodpecker/woodpecker-agent.env and adjust the values as well. The agent will automatically register itself with the server.

/usr/local/lib/systemd/system/woodpecker-agent.service

[Unit]
Description=WoodpeckerCI agent
Documentation=https://woodpecker-ci.org/docs/administration/configuration/agent
Requires=network.target
After=network.target
ConditionFileNotEmpty=/etc/woodpecker/woodpecker-agent.env
ConditionPathExists=/etc/woodpecker/woodpecker-agent.env

[Service]
Type=simple
EnvironmentFile=/etc/woodpecker/woodpecker-agent.env
User=woodpecker
Group=woodpecker
ExecStart=/usr/local/bin/woodpecker-agent
WorkingDirectory=/var/lib/woodpecker/
StateDirectory=woodpecker

[Install]
WantedBy=multi-user.target

/etc/woodpecker/woodpecker-agent.env

WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET=${WOODPECKER_AGENT_SECRET}

Manual installation from Linux binaries

1. Download the Woodpecker server and agent tarballs for your Linux architecture from the GitHub releases page.

2. Extract both tarballs and install the woodpecker-server and woodpecker-agent binaries in /usr/local/bin/. This example uses Linux ARM64; choose tarballs matching your architecture. Run these commands from the directory containing the downloaded tarballs.

   tar -xzf woodpecker-server_linux_arm64.tar.gz
   tar -xzf woodpecker-agent_linux_arm64.tar.gz
   sudo install -m 755 woodpecker-server woodpecker-agent /usr/local/bin/

3. Create the /etc/woodpecker directory and the server and agent environment files using the examples above. Replace the ${...} placeholders with values for your installation, including the public WOODPECKER_HOST URL. Set the same WOODPECKER_AGENT_SECRET value in both files.

   sudo mkdir -p /etc/woodpecker
   sudoedit /etc/woodpecker/woodpecker-server.env
   sudoedit /etc/woodpecker/woodpecker-agent.env

4. Create the woodpecker system user and its working directory.

   sudo useradd --system --user-group --home-dir /var/lib/woodpecker --create-home --shell /usr/sbin/nologin woodpecker

   Save the server and agent systemd unit examples above as /etc/systemd/system/woodpecker-server.service and /etc/systemd/system/woodpecker-agent.service. Then load and start the services:

   sudo systemctl daemon-reload
   sudo systemctl enable --now woodpecker-server woodpecker-agent

5. Check that both services are running:

   systemctl status woodpecker-server woodpecker-agent

   Check the agent logs for connection errors, then confirm that the agent appears in the Woodpecker server's agent list:

   journalctl -u woodpecker-agent -b

Community packages

info

Woodpecker itself is not responsible for creating these packages. Please reach out to the people responsible for packaging Woodpecker for the individual distributions.

• Alpine (Edge)
• Arch Linux
• openSUSE
• YunoHost
• Cloudron
• Easypanel
• Homebrew (CLI only)

NixOS

info

This module is not maintained by the Woodpecker developers. If you experience issues please open a bug report in the nixpkgs repo where the module is maintained.

In theory, the NixOS installation is very similar to the binary installation and supports multiple backends. In practice, the settings are specified declaratively in the NixOS configuration and no manual steps need to be taken.

{ config
, ...
}:
let
  domain = "woodpecker.example.org";
in
{
  # This automatically sets up certificates via let's encrypt
  security.acme.defaults.email = "acme@example.com";
  security.acme.acceptTerms = true;

  # Setting up a nginx proxy that handles tls for us
  services.nginx = {
    enable = true;
    openFirewall = true;
    recommendedTlsSettings = true;
    recommendedOptimisation = true;
    recommendedProxySettings = true;
    virtualHosts."${domain}" = {
      enableACME = true;
      forceSSL = true;
      locations."/".proxyPass = "http://localhost:3007";
    };
  };

  services.woodpecker-server = {
    enable = true;
    environment = {
      WOODPECKER_HOST = "https://${domain}";
      WOODPECKER_SERVER_ADDR = ":3007";
      WOODPECKER_OPEN = "true";
    };
    # You can pass a file with env vars to the system it could look like:
    # WOODPECKER_AGENT_SECRET=XXXXXXXXXXXXXXXXXXXXXX
    environmentFile = "/path/to/my/secrets/file";
  };

  # This sets up a woodpecker agent
  services.woodpecker-agents.agents."docker" = {
    enable = true;
    # We need this to talk to the podman socket
    extraGroups = [ "podman" ];
    environment = {
      WOODPECKER_SERVER = "localhost:9000";
      WOODPECKER_MAX_WORKFLOWS = "4";
      DOCKER_HOST = "unix:///run/podman/podman.sock";
      WOODPECKER_BACKEND = "docker";
    };
    # Same as with woodpecker-server
    environmentFile = [ "/var/lib/secrets/woodpecker.env" ];
  };

  # Here we setup podman and enable dns
  virtualisation.podman = {
    enable = true;
    defaultNetwork.settings = {
      dns_enabled = true;
    };
  };
  # This is needed for podman to be able to talk over dns
  networking.firewall.interfaces."podman0" = {
    allowedUDPPorts = [ 53 ];
    allowedTCPPorts = [ 53 ];
  };
}

All configuration options can be found via NixOS Search. There are also some additional resources on how to utilize Woodpecker more effectively with NixOS on the Awesome Woodpecker page, like using the runners nix-store in the pipeline.