Operating System CentOS

How to Install and Configure Concourse CI on Ubuntu 24.04 LTS with systemd

Set up Concourse CI from the official binary on Ubuntu 24.04: PostgreSQL, a web node, a worker, HTTPS and a first pipeline with fly.

This guide installs Concourse CI from the official release tarball and runs it with systemd: a web node with PostgreSQL on one server, a worker on a second server, HTTPS through the built-in Let's Encrypt support, and the fly command-line tool to run a first pipeline. It follows the systemd installation guide in the Concourse documentation and uses Concourse 8.3.3, the current release.

The target system is Ubuntu 24.04 LTS, not the RHEL family. CentOS 7 reached end of life in June 2024, and the Concourse documentation names Ubuntu 22.04 and 24.04 as the distributions its Linux worker is tested on (minimum tested kernel 5.15). AlmaLinux 9 and Rocky Linux 9 ship kernel 5.14 and are not on that list, and Ubuntu 26.04 LTS is not listed yet either, so Ubuntu 24.04 is the safe choice for a worker today.

Installation routes

The project documents three ways to run Concourse:

  • Docker Compose: the quick start on concourse-ci.org brings up everything in containers on one machine. It is the fastest way to try Concourse.
  • Helm chart: the official chart for Kubernetes clusters.
  • The concourse binary on your own servers, managed by systemd. This is the route described here, and the closest equivalent to the manual installs in older tutorials.

Whichever route you choose, a Concourse installation has the same three parts: a PostgreSQL database, one or more web nodes (web interface, API, pipeline scheduling and the worker registration gateway on port 2222) and one or more worker nodes that run containers.

