Christian WellsGoCD is a powerful open-source continuous delivery and automation system that excels at modeling complex CD workflows. It offers fast feedback through its modeling constructs, parallel execution, and dependency management. With GoCD, you can easily troubleshoot and track every change from commit to deployment in real-time. Additionally, GoCD allows you to compare and deploy any version of your application effortlessly. In this tutorial, we will guide you through the process of installing and configuring GoCD on a Ubuntu 22.04 server. Let’s get started!
Prerequisites
Before we dive into the installation and configuration process, let’s ensure that we have all the necessary prerequisites in place:
- A server running Ubuntu 22.04 with a minimum of 2GB of RAM.
- A non-sudo user with root privileges.
- The Uncomplicated Firewall (UFW) enabled and running.
- Fully Qualified Domain Names (FQDN) pointing to your server. For the purpose of this tutorial, we will use
gocd.example.comas our domain.
It’s also crucial to keep your server up to date. Run the following command to update your system:
sudo apt update && sudo apt upgrade
Now that we have our prerequisites ready, let’s proceed with the installation and configuration of GoCD.
Step 1 – Configure Firewall
Before installing any packages, we need to configure the firewall to open the necessary ports. By default, GoCD uses ports 8153, 80 (HTTP), and 443 (HTTPS). Let’s open these ports in the firewall.
To check the status of the firewall, run the following command:
sudo ufw status
You should see the following output:
Status: active To Action From -- ------ ---- OpenSSH ALLOW Anywhere OpenSSH (v6) ALLOW Anywhere (v6)
To open the required ports, execute the following commands:
sudo ufw allow 8153
sudo ufw allow http
sudo ufw allow https
Verify that the ports are now open by running sudo ufw status again:
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)
With the firewall configured, we can proceed to the next step.
Step 2 – Install GoCD
To install GoCD, we first need to import GoCD’s GPG key into the system. Run the following command:
curl https://download.gocd.org/GOCD-GPG-KEY.asc | gpg --dearmor | sudo tee /usr/share/keyrings/gocd.gpg > /dev/null 2>&1
Next, add the GoCD repository to the system by executing the following command:
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 with the command:
sudo apt update
Now we can proceed to install GoCD and the necessary Java Runtime Environment (JRE) by running:
sudo apt install -y go-server
During the installation, the latest compatible version of JRE required to run GoCD will also be installed.
Before we move on, we need to create a directory to store the artifacts. Artifacts can be stored on the same disk as the server or on a dedicated disk or block storage drive. For this tutorial, we will store them on the same disk. Execute the following command to create the directory:
sudo mkdir /opt/artifacts
Ensure that the GoCD server has ownership of the artifact directory by running:
sudo chown -R go:go /opt/artifacts
Congratulations! You have successfully installed GoCD on your Ubuntu 22.04 server. In the next step, we will install and configure PostgreSQL, which is recommended for GoCD in a production environment.
Step 3 – Install and Configure PostgreSQL
By default, GoCD uses the H2 database, which requires no additional configuration. However, for a production environment, it is recommended to use PostgreSQL. Ubuntu 22.04 ships with an older version of PostgreSQL, so we will install PostgreSQL 15 for this tutorial.
To install the repository for PostgreSQL, execute the following command:
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
Next, import the 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
Now we can install PostgreSQL 15 server by running:
sudo apt install -y postgresql postgresql-contrib
Check the status of the PostgreSQL service by executing:
sudo systemctl status postgresql
You should see the following output:
? 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
Now we need to log in to the PostgreSQL shell:
sudo -i -u postgres psql
Inside the PostgreSQL shell, 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 necessary privileges to the user to use the database:
postgres=# GRANT ALL PRIVILEGES ON DATABASE "gocd" TO "gocd_database_user";
Give the user superuser privileges. Note that the superuser privilege is only required the first time the GoCD server starts, as it needs to create the pgcrypto and citext extensions initially. After the first start, the superuser privilege can be revoked:
postgres=# ALTER ROLE "gocd_database_user" SUPERUSER;
Exit the PostgreSQL shell by typing q.
The next 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 into the file:
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, then Y when prompted.
Step 4 – Configure GoCD
Before we proceed with the configuration of GoCD, let’s start the GoCD server:
sudo systemctl start go-server
Check the status of the server:
sudo systemctl status go-server
You should see the following output:
? 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
To access the GoCD dashboard, visit the URL http://<yourserverIP>:8153/. For a secure connection, use https://<yourserverIP>:8154/. Ignore any certificate errors as we will address this later.
You should now see the GoCD dashboard:
Before we proceed with the configuration, let’s add the site URL in the Server Configuration menu. Follow these steps:
- Click on “Admin” in the top navigation bar.
- Select “Server Configuration” from the dropdown menu.
- Enter your site URL in the provided fields.
- Click the “Save” button to apply the changes.
Next, let’s configure the Artifacts Management. Click on “Artifacts Management” in the left menu and enter the location of the artifacts directory we created earlier. You can also set the capacity and enable auto-cleanup of artifacts according to your requirements. Remember to click “Save” when you’re done.
Please note that the auto-delete option does not create a backup of old artifacts. If you want to manually back up and delete old artifacts, disable auto-delete by unchecking the “Allow auto cleanup artifacts” option.
To configure email notifications, click on “Admin” in the top navigation bar, then select “Server Configuration”. Scroll down to the “Email” section and provide the necessary email settings. Click the “Send Test Email” button to verify the configuration, then click “Save” to finish.
If you need to set the job timeout duration, you can do so in the “Job Timeout Configuration” section.
To apply the configuration changes, restart the GoCD server:
sudo systemctl restart go-server
Congratulations! You have successfully configured GoCD. In the next step, we will set up authentication for GoCD using a password file.
Step 5 – Set up GoCD Authentication
By default, GoCD is accessible to anyone, but we can configure password-based authentication to enhance security. In this tutorial, we will set up password-based authentication using Apache tools.
First, install Apache tools to create an encrypted password file:
sudo apt install apache2-utils
Create a password file using Bcrypt authentication. The -c flag is used to create a new file, and the -B flag sets the Bcrypt authentication. Replace goadmin with your desired username:
sudo htpasswd -B -c /etc/go/passwd_auth goadmin
Enter the password when prompted. You can add multiple users by running the same command without the -c flag. Be careful not to overwrite the existing file when adding more users.
Next, we need to configure the password location in the GoCD backend. Follow these steps:
- Click on “Admin” in the top navigation bar.
- Select “Security” from the dropdown menu.
- Click on “Authorization Configuration”.
- Click the “Add” button and provide an ID.
- Select “Password File Authentication Plugin for GoCD” as the plugin ID.
- Enter the path of the password file in the appropriate field.
- Click the “Check Connection” button to verify if GoCD can access the file for authentication purposes.
- Leave the “Allow only known users to login” option unchecked for the first user.
- Click “Save” to finish.
You will be prompted to refresh GoCD, and then you will be taken to the login page. Enter the credentials you created earlier and click “Sign in” to proceed.
To manage user roles, go to “Admin” > “Security” > “Users Management”. Check the “SYSTEM ADMIN” box for users you want to mark as administrators.
Now, go back to “Admin” > “Security” > “Authorization Configuration”. Click the “Edit” button next to the password file listing. Check the “Allow only known users to login” option. From now on, you need to create new users via the password file and then import them from the server page.
To create a new user, use the following command:
sudo htpasswd -B /etc/go/passwd_auth gouser1
Enter the password when prompted.
To import the new user, go to “Admin” > “Security” > “Users Management” and click the “Import User” button. Enter the username you want to search for, select the user, and click “Import”.
Repeat the process for additional users. You can now log in using the newly created users.
Great! We have successfully set up authentication for GoCD. In the next step, we will install and configure Nginx.
Step 6 – Install Nginx
To install the latest version of Nginx, we need to download the official Nginx repository. Follow these steps:
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 by running:
nginx -v
You should see the version number displayed:
nginx version: nginx/1.22.1
Start the Nginx server:
sudo systemctl start nginx
Congratulations! Nginx is now installed and running on your server. In the next step, we will install an SSL certificate to enable secure communication.
Step 7 – Install SSL
To generate an SSL certificate, we will use Certbot. In this tutorial, we will install Certbot using Snapd. Ubuntu 22.04 comes with Snapd pre-installed, so we’ll use that to install Certbot.
Ensure that your version of Snapd is up to date by running the following commands:
sudo snap install core sudo snap refresh core
Install Certbot:
sudo snap install --classic certbot
Create a symbolic link to the /usr/bin directory to ensure the Certbot command can be run:
sudo ln -s /snap/bin/certbot /usr/bin/certbot
Generate an SSL certificate by running the following command:
sudo certbot certonly --nginx --agree-tos --no-eff -email --staple-ocsp --preferred-challenges http -m test@example.com -d gocd.example.com
Replace gocd.example.com with your domain. The certificate will be downloaded to the /etc/letsencrypt/live/gocd.example.com directory on your server.
Next, generate a Diffie-Hellman group certificate:
sudo openssl dhparam-dsaparam -out /etc/ssl/certs/dhparam.pem 4096
To check if the SSL renewal process is working fine, perform a dry run by executing the following command:
sudo certbot renew --dry-run
If you see no errors, your SSL certificate will renew automatically when needed.
Congratulations! You have successfully installed an SSL certificate for your GoCD server. In the next step, we will configure Nginx to use the SSL certificate.
Step 8 – Configure Nginx
To configure Nginx, we need to make some changes to the Nginx configuration file and create a new configuration file for GoCD.
Open the Nginx configuration file 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, then Y when prompted.
Create a new configuration file for GoCD:
sudo nano /etc/nginx/conf.d/gocd.conf
Paste the following code into the file:
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 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 the default size of 1MB, ensure that you set this value to a larger one. # Setting it 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 intend 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 from 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 it to 0 will disable the limit) # proxy_max_temp_file_size 2048m; } }
Save the file by pressing Ctrl + X, then Y when prompted.
To verify the syntax of the Nginx configuration file, run the following command:
sudo nginx -t
If the syntax is correct, you will see the following output:
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 to apply the changes:
sudo systemctl restart nginx
Congratulations! You have successfully configured Nginx to work with GoCD over SSL. Now you can access the GoCD Dashboard securely using the URL https://gocd.example.com.
Step 9 – Install GoCD Agent
GoCD Agents are responsible for executing tasks and jobs assigned by the GoCD server. To run a pipeline, at least one agent must be configured. In this step, we will install the GoCD agent on the same server as the GoCD server.
Since we have already imported the GoCD repository, we can install the GoCD agent directly:
sudo apt install go-agent
Start the GoCD agent service:
sudo systemctl start go-agent
Now, go to the “Agents” tab on your GoCD dashboard, and you should see the agent listed and enabled automatically.
Congratulations! You have successfully installed and configured a GoCD agent. You are now ready to utilize the power of GoCD for your continuous delivery and automation needs.
Conclusion
In this tutorial, we have covered the step-by-step process of installing and configuring GoCD on a Ubuntu 22.04 server. We started by ensuring that all the prerequisites were met, including server requirements and firewall configuration. Then, we installed GoCD and its dependencies, created a directory for artifacts, and configured PostgreSQL as the database backend. We also guided you through the configuration of GoCD, including server settings, email notifications, and job timeout duration.
Additionally, we explored the process of setting up password-based authentication for GoCD, securing the server with Nginx and SSL, and installing a GoCD agent. Now, you have a fully functional GoCD setup that enables you to streamline your continuous delivery and automation workflows.
If you have any questions or need further assistance, please feel free to reach out in the comments below. Shape.host is a leading provider of Cloud VPS services, offering reliable and scalable hosting solutions. Visit Shape.host to learn more about our Cloud VPS offerings and how we can help you achieve your hosting goals.
