Your First Concourse CI Deployment

Learn how to deploy Concourse CI step-by-step in a local environment

📚 What You'll Learn: By the end of this tutorial, you'll have a fully functional Concourse CI installation with a web interface and workers ready to run your first pipeline.

Before You Start

This tutorial assumes you have:

Juju 3.x installed and configured
A Juju controller (we'll use localhost/LXD for this tutorial)
Basic command-line familiarity with bash/terminal
~15-20 minutes of time

⚠️ Important: This charm is currently in active development. Always use --channel edge when deploying to get the latest version.

Step 1: Bootstrap Your Juju Controller

If you don't already have a Juju controller, let's create one on your local machine using LXD.

1 Bootstrap a controller named "concourse-tutorial"

juju bootstrap localhost concourse-tutorial

💡 Optional: Faster feedback during tutorial

To speed up the update-status hook interval from 5 minutes to 10 seconds, add --config test-mode=true when creating your model:

juju add-model concourse --config test-mode=true

💡 What just happened? Juju created a controller machine that will manage your deployments. Think of it as the control center for all your applications.

Step 2: Create a Model

Models in Juju are like namespaces for your applications. Let's create one for Concourse CI.

2 Create a model called "concourse"

juju add-model concourse

You should see output confirming the model was created.

Step 3: Deploy PostgreSQL Database

Concourse CI's web server needs a PostgreSQL database to store pipeline configurations and build history.

3 Deploy PostgreSQL 16

juju deploy postgresql --channel 16/stable --base ubuntu@24.04

This will take a few minutes as Juju creates a container and installs PostgreSQL.

💡 Why PostgreSQL 16? The Concourse CI charm currently requires PostgreSQL 16 for full compatibility with Juju secrets API.

Step 4: Deploy Concourse CI

Now for the main event! We'll deploy Concourse CI with 3 units in auto mode.

4 Deploy Concourse CI with 3 units

juju deploy concourse-ci-machine concourse-ci -n 3 \
  --config mode=auto \
  --channel edge \
  --base ubuntu@24.04

What does this do?

-n 3: Creates 3 units (1 web server + 2 workers)
--config mode=auto: Automatically assigns roles (leader = web, others = workers)
--channel edge: Uses the latest development version

Step 5: Connect Database and Concourse CI

Juju makes connecting applications easy with relations.

5 Create the database relation

juju integrate concourse-ci:postgresql postgresql:database

💡 What's a relation? It's Juju's way of connecting applications. The charm automatically handles database credentials, connection strings, and configuration through this relation.

Step 6: Expose the Web Interface

Make the Concourse CI web UI accessible from your network.

6 Expose Concourse CI to the network

juju expose concourse-ci

Step 7: Watch the Deployment

Let's watch everything come online.

7 Monitor the deployment status

juju status --watch 5s

Wait until you see:

postgresql/0: active
concourse-ci/0: active (Web server ready)
concourse-ci/1: active (Worker ready)
concourse-ci/2: active (Worker ready)

Press Ctrl+C to stop watching.

Step 8: Get Your Admin Credentials

Time to log in! First, get the admin password.

8 Retrieve the admin password

juju run concourse-ci/leader get-admin-password

You'll see output like:

username: admin
password: 01JfF@I!9W^0%re!3I!hyy3C

Copy that password - you'll need it in a moment!

Step 9: Access the Web UI

Find the IP address of your web server and open it in a browser.

9 Get the web server IP

juju status concourse-ci/0 --format=json | jq -r '.applications."concourse-ci".units."concourse-ci/0".address'

Open your web browser to:

http://<that-ip-address>:8080

Username: admin
Password: (the password from step 8)

🎉 Success! You should see the Concourse CI dashboard. You now have a fully operational Concourse CI system!

What You've Accomplished

Let's review what you just built:

✅ A Juju controller managing your infrastructure
✅ A PostgreSQL database storing Concourse CI data
✅ A Concourse CI web server with UI and API
✅ Two Concourse CI workers ready to execute tasks
✅ Automatic key distribution (TSA keys configured automatically!)
✅ Secure random admin password

💡 Behind the Scenes: The charm automatically handled TSA key generation, worker registration, and secure communication - no manual key management required!

Next Steps

Now that you have Concourse CI running, here's what to explore next:

Create your first pipeline: Check out the Concourse CI Hello World tutorial
Add GPU workers: Follow our GPU Workers Tutorial to enable ML/AI workloads
Set up shared storage: Learn about Shared Storage for efficient multi-worker deployments
Scale your workers: See How to Scale Workers

Troubleshooting

Web UI won't load

Check:

Is the unit active? Run juju status concourse-ci/0
Can you reach the IP? Try ping <ip-address>
Check logs: juju debug-log --include concourse-ci/0

Units stuck in "waiting" state

Solution: Check the relation is connected:

juju status --relations

You should see concourse-ci:postgresql postgresql:database

Need more help?

Check the Troubleshooting Guide for common issues and solutions.

🎓 Congratulations! You've completed your first Concourse CI deployment. You're ready to start building CI/CD pipelines!