PipeCD on Ubuntu 24.04 on Azure User Guide

Overview

This image runs PipeCD 0.57.0, the open source GitOps continuous delivery platform, on Ubuntu 24.04 LTS. PipeCD brings a single GitOps workflow to Kubernetes, Terraform, Amazon ECS, AWS Lambda, Google Cloud Run and more: you declare the desired state of your applications in Git and PipeCD progressively rolls it out, with automated analysis, canary and blue/green strategies, automatic rollback on failure, and one web console that shows every deployment, its live state and its full history.

PipeCD has two parts. The Control Plane provides the web console, the deployment history, the audit trail and project and role management. Lightweight agents called piped run next to your workloads, pull the desired state from Git and carry out the deployments. This image runs the complete Control Plane and a ready registered piped agent on a single VM, as a systemd managed Docker Compose stack.

The Control Plane is six containers behind an Envoy gateway that serves the web console, the agent gRPC channel and the API on a single port, 8080: a PipeCD server, a PipeCD ops process (schema migrations and background workers), a MySQL datastore, a MinIO object store and a Redis cache. A piped agent is generated and registered against the local control plane on first boot, so it shows online in the console straight away.

What is included:

• PipeCD 0.57.0 control plane (official ghcr.io/pipe-cd/pipecd server + ops images, pinned), run by systemd
• A piped agent (ghcr.io/pipe-cd/piped:v0.57.0) generated and registered on first boot and shown online in the console
• The web console, the agent gRPC channel and the pipectl API multiplexed onto port 8080 by an Envoy gateway
• A local MySQL datastore, a local MinIO object store and a Redis cache, all bound to the internal container network only
• A per-VM administrator password, database password, object store keys, control plane encryption key and agent key generated on first boot; the administrator password recorded in a root only file
• docker.service and pipecd.service as systemd units, enabled and active
• Local password authentication with no baked-in administrator account
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point; size up for heavier use. NSG inbound: allow 22/tcp from your management network and 8080/tcp for the web console, the agent channel and the API. PipeCD serves plain HTTP on port 8080; for production, front it with your own domain and TLS (see the final steps).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for PipeCD by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and 8080. Then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name pipecd \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name pipecd --port 8080 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

The control plane and the piped agent run as a Docker Compose stack managed by the pipecd systemd service. Confirm both systemd units are active, that all seven containers are up, and that the Envoy gateway is listening on port 8080:

systemctl is-active docker pipecd
sudo docker ps --format 'table {{.Names}}\t{{.Status}}'
sudo ss -tlnp | grep :8080 | awk '{print $1, $4}'

Expected output:

active
active
NAMES                     STATUS
pipecd-pipecd-piped-1     Up 4 minutes
pipecd-pipecd-gateway-1   Up 4 minutes
pipecd-pipecd-ops-1       Up 4 minutes
pipecd-pipecd-server-1    Up 4 minutes
pipecd-pipecd-cache-1     Up 4 minutes
pipecd-pipecd-minio-1     Up 4 minutes
pipecd-pipecd-mysql-1     Up 4 minutes (healthy)
LISTEN 0.0.0.0:8080
LISTEN [::]:8080

Step 5 - Retrieve your per-VM credentials

On the first boot of every VM, pipecd-firstboot.service generates a unique administrator password, database password, object store keys, control plane encryption key and agent key, brings the control plane up on a fresh datastore, registers a piped agent, and writes the console URL, project, administrator username and password into a root-only file. Read it with:

sudo cat /root/pipecd-credentials.txt

There is no default or shared credential in the image: the console uses local password authentication with no administrator baked in, and every secret is unique to this VM. Store the administrator password somewhere safe.

Step 6 - Confirm the console health and the piped agent

The web console answers on port 8080, and the piped agent registered on first boot reports back to the control plane. Confirm the console returns 200 and that the piped agent is ONLINE:

curl -s -o /dev/null -w 'console: %{http_code}\n' http://127.0.0.1:8080/
PID=$(sudo grep '^PIPECD_PIPED_ID=' /root/pipecd-credentials.txt | cut -d= -f2)
sudo /usr/local/sbin/pipecd-webapi.py piped-status --id "$PID"

Expected output:

console: 200
ONLINE

The pipecd-webapi.py helper logs in to the control plane as the per-VM administrator and asks it for the piped's status; ONLINE means the agent has connected to the control plane and reported its version, which is the end to end proof that the GitOps control plane and its agent are wired together.

Step 7 - Sign in to the web console

Browse to http://<vm-public-ip>:8080/. Enter your Project Name (cloudimg on this image) and continue, then sign in with the administrator Username (admin) and the password from /root/pipecd-credentials.txt.

Step 8 - The applications console

After signing in you land on the Applications page. This is where you register the applications PipeCD deploys, bound to a piped agent and a Git repository. It is empty on a fresh image - the next steps connect your repositories.

Step 9 - Confirm the piped agent is online

Open Settings then Piped. The cloudimg-piped agent registered on first boot is listed with a green online indicator, its ID, version and start time - the agent is already connected to the control plane and ready to run deployments once you point it at your repositories.

Step 10 - Review the deployments view

Open Deployments to see the pipeline of every rollout PipeCD runs, with its stages, live state and history. It is empty until you register applications, but this is the single console where you watch and, where configured, approve deployments across every platform.

Step 11 - Point the piped agent at your repositories

The image ships a fully functional control plane and a connected agent; to start deploying, tell the piped agent which Git repositories and platform providers to use. Edit the agent configuration on the VM and restart the stack:

sudo nano /opt/pipecd/piped/piped-config.yaml

Add your repositories (the Git repositories that hold your application manifests) and platformProviders (for example a Kubernetes cluster, a Terraform working directory or an ECS/Lambda/Cloud Run target), following the PipeCD piped configuration reference. Then apply the change:

cd /opt/pipecd && sudo docker compose up -d pipecd-piped

Register applications from the Applications page in the console, choosing the repository and platform provider you configured, and PipeCD will begin syncing the desired state from Git.

Step 12 - Production hardening

• TLS and DNS: front PipeCD with your own domain and a TLS-terminating reverse proxy or Azure Application Gateway pointed at port 8080. Add your public address to the control plane configuration at /opt/pipecd/pipecd-config/control-plane-config.yaml (spec.address) and cd /opt/pipecd && sudo docker compose up -d to apply.
• Single sign-on: PipeCD supports GitHub and generic OIDC single sign-on in addition to the local administrator. Configure a shared SSO provider in the control plane configuration and manage RBAC roles per project from Settings.
• Additional agents: register more piped agents from Settings then Piped to reach clusters and accounts in other networks; each agent dials the control plane over the same gateway.

Maintenance

• Back up your data: all control plane state lives in the local MySQL datastore and MinIO object store, captured in the pipecd_mysql-data and pipecd_minio-data Docker volumes. Snapshot the OS disk for a full backup, or use docker exec with mysqldump for logical database backups.
• Console URL: the console is served on port 8080 and works over the VM's public IP out of the box. For a stable hostname or HTTPS, front it with your own DNS and TLS as above.
• Security updates: unattended security upgrades are enabled, so the OS keeps itself patched. Reboot when a new kernel is installed; the stack restarts automatically.
• Upgrades: the PipeCD images are pinned for reproducibility. To upgrade, change the image tags in /opt/pipecd/.env and cd /opt/pipecd && sudo docker compose up -d.

Support

cloudimg provides 24/7/365 expert technical support for this image. Contact support@cloudimg.co.uk. PipeCD is licensed under the Apache License 2.0. This image is provided by cloudimg; additional charges apply for build, maintenance and 24/7 support.