Installation

Every command needed to go from a bare Ubuntu server to a running ci-agent. Two paths: online server (sections 1–3) and air-gapped server (section 4). Commands assume Ubuntu 22.04/24.04 x86_64 and a sudo-capable user.

Releases are built automatically from every commit on master: https://github.com/m-hoseinzadeh/ci-agent/releases — the …-x86_64-linux-musl binary is fully static and runs on any x86_64 Linux.

Private repository note: the plain curl -fsSLO …/releases/latest/download/… commands below only work if the repo is public. While it is private, download with a token via the API instead:

TOKEN=ghp_yourtoken
API=https://api.github.com/repos/m-hoseinzadeh/ci-agent/releases/latest
URL=$(curl -fsS -H "Authorization: Bearer $TOKEN" $API \
  | grep -o '"url": *"[^"]*assets/[0-9]*"' | head -1 | grep -o 'https[^"]*')
# pick the asset you need by listing names first:
curl -fsS -H "Authorization: Bearer $TOKEN" $API | grep '"name"'
curl -fsSL -H "Authorization: Bearer $TOKEN" -H "Accept: application/octet-stream" \
  -o ci-agent-x86_64-linux-musl.tar.gz "$URL"

Once installed, the agent updates itself from the Maintenance page — the update check reads the latest version from the public apt repository, so no token is needed.

1. Install requirements

Docker Engine + Compose plugin

# prerequisites + Docker's apt repository
sudo apt-get update
sudo apt-get install -y ca-certificates curl git
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# install
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# enable + verify
sudo systemctl enable --now docker
sudo docker run --rm hello-world
docker compose version

nginx

Current stable nginx from the official nginx.org apt repository (the distro package lags behind), following nginx.org/en/linux_packages.html:

# prerequisites
sudo apt-get install -y curl gnupg2 ca-certificates lsb-release ubuntu-keyring

# import the nginx signing key
curl -fsSL https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
  | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg > /dev/null

# verify the key — the output must contain the fingerprint
# 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
gpg --dry-run --quiet --no-keyring --import --import-options import-show \
  /usr/share/keyrings/nginx-archive-keyring.gpg

# add the stable repository and pin it above the distro package
echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
https://nginx.org/packages/ubuntu $(lsb_release -cs) nginx" \
  | sudo tee /etc/apt/sources.list.d/nginx.list
printf "Package: *\nPin: origin nginx.org\nPin: release o=nginx\nPin-Priority: 900\n" \
  | sudo tee /etc/apt/preferences.d/99nginx

# install
sudo apt-get update
sudo apt-get install -y nginx
sudo systemctl enable --now nginx
nginx -v

