GoCD Continuous Delivery Server on AWS User Guide

Overview

GoCD is the open source continuous integration and continuous delivery server from Thoughtworks. It models complex build and release workflows as pipelines and renders a value stream map that visualises every change from commit through to deployment. The cloudimg image runs GoCD 26.1 with a co-located build agent, so it is a complete, self contained CI/CD server the moment it boots.

GoCD ships with no authentication out of the box: anyone who can reach it can administer it. This image closes that gap. The file based authentication realm is baked into the GoCD configuration, an admin user is marked as a GoCD administrator, and the per instance admin password is generated and rotated on first boot. The server binds to loopback and is fronted by nginx on port 80.

What is included:

• GoCD server 26.1 from the official download.gocd.org APT repository (Apache License 2.0, Thoughtworks)
• A co-located go-agent that auto registers and is auto enabled, so pipelines run out of the box
• GoCD bound to 127.0.0.1:8153 / :8154, fronted by nginx on :80 with X-Forwarded-* headers
• Secure by default authentication: the file based auth realm (cd.go.authentication.passwordfile) plus an admin GoCD administrator baked into /etc/go/cruise-config.xml
• gocd-firstboot.service generating a strong per instance admin password (bcrypt entry in /etc/go/password.properties) and writing /etc/cloudimg-credentials.txt (mode 0600 root:root) on first boot
• OpenJDK runtime, apache2-utils for the bcrypt password entry, and nginx
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair, and a VPC subnet. The instance security group should allow inbound TCP 22 (SSH) and TCP 80 (web UI) from your trusted CIDR. m5.large (8 GB RAM) suits small teams running a handful of pipelines. GoCD is a JVM application; for busy servers with many concurrent jobs, distributed agents, or large materials, scale up to a larger instance type.

Connecting to your instance

SSH in as the default login user for the operating system variant you launched. This listing currently ships one variant:

ssh ubuntu@<public-ip>

Step 1: Launch from AWS Marketplace

Subscribe to the cloudimg GoCD listing in AWS Marketplace and launch an instance. Pick the m5.large size, choose your VPC and subnet, and attach a security group that allows inbound TCP 22 and TCP 80 from your trusted CIDR.

Step 2: SSH In

ssh ubuntu@<public-ip>

Step 3: Service Status

Confirm the GoCD server, the built in agent, and nginx are all active. GoCD is a JVM service and can take 60 to 90 seconds to finish warming up after a boot.

sudo systemctl is-active go-server go-agent nginx

active
active
active

Step 4: Confirm Secure By Default Authentication

Unlike a stock GoCD install, this image requires a login. An unauthenticated API call is rejected, while the per instance admin credentials authenticate.

PASS=$(sudo grep '^GOCD_ADMIN_PASSWORD=' /etc/cloudimg-credentials.txt | cut -d= -f2-)
echo "unauthenticated: $(curl -s -o /dev/null -w '%{http_code}' -H 'Accept: application/vnd.go.cd.v7+json' http://127.0.0.1/go/api/agents)"
echo "per-VM admin:    $(curl -s -o /dev/null -w '%{http_code}' -H 'Accept: application/vnd.go.cd.v7+json' -u "admin:${PASS}" http://127.0.0.1/go/api/agents)"

The unauthenticated request returns 401; the authenticated request returns 200.

unauthenticated: 401
per-VM admin:    200

Step 5: Read Per-VM Admin Credentials

The first boot service rotates the GoCD admin password and writes the cloudimg credentials file. Read it now.

sudo cat /etc/cloudimg-credentials.txt

Pick up GOCD_URL, GOCD_ADMIN_USER (always admin), and GOCD_ADMIN_PASSWORD. Keep this terminal open while you log in.

Step 6: Sign In to GoCD

Browse to http://<public-ip>/go/ (nginx forwards to GoCD on 127.0.0.1:8153). The GoCD sign in page appears, which is proof the server is not open. Enter admin and the password from /etc/cloudimg-credentials.txt.

Step 7: Create Your First Pipeline

A fresh GoCD server has no pipelines, so it opens the Add a New Pipeline wizard. Point it at a Git repository (the Material), name the pipeline, and define stages and jobs. The built in agent will pick up and run the work.

Step 8: Confirm the Built-In Agent

Open Agents from the top navigation. The co-located gocd-builtin-agent is registered and Enabled, so pipelines can run immediately without adding external agents.

You can confirm the same over the REST API:

PASS=$(sudo grep '^GOCD_ADMIN_PASSWORD=' /etc/cloudimg-credentials.txt | cut -d= -f2-)
curl -s -H 'Accept: application/vnd.go.cd.v7+json' -u "admin:${PASS}" http://127.0.0.1/go/api/agents \
  | python3 -c "import sys,json; a=json.load(sys.stdin)['_embedded']['agents']; print('agents:', len(a)); [print(' -', x['hostname'], x['agent_config_state']) for x in a]"

agents: 1
 - gocd-builtin-agent Enabled

Step 9: Administer Pipelines

The Admin menu is where you manage pipelines, pipeline groups, configuration, plugins, and security. Administration is restricted to the admin user provisioned in the GoCD security configuration.

Step 10: API Round-Trip

Confirm the REST API is reachable with the same credentials from your CI scripts or external triggers.

PASS=$(sudo grep '^GOCD_ADMIN_PASSWORD=' /etc/cloudimg-credentials.txt | cut -d= -f2-)
curl -sf -H 'Accept: application/vnd.go.cd.v7+json' -u "admin:${PASS}" http://127.0.0.1/go/api/agents | head -c 200

A 200 response with a JSON agents payload confirms admin auth via nginx to GoCD is wired correctly. GoCD's versioned API needs an exact Accept header (the agents resource is application/vnd.go.cd.v7+json).

Step 11: Production Hardening Checklist

Before exposing GoCD to the internet, work through these:

1. TLS termination. Add a Let's Encrypt certificate with certbot --nginx and redirect port 80 to 443. Set the GoCD Site URL under Admin, Server Configuration to the https:// form so absolute links are correct.
2. Rotate and add users. The per instance admin password lives in /etc/go/password.properties as a bcrypt entry; add more users with sudo htpasswd -B /etc/go/password.properties <user> and grant roles under Admin, Security.
3. Authorization. Define pipeline group and role based permissions under Admin, Pipelines and Admin, Security, Roles so contributors only see what they need.
4. Add agents. Scale out by installing go-agent on additional hosts pointed at https://<this-server>:8154/go, or use elastic agents. The built in agent is convenient but shares resources with the server.
5. Back up /etc/go and /var/lib/go-server. These hold the configuration, pipeline history, and artifacts; back them up on a schedule.
6. Keep it patched. Unattended upgrades is enabled; run sudo apt-get update && sudo apt-get upgrade to pull GoCD point releases from the official repo.

Architecture

Support

cloudimg provides 24/7 support for this image. Open a ticket at https://www.cloudimg.co.uk/support/ with your instance ID and a brief description of the issue. Common asks: adding distributed or elastic agents, wiring up SSO, configuring pipeline group authorization, and scaling the server for larger workloads.