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.
Prerequisites
-
A server running Ubuntu 22.04 with a minimum of 2GB of RAM.
-
A non-sudo user with root privileges.
-
The uncomplicated Firewall(UFW) is enabled and running.
-
Fully Qualified Domain Names(FQDN) pointing to your server. We will be using
gocd.example.comfor our tutorial. -
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 https://download.gocd.org/GOCD-GPG-KEY.asc | 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] https://download.gocd.org /" | 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 http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
Import PostgreSQL GPG key.
$ curl https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/apt.postgresql.org.gpg >/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 db.properties file and open it for editing.
$ sudo nano /etc/go/db.properties
Paste the following code in it.
db.driver=org.postgresql.Driver db.url=jdbc:postgresql://localhost:5432/gocd db.user=gocd_database_user db.password=gocd_database_password
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.
Before using it, you should configure GoCD. Head to the Admin >> Server Configuration menu from the top navigation bar.
Add the site URL in the fields provided and press the Save button.
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.
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.
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.
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.
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.
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.
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.
Select the user and click the Import button to add the user.
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 https://nginx.org/keys/nginx_signing.key | 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] \ http://nginx.org/packages/ubuntu `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 gocd.example.com
The above command will download a certificate to the /etc/letsencrypt/live/gocd.example.com 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;
server_name gocd.example.com;
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 gocd.example.com;
access_log /var/log/nginx/gocd.access.log;
error_log /var/log/nginx/gocd.error.log;
# TLS configuration
ssl_certificate /etc/letsencrypt/live/gocd.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/gocd.example.com/privkey.pem;
ssl_trusted_certificate /etc/letsencrypt/live/gocd.example.com/chain.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384';
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 https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size
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 https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering
#
# 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 https://gocd.example.com.
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.
You can start using the GoCD CI/CD service from here.
Conclusion
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.
