How to Install and Configure GoCD on Ubuntu 22.04

GoCD is an open-source continuous delivery and automation system. GoCD excels at modeling complex CD workflows for fast feedback with its modeling constructs, parallel execution, and dependency management. GoCD helps you troubleshoot a broken pipeline by tracking every change from commit to deployment in real-time. GoCD lets you easily compare two builds and deploy any version of the application you want. The GoCD ecosystem consists of a GoCD server and a GoCD agent. GoCD controls everything, such as running the web-based user interface and managing and providing jobs to the agent. Go agents are responsible for running the jobs and deployments.

This tutorial will teach you to install and configure GoCD on a Ubuntu 22.04 server.


  1. A server running Ubuntu 22.04 with a minimum of 2GB of RAM.

  2. A non-sudo user with root privileges.

  3. The uncomplicated Firewall(UFW) is enabled and running.

  4. Fully Qualified Domain Names(FQDN) pointing to your server. We will be using for our tutorial.

  5. Ensure that everything is updated.

    $ sudo apt update && sudo apt upgrade

Step 1 - Configure Firewall

Before installing any packages, the first step is configuring the firewall to open ports for HTTP, HTTPS, and Synapse.

Check the status of the firewall.

$ sudo ufw status

You should see something like the following.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)

Open the HTTP, HTTPS, and GoCD ports in the firewall.

$ sudo ufw allow 8153
$ sudo ufw allow http
$ sudo ufw allow https

Check the status again to confirm.

$ sudo ufw status
Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
8153                       ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
8153 (v6)                  ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Step 2 - Install GoCD

Import GoCD's GPG key into the system.

$ curl | gpg --dearmor | sudo tee /usr/share/keyrings/gocd.gpg > /dev/null 2>&1

Add the GoCD repository to the system.

$ echo "deb [signed-by=/usr/share/keyrings/gocd.gpg] /" | sudo tee /etc/apt/sources.list.d/gocd.list

Update the system repositories list.

$ sudo apt update

Install GoCD. This will also install the latest compatible version of Java Runtime(JRE) required to run GoCD.

$ sudo apt install -y go-server

Before we proceed to the next step, we need to create a directory to store the artifacts. Artifacts can either be stored on the same disk in which the server is installed or on a dedicated disk or block storage drive. We will store it on the same disk for this tutorial.

Create a directory to store the artifacts.

$ sudo mkdir /opt/artifacts

Give GoCD ownership to the artifact directory.

$ sudo chown -R go:go /opt/artifacts

Step 3 - Install and Configure PostgreSQL

GoCD ships with the H2 database by default which requires no configuration. If you are using GoCD in a production environment, PostgreSQL is recommended.

Ubuntu 22.04 ships with an older version of PostgreSQL. We will install Postgres 15 for our tutorial.

Install the repository for PostgreSQL.

$ sudo sh -c 'echo "deb $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

Import PostgreSQL GPG key.

$ curl | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/ >/dev/null

Update the system repository list.

$ sudo apt update

Install PostgreSQL 15 server.

$ sudo apt install -y postgresql postgresql-contrib

Check the status of the service.

$ sudo systemctl status postgresql
? postgresql.service - PostgreSQL RDBMS
     Loaded: loaded (/lib/systemd/system/postgresql.service; enabled; vendor preset: enabled)
     Active: active (exited) since Mon 2022-12-19 06:49:50 UTC; 2h 26min ago
   Main PID: 3536 (code=exited, status=0/SUCCESS)
        CPU: 1ms

Dec 19 06:49:50 gocd systemd[1]: Starting PostgreSQL RDBMS...
Dec 19 06:49:50 gocd systemd[1]: Finished PostgreSQL RDBMS.

Log in to the PostgreSQL shell.

$ sudo -i -u postgres psql

Create a new database for GoCD.

postgres=# CREATE DATABASE "gocd" ENCODING="UTF8" TEMPLATE="template0";

Create a new database user with a strong password.

postgres=# CREATE ROLE "gocd_database_user" PASSWORD 'gocd_database_password' NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;

Grant the rights to the user to use the database.

postgres=# GRANT ALL PRIVILEGES ON DATABASE "gocd" TO "gocd_database_user";

Give the user superuser privileges. The database user requires superuser privileges only the first time the GoCD server starts. This is required to be done because the pgcrypto and citext extensions need to be created initially. The superuser privilege can be revoked after the first time the GoCD server starts as it will no longer be needed.

postgres-=# ALTER ROLE "gocd_database_user" SUPERUSER;

Exit the Postgres Shell.

postgres=# \q

The final step in configuring PostgreSQL for GoCD is to store the database credentials in the GoCD server configuration directory.

Create the file and open it for editing.

$ sudo nano /etc/go/

Paste the following code in it.


Save the file by pressing Ctrl + X and entering Y when prompted.