nginx.org packages load sites from /etc/nginx/conf.d/*.conf and have no sites-available/sites-enabled. All commands the agent generates (setup wizard, per-project nginx guide) write to conf.d, which Ubuntu’s distro package also includes — both layouts work.

Verify everything

docker --version && docker compose version && nginx -v && git --version && curl --version | head -1

2. Install CI Agent

Every master commit is published as a signed package to the public apt repository (binaries only — the source stays private):

# trust the signing key + add the repository (one time)
sudo curl -fsSL https://m-hoseinzadeh.github.io/ci-agent-apt/ci-agent.gpg \
  -o /usr/share/keyrings/ci-agent.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/ci-agent.gpg] https://m-hoseinzadeh.github.io/ci-agent-apt ./" \
  | sudo tee /etc/apt/sources.list.d/ci-agent.list

# install — creates the ci-agent user, installs the systemd unit and
# /etc/ci-agent/config.toml (kept as a conffile across upgrades)
sudo apt-get update
sudo apt-get install -y ci-agent
sudo systemctl start ci-agent
systemctl status ci-agent --no-pager

Signing key fingerprint: A80F7309CF26133DBE88E2EC9C5489AAE86BF159.

Option B — manual tarball

# download the latest release (binary + systemd unit + example config)
curl -fsSLO https://github.com/m-hoseinzadeh/ci-agent/releases/latest/download/ci-agent-x86_64-linux-musl.tar.gz
tar xzf ci-agent-x86_64-linux-musl.tar.gz

# binary
sudo install -m 0755 ci-agent/ci-agent /usr/bin/ci-agent
ci-agent --help

# dedicated user (in the docker group) + directories
sudo useradd -r -s /usr/sbin/nologin -G docker ci-agent
sudo mkdir -p /etc/ci-agent /var/lib/ci-agent

# configuration (defaults are sane; see /docs/configuration)
sudo cp ci-agent/deploy/config.example.toml /etc/ci-agent/config.toml
sudo chown -R ci-agent: /var/lib/ci-agent /etc/ci-agent

# systemd service
sudo cp ci-agent/deploy/ci-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ci-agent
systemctl status ci-agent --no-pager

3. First-run setup

The packaged config listens on 0.0.0.0:8044 so the setup wizard is reachable at http://<server-ip>:8044 right after install (the built-in default without a config file stays 127.0.0.1:8044). The wizard enforces, in order:

  1. Name your server (optional) — give this install a name and, if you like, a logo (PNG / SVG / JPEG / WebP / GIF / ICO, up to 512 KB). They brand the panel — sidebar, browser tab title and favicon. Leave both blank to use the default; you can change them later on the Settings page. Click Continue.
  2. Set the admin password — do this immediately; until you do, anyone who can reach the port can claim the instance.
  3. Bind a domain for the admin panel — a LAN DNS name or /etc/hosts entry (e.g. ci.example.internal) works on air-gapped networks.
  4. Install the generated nginx site — copy-paste commands. The wizard shows them; it never runs them for you.
  5. Open http://<your-domain>/ — when the first request arrives through nginx (Host matches, peer is loopback, X-Forwarded-For present), the agent rewrites listen to 127.0.0.1:8044 in its config and restarts. From then on the panel is unreachable from outside the server except through nginx; the rest of the UI stays locked until this completes. If the automatic rewrite fails, the wizard shows a Lock to 127.0.0.1 and restart button (and a sed command you can run instead). If CI_AGENT_LISTEN is set in the service environment, the wizard can’t rewrite listen — remove that variable first.
  6. Set up two-factor authentication (2FA) — on your first login the panel shows a QR code. Scan it with an authenticator app (e.g. Google Authenticator) and enter the 6-digit code to finish. Save the 10 backup codes it shows — each one logs you in once if you lose your phone. 2FA is required; the panel stays locked until you enroll.

Note: the QR code is drawn by the agent itself, so 2FA setup works fully offline. You can enrol extra devices later from Settings, and a code from any of them signs you in. Lost your phone with no backup codes left? Run ci-agent reset-2fa on the server and log in to enroll again. See Security.

Once the password is set, the domain steps (3–5) offer a Skip for now link: you can use the panel by IP and port right away, and the wizard returns as a security reminder at each login until the lockdown completes (or you remove the domain for good).

Prefer to never expose the port, even briefly? Set listen = "127.0.0.1:8044" before the first start and run the wizard through an SSH tunnel:

ssh -L 8044:127.0.0.1:8044 you@your-server

The nginx step still applies — verification happens via a local request through the proxy.

The env-encryption key is generated at /etc/ci-agent/secret.key on first start; back it up together with the database (Maintenance page).

For TLS, extend the generated server block — config in Security.

4. Air-gapped server

Do section 1’s downloads on a connected machine with the same Ubuntu release, transfer, install offline.

Docker + nginx as .deb files (connected machine)

mkdir debs && cd debs

# resolve and download the full dependency closure
sudo apt-get update
apt-get download $(apt-cache depends --recurse --no-recommends --no-suggests \
  --no-conflicts --no-breaks --no-replaces --no-enhances \
  docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin nginx git curl \
  tmux openssh-server openssh-client \
  | grep "^\w" | sort -u)

cd .. && tar czf debs.tar.gz debs
scp debs.tar.gz you@airgapped-server:

(Requires the Docker and nginx.org apt repositories configured on the connected machine — see section 1; the pin in 99nginx makes the closure resolve to nginx.org’s nginx.)

tmux and openssh-server/openssh-client are optional. The package recommends them for the server shell’s Open host SSH session button. Leave them out if you don’t need that button.

CI Agent package (connected machine)

Pick one of the two options.

Option 1 — the signed offline bundle (easiest). Every release publishes ci-agent-offline-<version>.tar.gz on the public ci-agent-apt releases page. It holds the .deb, its signature, the release public key and an install.sh that checks the signature before installing.

URL=$(curl -fsSL https://api.github.com/repos/m-hoseinzadeh/ci-agent-apt/releases/latest \
  | grep -o 'https://[^"]*/ci-agent-offline-[^"]*\.tar\.gz' | head -n1)
curl -fsSLO "$URL"
scp ci-agent-offline-*.tar.gz you@airgapped-server:

Option 2 — the newest .deb from the apt repository, plus its signature. The repository keeps several versions, so the command below sorts them and takes the newest one. Then it checks the signature with the repository key.

REPO=https://m-hoseinzadeh.github.io/ci-agent-apt
FILE=$(curl -fsSL "$REPO/Packages" \
  | awk '/^Version:/{v=$2} /^Filename:/{print v, $2}' | sort -V | tail -n1 | cut -d' ' -f2)
curl -fsSLO "$REPO/$FILE"
curl -fsSLO "$REPO/$FILE.asc"
curl -fsSL "$REPO/ci-agent.gpg" -o ci-agent.gpg

# must print: Good signature from "ci-agent apt repository ..."
# and the key A80F7309CF26133DBE88E2EC9C5489AAE86BF159
gpgv --keyring ./ci-agent.gpg "$(basename "$FILE").asc" "$(basename "$FILE")"

scp ci-agent_*.deb ci-agent_*.deb.asc you@airgapped-server:

What this means. The signature proves the package was built by the ci-agent release pipeline and was not changed on the way. If gpgv does not say Good signature, do not install the file.

Base images your projects need (connected machine)

docker pull nginx:1.31            # whatever your compose files use
docker save nginx:1.31 -o images.tar
scp images.tar you@airgapped-server:

On the air-gapped server

# packages
tar xzf debs.tar.gz && cd debs && sudo dpkg -i *.deb; cd ..
sudo systemctl enable --now docker nginx

# base images
sudo docker load -i images.tar

# ci-agent — Option 1 (offline bundle). Unpack it in its OWN empty
# directory, never directly inside a shared folder like /tmp:
mkdir ci-agent-offline
tar -C ci-agent-offline -xzf ci-agent-offline-*.tar.gz
cd ci-agent-offline && sudo ./install.sh && cd ..

# ci-agent — Option 2 (.deb you already verified):
sudo dpkg -i ci-agent_*.deb

sudo systemctl start ci-agent

install.sh stops with signature verification FAILED and installs nothing if the .deb does not match its signature, or if the signature is not from the ci-agent release key A80F7309CF26133DBE88E2EC9C5489AAE86BF159. That key is written into the script itself, so a bundle that brings some other key is refused. On success it prints Signature OK (ci-agent release key A80F7309CF26133DBE88E2EC9C5489AAE86BF159).

The check runs from the script inside the bundle, so it can’t protect you from a bundle whose install.sh was also changed. If you got the bundle from anywhere other than the official releases page, compare its SHA-256 with the one listed there before you run it.

The default pull_policy = "never" means deployments never try to reach a registry — they use exactly the images you loaded.

5. Upgrading CI Agent

apt installs:

sudo apt-get update && sudo apt-get install --only-upgrade ci-agent

Manual installs:

curl -fsSLO https://github.com/m-hoseinzadeh/ci-agent/releases/latest/download/ci-agent-x86_64-linux-musl
sudo install -m 0755 ci-agent-x86_64-linux-musl /usr/bin/ci-agent
sudo systemctl restart ci-agent

Air-gapped: fetch the new bundle or .deb on the connected machine (see section 4), scp, then run install.sh or sudo dpkg -i. All state survives upgrades (/etc/ci-agent/config.toml is a conffile).

Updating from the panel

The Maintenance page shows the running release and can update the agent for you. This works for every install type (apt, tarball or .deb):

  1. Connected server: click Check for updates, then Update now next to CI Agent — or click Download & stage latest. The agent downloads the newest signed .deb from the public apt repository.
  2. Air-gapped server: under CI Agent update, upload the whole ci-agent-offline-*.tar.gz bundle, or the .deb and its .asc signature separately. Click Verify & stage update.
  3. Either way the signature is checked offline against the release key built into the agent, and older versions are refused. When the update is staged, click Apply & restart.
  4. The service restarts on the new version. If the new version fails to start 3 times in a row, the agent automatically goes back to the previous one.

Self-update needs one line in the service unit. Applying a staged binary is done by a root pre-start step, ExecStartPre=+-/usr/bin/ci-agent apply-staged-update, in ci-agent.service. Packages built before this shipped don’t have it, and the self-update only ever swaps the binary — it never rewrites the unit file — so an already-deployed box keeps the old unit even after updating. If “Apply & restart” leaves you on the old version (check System & versions on the Maintenance page), add the step once with a drop-in:

sudo mkdir -p /etc/systemd/system/ci-agent.service.d
printf '[Service]\nExecStartPre=+-/usr/bin/ci-agent apply-staged-update\n' \
  | sudo tee /etc/systemd/system/ci-agent.service.d/self-update.conf
sudo systemctl daemon-reload
# apply the binary already staged by the failed attempt, then restart:
sudo /usr/bin/ci-agent apply-staged-update
sudo systemctl restart ci-agent

Confirm with systemctl cat ci-agent | grep ExecStartPre. The drop-in lives outside the packaged unit, so it survives both self-updates and later dpkg upgrades. Fresh installs already include the step and need none of this.

systemctl cat ci-agent also shows a second drop-in, /etc/systemd/system/ci-agent.service.d/10-ci-agent.conf, marked “Managed by ci-agent — DO NOT EDIT”. The pre-start step writes it on every start, so service settings added in newer releases also reach boxes that were updated from the panel. Leave it alone.

Common problems and fixes

Problem Fix
“Apply & restart” leaves you on the old version Add the ExecStartPre drop-in shown above.
install.sh says signature verification FAILED The download is damaged or not an official release. Download the bundle again.
gpgv does not print Good signature Don’t install that .deb. Download the .deb, .asc and ci-agent.gpg again.
The Maintenance page says the apt repository is unreachable Normal on an air-gapped server. Upload the offline bundle instead.

6. Building from source (alternative)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env
git clone https://github.com/m-hoseinzadeh/ci-agent.git && cd ci-agent
cargo build --release
sudo install -m 0755 target/release/ci-agent /usr/bin/ci-agent