Operating System CentOS

How to Install and Configure GoCD on AlmaLinux 9 and Rocky Linux 9

Install GoCD server and agent on the RHEL 9 family from the official repository, enable authentication, and learn what the project's volunteer-maintained status means.

This guide installs a GoCD server and a GoCD agent on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9 from the project's own package repository, connects the agent to the server and protects the dashboard with a login. GoCD's documentation lists "CentOS/RHEL version 8+" and compatible distributions such as AlmaLinux and Rocky Linux as supported; CentOS 7 reached end of life in June 2024 and is not.

Project status: read this first

GoCD is still released, but it is not actively developed. Thoughtworks ended commercial support and funded development in December 2020. According to the project's own status statement, GoCD is "neither officially end-of-life, nor fully abandoned": a very small group of volunteers publishes a few releases a year, mostly security fixes, bug fixes and dependency updates, and major new features are unlikely. Old releases are not patched.

In practice this means:

  • Always run the latest release. The release notes for GoCD 26.1.0 state that effectively all earlier versions are affected by serious vulnerabilities fixed in that release.
  • Do not expose the server directly to the internet without authentication and TLS.
  • For a new installation, weigh GoCD against actively developed CI/CD systems before committing to it. For an existing GoCD setup, the steps below are the supported way to move it to a current operating system.

Requirements

  • A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9. The documented minimum for the GoCD server is 1 GB of RAM (2 GB recommended) and two CPU cores; an agent needs at least 128 MB (256 MB recommended).
  • A user with sudo rights.
  • Java 21 or newer. Since GoCD 26.1.0, Java 21 is the minimum supported version. You normally do not install it yourself: the packages pull in a compatible runtime as a weak dependency.

Add the GoCD repository

Download the repository definition. It enables the stable gocd repository with GPG checking and leaves the experimental one disabled:

sudo curl https://download.gocd.org/gocd.repo -o /etc/yum.repos.d/gocd.repo

Install and start the GoCD server

Install the server. The install_weak_deps option makes sure the recommended Java runtime is installed even if weak dependencies are disabled in your dnf configuration:

sudo dnf install -y --setopt=install_weak_deps=true go-server

Confirm that a Java runtime is present, then start the server and enable it at boot:

java -version
sudo systemctl enable --now go-server
systemctl status go-server

If the package warned that no compatible Java runtime was found, install one (version 21 or newer) and point GoCD to it in /usr/share/go-server/wrapper-config/wrapper-properties.conf, following the comments in that file. Do not edit wrapper.conf in the same directory; it holds the defaults and is replaced on upgrade.

The first start takes a minute or two. The dashboard listens on port 8153 under the path /go. Open the port for your own address only, for example for the workstation at 198.51.100.25:

sudo firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="198.51.100.25" port port="8153" protocol="tcp" accept'
sudo firewall-cmd --reload

Then browse to http://203.0.113.10:8153/go, replacing the address with your server's.

The server's files are in these locations:

PathContents
/etc/goServer configuration
/var/lib/go-server/dbDatabase
/var/lib/go-server/artifactsBuild artifacts
/var/lib/go-server/pluginsPlugins
/var/log/go-serverLogs
/usr/share/go-serverBinaries and startup configuration

Artifacts grow quickly. If the server has a separate data volume, mount it at /var/lib/go-server/artifacts before you start building.

Enable authentication

A fresh GoCD server lets anyone who can reach it administer it, so set up logins before adding pipelines. The bundled password file plugin reads an htpasswd-style file. Create one with a bcrypt-hashed password:

sudo dnf install -y httpd-tools
sudo htpasswd -c -B /etc/go/passwd admin
sudo chown go:go /etc/go/passwd
sudo chmod 600 /etc/go/passwd

In the dashboard, open Admin > Security > Authorization Configuration, click Add, enter any ID, choose Password File Authentication Plugin for GoCD and enter /etc/go/passwd as the password file path. Save, then reload the page: GoCD now asks for the user name and password. Add further users later with sudo htpasswd -B /etc/go/passwd username (without -c, which would overwrite the file).

Install and connect an agent

The server only schedules work; agents run it. For a small setup you can install an agent on the same machine, but separate machines are the normal layout. On the agent host, add the repository as above and install the package:

sudo curl https://download.gocd.org/gocd.repo -o /etc/yum.repos.d/gocd.repo
sudo dnf install -y --setopt=install_weak_deps=true go-agent

If the agent is on a different machine than the server, edit /usr/share/go-agent/wrapper-config/wrapper-properties.conf and set the GoCD server URL as described in the comments in that file, for example http://203.0.113.10:8153/go. An agent on the server itself uses the default local address and needs no change. Start the agent:

sudo systemctl enable --now go-agent

Agents on other hosts must be able to reach port 8153 on the server, so add a firewall rule for each agent address like the one above.

New agents are disabled until you approve them. In the dashboard, open the Agents tab, select the new agent and click Enable. From then on the server assigns jobs to it. The agent's working directory is /var/lib/go-agent and its logs are in /var/log/go-agent.

Build tools are not part of the agent. Install whatever your pipelines call (Git, compilers, container tools) on each agent host with dnf.

Upgrading and backups

Because old GoCD versions do not receive fixes, upgrading is part of running it. Update server and agents together:

sudo dnf upgrade go-server go-agent
sudo systemctl restart go-server
sudo systemctl restart go-agent

Read the release notes on gocd.org/releases first; they list breaking changes such as the minimum Java version. Before an upgrade, take a backup from Admin > Backup in the dashboard and copy /etc/go and the backup directory off the server.

Troubleshooting

  • The service does not start: check /var/log/go-server/go-server.log and journalctl -u go-server. A missing or too-old Java runtime is the usual cause.
  • The agent does not appear in the dashboard: check /var/log/go-agent for connection errors, confirm the server URL in wrapper-properties.conf and that port 8153 is reachable from the agent.
  • The dashboard is reachable from everywhere: remove any broad 8153/tcp firewall rule and put a TLS-terminating reverse proxy in front of the server; the GoCD documentation has a section on reverse proxy configuration.

Frequently asked questions

Is GoCD discontinued?

No, but it is in a low-activity, volunteer-maintained state without vendor backing. Releases continue (26.1.0 at the time of writing, described by the project as a security, maintenance and bug-fix release), and there is no commercial support. Treat it as software you must keep patched yourself.

Do I need to install Java separately?

Usually not. The RPM recommends a compatible Java package and dnf installs it with the server or agent. You only need to act if weak dependencies were skipped or you want a specific runtime, in which case install Java 21 or newer and reference it in wrapper-properties.conf.

Can I install GoCD on Ubuntu or Debian instead?

Yes. The project publishes an APT repository at the same address and supports Ubuntu 22 and above and Debian 11 and above. The packages have the same names, go-server and go-agent, and use the same paths.

Which database does GoCD use?

A default installation uses an embedded H2 database stored under /var/lib/go-server/db. The documentation also describes PostgreSQL and MySQL as external databases for larger installations.

Share story:

Continue reading other guides on How VPS.