Step 4 - Configure GoCD

Before configuring GoCD, we need to start the GoCD server.

Start the GoCD server.

$ sudo systemctl start go-server

Check the status of the server.

$ sudo systemctl status go-server
? go-server.service - go-server
     Loaded: loaded (/etc/systemd/system/go-server.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2022-12-15 08:53:10 UTC; 8s ago
    Process: 8475 ExecStart=/usr/share/go-server/bin/go-server start sysd (code=exited, status=0/SUCCESS)
   Main PID: 8541 (wrapper-linux-x)
      Tasks: 43 (limit: 2237)
     Memory: 566.7M
        CPU: 11.873s
     CGroup: /system.slice/go-server.service
             ??8541 /usr/share/go-server/bin/../wrapper/wrapper-linux-x86-64 /usr/share/go-server/wrapper-config/wrapper.conf wrapper.syslog.ident=go-server wrapper.pidfile=/var/lib/go-server/run/go-server.pi>
             ??8556 /usr/share/go-server/jre/bin/java --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED -Xms512m -Xmx1024m -XX:MaxMetaspaceSize=400m .....

Launch the GoCD dashboard by visiting the URL http://<yourserverIP>:8153/. To access the GoCD dashboard via a secure connection, visit the URL https://<yourserverIP>:8154. Ignore the error showing that the certificates are invalid. It is always important to access the dashboard over a secured connection.

You will get the following page.

GoCD Homepage

Before using it, you should configure GoCD. Head to the Admin >> Server Configuration menu from the top navigation bar.

GoCD Server Configuration Menu

Add the site URL in the fields provided and press the Save button.

GoCD Server URL

Click the Artifacts Management option from the left menu and enter the location of the artifacts directory created earlier. Select the option Allow auto cleanup artifacts to manage the space and set capacity per your requirements. Click the Save button when finished.

GoCD Artifcats Management

However, the auto-delete option does not take a backup of your old artifacts. To manually take a backup and then delete the old artifacts, disable auto delete by unchecking the Allow auto cleanup artifacts option.

Next, we need to configure email options to receive email notifications from GoCD.

GoCD Email Server options

Click the Send Test Email button to check the settings and then click the Save button to finish.

If you want to set job timeout duration, you can do so by visiting the Job Timeout Configuration section.

Restart the GoCD server to apply the changes.

$ sudo systemctl restart go-server

Step 5 - Set up GoCD authentication

By default, GoCD is accessible to anyone, but you can configure authentication using a password file or LDAP. In this tutorial, we will set up password-based authentication.

Install Apache tools so that we can create an encrypted password file using the htpasswd command.

$ sudo apt install apache2-utils

Create a password file using the Bcrypt authentication. The -c flag creates a new file, the -B flag sets the Bcrypt authentication and the goadmin is the username.

$ sudo htpasswd -B -c /etc/go/passwd_auth navjot

Provide the password when prompted.

New password:
Re-type new password:
Adding password for user navjot

You can add multiple users using the same command, but remove the -c flag because the file already exists. Using the -c flag again will overwrite the existing file and replace the existing user with the new one.

$ sudo htpasswd -B /etc/go/passwd_auth gouser1

The next step in authentication is to configure the password location in the GoCD backend. Visit the Admin >> Security >> Authorization Configuration section from the top navigation bar.

Click the Add button and provide any ID. Select Password File Authentication Plugin for GoCD for the plugin ID from the dropdown menu and enter the path of the password file. Next, click the Check Connection button to verify if GoCD can access the file for authentication purposes.

GoCD Authorization Configuration

For the first user, keep the option Allow only known users to login unchecked. Click the Save button to finish.

You will be soon asked to refresh GoCD and will be taken to the login page.

GoCD Login Page

Enter the credentials created earlier and press the Sign in button to proceed. Visit the Admin >> Security >> Users Management section from the top navigation bar.

GoCD Users Management

Check the SYSTEM ADMIN box to mark the user as administrator. Now, go back to the Admin >> Security >> Authorization Configuration section and click the Edit button across the password file listing.

GoCD Password File Edit Option

Check the option Allow only known users to login. From now on, you need to create a new user via the htpasswd file and then import them first from the server page.

Let us create a second user.

$ sudo htpasswd -B /etc/go/passwd_auth gouser1
New password:
Re-type new password:
Adding password for user gouser1

Visit the Admin >> Security >> Users Management section from the top navigation menu and click the Import User button. Enter the username gouser1 to search for the user.

GoCD Import User

Select the user and click the Import button to add the user.

GoCD Users List

Now, you can log in using the second user as well. Repeat the process for more users.

Step 6 - Install Nginx

Ubuntu 22.04 ships with an older version of Nginx. To install the latest version, you need to download the official Nginx repository.

Import Nginx's signing key.

$ curl | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Add the repository for Nginx's stable version.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \ `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list

Update the system repositories.

$ sudo apt update

Install Nginx.

$ sudo apt install nginx

Verify the installation.

$ nginx -v
nginx version: nginx/1.22.1

Start the Nginx server.

$ sudo systemctl start nginx

Step 7 - Install SSL

We need to install Certbot to generate the SSL certificate. You can either install Certbot using Ubuntu's repository or grab the latest version using the Snapd tool. We will be using the Snapd version.

Ubuntu 22.04 comes with Snapd installed by default. Run the following commands to ensure that your version of Snapd is up to date.

$ sudo snap install core
$ sudo snap refresh core

Install Certbot.

$ sudo snap install --classic certbot

Use the following command to ensure that the Certbot command can be run by creating a symbolic link to the /usr/bin directory.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Run the following command to generate an SSL Certificate.

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d

The above command will download a certificate to the /etc/letsencrypt/live/ directory on your server.

Generate a Diffie-Hellman group certificate.

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Do a dry run of the process to check whether the SSL renewal is working fine.

$ sudo certbot renew --dry-run

If you see no errors, you are all set. Your certificate will renew automatically.

Step 8 - Configure Nginx

Open the file /etc/nginx/nginx.conf for editing.

$ sudo nano /etc/nginx/nginx.conf

Add the following line before the line include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Save the file by pressing Ctrl + X and entering Y when prompted.

Create and open the file /etc/nginx/conf.d/gocd.conf for editing.

$ sudo nano /etc/nginx/conf.d/gocd.conf

Paste the following code in it.

server {
  # Redirect any http requests to https
  listen         80;
  listen         [::]:80;
  return 301     https://$host$request_uri;

map $http_upgrade $connection_upgrade {
  default upgrade;
  '' close;

server {
  listen                    443 ssl http2;
  listen                    [::]:443 ssl http2;
  server_name     ;

  access_log                /var/log/nginx/gocd.access.log;
  error_log                 /var/log/nginx/gocd.error.log;

  # TLS configuration
  ssl_certificate           /etc/letsencrypt/live/;
  ssl_certificate_key       /etc/letsencrypt/live/;
  ssl_trusted_certificate   /etc/letsencrypt/live/;
  ssl_protocols             TLSv1.2 TLSv1.3;

  ssl_prefer_server_ciphers on;
  ssl_session_cache         shared:SSL:50m;
  ssl_session_timeout       1d;

  # OCSP Stapling ---
  # fetch OCSP records from URL in ssl_certificate and cache them
  ssl_stapling on;
  ssl_stapling_verify on;
  ssl_dhparam /etc/ssl/certs/dhparam.pem;

  # Proxy everything over to the GoCD server
  location / {
    proxy_set_header        Host            $host;
    proxy_set_header        X-Real-IP       $remote_addr;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header        X-Forwarded-Proto $scheme;
    proxy_http_version      1.1;
    proxy_set_header        Upgrade $http_upgrade;
    proxy_set_header        Connection $connection_upgrade;
    proxy_pass              http://localhost:8153/;

    # To be able to upload artifacts larger than default size of 1mb, ensure that you set this up to a large value.
    # setting to `0` will disable checking for body size.
    # See
    client_max_body_size  10000m;

    # If you are intending to allow downloading of large artifacts (> 1GB) from GoCD you may need to adjust one of the
    # following two proxy buffering settings to prevent downloads failing for slow clients due to server idle timeouts.
    # See
    # 1) disable the buffering of responses entirely (enabled by default on NGINX) OR
    # proxy_buffering off;
    # 2) increase the max temporary file size (setting to `0` will disable the limit)
    # proxy_max_temp_file_size 2048m;

Save the file by pressing Ctrl + X and entering Y when prompted once finished.

Verify the Nginx configuration file syntax.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart the Nginx service.

$ sudo systemctl restart nginx

You can now access the GoCD Dashboard via the URL

Step 9 - Install GoCD Agent

GoCD Agents are the workers responsible for the execution of all the tasks. When a change in the source is detected, the pipeline is triggered and the jobs are assigned to available workers for execution. The agent then executes the task and reports the final status after execution.

To run the pipeline, at least one agent must be configured. Let us install the GoCD agent on the GoCD server.

We have already imported the GoCD repository, therefore, install the GoCD agent directly.

$ sudo apt install go-agent

Start the GoCD agent service.

$ sudo systemctl start go-agent

Visit the Agents tab on your GoCD dashboard and you should see the agent listed and enabled automatically.

GoCD Agents List

You can start using the GoCD CI/CD service from here.


This concludes our tutorial, where you learned how to install and configure GoCD on a Ubuntu 22.04 server. If you have any questions, post them in the comments below.

Share this page:

0 Comment(s)

Add comment

Please register in our forum first to comment.