Requirements

  • Two servers running Ubuntu 24.04 LTS, x86_64 or arm64. The documentation says web and worker should be separate machines. The examples use ci.example.com (203.0.113.10) for the web node and 203.0.113.20 for the worker.
  • A DNS record for ci.example.com pointing to the web node, and port 443 on it reachable from the internet (needed for Let's Encrypt).
  • Port 2222 on the web node reachable from the worker.
  • Root access on both servers. The commands below are run as root; open a root shell with sudo -i.
  • A few gigabytes of RAM for the web node and a large disk on the worker, which stores container images, build volumes and caches.

Install PostgreSQL on the web node

Concourse needs PostgreSQL 11 or newer; the version packaged with Ubuntu 24.04 qualifies. Install it and create a role and the database, which Concourse expects to be named atc. Choose your own password:

apt update
apt install postgresql
sudo -u postgres psql -c "CREATE ROLE concourse LOGIN PASSWORD 'replace-with-db-password'"
sudo -u postgres createdb --owner=concourse atc

Install the concourse binary on both servers

Run this block on the web node and on the worker. It downloads the release for the machine's architecture and unpacks it to /usr/local/concourse:

CONCOURSE_VERSION="8.3.3"
SYSTEM_ARCH="$(case "$(uname -m)" in x86_64) echo amd64;; aarch64|arm64) echo arm64;; *) uname -m;; esac)"
curl -L --output ./concourse.tgz "https://github.com/concourse/concourse/releases/download/v${CONCOURSE_VERSION}/concourse-${CONCOURSE_VERSION}-linux-${SYSTEM_ARCH}.tgz"
tar xzf ./concourse.tgz -C /usr/local/
rm ./concourse.tgz
/usr/local/concourse/bin/concourse --version

Each release also publishes a .sha1 file next to the tarball on the GitHub releases page if you want to verify the download.

Generate the keys

Concourse uses three keys: one to sign user sessions, one that identifies the web node's worker gateway (the TSA), and one that workers use to register. Generate them on the web node:

mkdir -p /usr/local/concourse/keys
cd /usr/local/concourse/keys
/usr/local/concourse/bin/concourse generate-key -t rsa -f ./session_signing_key
/usr/local/concourse/bin/concourse generate-key -t ssh -f ./tsa_host_key
/usr/local/concourse/bin/concourse generate-key -t ssh -f ./worker_key

The web node keeps session_signing_key, tsa_host_key and worker_key.pub. The worker needs tsa_host_key.pub and worker_key. Copy those two to the worker (adjust the user to one that can log in there, then move the files into place as root):

scp tsa_host_key.pub worker_key deploy@203.0.113.20:

Afterwards delete worker_key from the web node; only its public half is needed there.

Configure and start the web node

Create an unprivileged system user for the service:

addgroup --system concourse
adduser --system --ingroup concourse --no-create-home --disabled-password --disabled-login --comment "concourse web user" concourse

Create /usr/local/concourse/web.env. Replace the database password, the admin password and the encryption key (a random string of exactly 16 or 32 characters):

PATH=/usr/local/concourse/bin
CONCOURSE_CLUSTER_NAME=Concourse
CONCOURSE_EXTERNAL_URL=https://ci.example.com
CONCOURSE_ENABLE_LETS_ENCRYPT=true
CONCOURSE_TLS_BIND_PORT=443
CONCOURSE_ENCRYPTION_KEY=replace-with-32-random-characters
CONCOURSE_POSTGRES_HOST=127.0.0.1
CONCOURSE_POSTGRES_USER=concourse
CONCOURSE_POSTGRES_PASSWORD=replace-with-db-password
CONCOURSE_SESSION_SIGNING_KEY=/usr/local/concourse/keys/session_signing_key
CONCOURSE_TSA_HOST_KEY=/usr/local/concourse/keys/tsa_host_key
CONCOURSE_TSA_AUTHORIZED_KEYS=/usr/local/concourse/keys/worker_key.pub
CONCOURSE_MAIN_TEAM_LOCAL_USER=admin
CONCOURSE_ADD_LOCAL_USER=admin:replace-with-admin-password
CONCOURSE_ENABLE_CACHE_STREAMED_VOLUMES=true

The encryption key matters: with Let's Encrypt enabled, Concourse stores the certificate and its private key in the database, and the documentation tells you to enable database encryption for that reason. Keep a copy of the key somewhere safe; without it the encrypted data cannot be read.

Restrict the file and hand the directory to the service user:

chown -R concourse:concourse /usr/local/concourse
chmod 0400 /usr/local/concourse/web.env

Create /etc/systemd/system/concourse-web.service. The AmbientCapabilities line lets the unprivileged user bind port 443:

[Unit]
Description=Concourse Web
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
User=concourse
Group=concourse
EnvironmentFile=/usr/local/concourse/web.env
ExecStart=/usr/local/concourse/bin/concourse web
AmbientCapabilities=CAP_NET_BIND_SERVICE
Restart=on-failure
RestartSec=3
KillSignal=SIGTERM
TimeoutStopSec=60

[Install]
WantedBy=default.target

Start the service and check it:

systemctl daemon-reload
systemctl enable --now concourse-web
systemctl status concourse-web
journalctl -u concourse-web -n 50

If you use a host firewall, allow port 443 from anywhere and port 2222 from the worker only:

ufw allow 443/tcp
ufw allow from 203.0.113.20 to any port 2222 proto tcp

Open https://ci.example.com in a browser. The first request can take a few seconds while the certificate is issued.

Configure and start the worker

On the worker, move the two key files into place and create the work directory. The worker runs as root because it manages containers:

mkdir -p /usr/local/concourse/keys /opt/concourse
mv /home/deploy/tsa_host_key.pub /home/deploy/worker_key /usr/local/concourse/keys/
chown root:root /usr/local/concourse/keys/*
chmod 0600 /usr/local/concourse/keys/worker_key

Create /usr/local/concourse/worker.env. Every worker needs a unique name:

PATH=/usr/local/concourse/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
CONCOURSE_NAME=worker-01
CONCOURSE_WORK_DIR=/opt/concourse
CONCOURSE_TSA_HOST="203.0.113.10:2222"
CONCOURSE_TSA_PUBLIC_KEY=/usr/local/concourse/keys/tsa_host_key.pub
CONCOURSE_TSA_WORKER_PRIVATE_KEY=/usr/local/concourse/keys/worker_key
CONCOURSE_BAGGAGECLAIM_DRIVER=overlay

Create /etc/systemd/system/concourse-worker.service:

[Unit]
Description=Concourse Worker
After=network-online.target
Wants=network-online.target

[Service]
User=root
Group=root
EnvironmentFile=/usr/local/concourse/worker.env
ExecStart=/usr/local/concourse/bin/concourse worker
Restart=on-failure
RestartSec=3
KillSignal=SIGUSR2
SendSIGKILL=yes
TimeoutStopSec=300

[Install]
WantedBy=default.target

Stopping the unit sends SIGUSR2, which retires the worker: it finishes running builds, unregisters and exits. Start it:

systemctl daemon-reload
systemctl enable --now concourse-worker
systemctl status concourse-worker

Since version 8, the worker uses containerd as its default container runtime; nothing extra has to be installed for it.

Install fly and run a first pipeline

fly is the command-line client. Install it on your workstation, either from the download link in the bottom-right corner of the web interface or from the same GitHub release:

curl -L --output fly.tgz "https://github.com/concourse/concourse/releases/download/v8.3.3/fly-8.3.3-linux-amd64.tgz"
tar xzf fly.tgz
sudo install -m 0755 fly /usr/local/bin/fly

Log in with the local user from web.env and confirm that the worker has registered:

fly -t ci login -c https://ci.example.com -u admin -p 'replace-with-admin-password'
fly -t ci workers

Save a minimal pipeline as hello.yml:

jobs:
- name: hello
  plan:
  - task: say-hello
    config:
      platform: linux
      image_resource:
        type: registry-image
        source:
          repository: busybox
      run:
        path: echo
        args: ["Hello from Concourse"]

Upload it, unpause it and trigger the job while watching its output:

fly -t ci set-pipeline -p hello -c hello.yml
fly -t ci unpause-pipeline -p hello
fly -t ci trigger-job -j hello/hello --watch

The worker pulls the image, runs the task in a container and prints the greeting. The same build is visible in the web interface.

Maintenance and troubleshooting

  • Authentication: the local user is a starting point. The Concourse documentation describes authentication providers such as GitHub, OIDC and LDAP; once one is configured, remove the *_LOCAL_USER variables.
  • Upgrading: read the release notes, stop the services, unpack the new tarball over /usr/local/concourse on every node, start the web node first and then the workers. Run fly -t ci sync afterwards so the client matches the server.
  • Containers cannot resolve host names: Ubuntu's resolver listens on a loopback address, which the runtime strips from the container's /etc/resolv.conf. Set a DNS server explicitly by adding CONCOURSE_CONTAINERD_DNS_SERVER with the address of a resolver your network provides to worker.env, then restart the worker.
  • Worker missing from fly workers: check journalctl -u concourse-worker. Typical causes are port 2222 being blocked, or the worker's public key not matching worker_key.pub on the web node.
  • Web node fails with a bind error on port 443: confirm the AmbientCapabilities line is in the unit and that no other web server occupies the port.

Frequently asked questions

Can I run the web node and the worker on one server?

For a trial, yes: the Docker Compose quick start does exactly that. For regular use the documentation recommends separate machines, and says running several workers on one machine makes no sense. Builds compete with the web node and database for memory and disk otherwise.

Can I install Concourse on AlmaLinux 9 or Rocky Linux 9?

The web node is a plain Go binary with no special requirements and can run there. The worker is the sensitive part: it is tested on Ubuntu 22.04 and 24.04 with kernel 5.15 or newer, so on the RHEL 9 family you would be running an untested combination. Put at least the workers on Ubuntu.

How many workers do I need?

Start with one and watch it. The documentation suggests adding workers when the average number of containers per worker approaches about 200, and generally prefers several smaller workers to a few very large ones.

What do the old component names ATC, TSA, Garden and Baggageclaim refer to?

They still exist inside the two processes. ATC (web interface, API, scheduler) and TSA (worker registration over SSH on port 2222) are part of concourse web. The container runtime and Baggageclaim (volume and cache management) are part of concourse worker. You no longer install or start them separately.

Share story:

Continue reading other guides on How VPS.