Installation

Crow CI consists of three components:

Component	Required	Description
Server	Yes	UI, API, webhook handling, pipeline parsing
Agent	Yes	Executes pipelines via Docker, Kubernetes, or local backend
Autoscaler	No	Spins up/down cloud VMs for pending builds

Installation Methods

Method	Best For
Docker Compose	Single-server deployments
Helm Chart	Kubernetes clusters
Binary	Custom deployments
Ansible	Automated provisioning

Database

Crow uses SQLite by default. For production, PostgreSQL or MariaDB is recommended.¹

Note

Database deployment is not covered here. Use existing guides or managed cloud services. You can start with SQLite and migrate later.

Container Images

Images are published to the Codeberg Container Registry:

• crow-server
• crow-agent
• crow-cli
• crow-autoscaler

Image Tags

The unsuffixed and -alpine tags differ depending on the component:

• crow-server and crow-agent are published as Alpine-based images. The unsuffixed tag and the -alpine tag point to the same image — -alpine is kept as an alias for backwards compatibility.
• crow-cli is published in two flavours: the unsuffixed tag is a minimal scratch image, and the -alpine tag is the Alpine variant.

Tag	Description
vX.Y.Z	SemVer release (server/agent: Alpine; cli: scratch)
vX.Y.Z-alpine	SemVer release (Alpine, rootless; alias of vX.Y.Z for server/agent)
vX, vX.Y	Rolling major/minor version
vX-alpine, vX.Y-alpine	Rolling major/minor version (Alpine variant)
dev	Latest from main branch
dev-alpine	Latest from main branch (Alpine variant)

-alpine tag deprecation for server and agent

The -alpine suffix tags for crow-server and crow-agent are deprecated and will be removed in a future release. The unsuffixed and -alpine tags currently point to the same Alpine-based image, so the suffix is now redundant.

If you currently pull crow-server:<tag>-alpine or crow-agent:<tag>-alpine, switch to crow-server:<tag> / crow-agent:<tag> — same image, fewer keystrokes. The server and agent print a matching warning at startup as a reminder.

This deprecation does not apply to crow-cli, where -alpine continues to denote a different image (Alpine) than the default (scratch).

Note

No latest tag exists to prevent accidental major version upgrades.

Agent Authentication

Agents authenticate with the server using tokens via CROW_AGENT_SECRET.

System Token

Set the same CROW_AGENT_SECRET on both server and agent. On first connection:

1. Agent connects with system token
2. Server registers agent and returns unique ID
3. Agent stores ID in CROW_AGENT_CONFIG_FILE
4. Subsequent connections use stored ID

Tip

Persist CROW_AGENT_CONFIG_FILE to prevent duplicate agent registrations on container restarts.

Agent Token

For multiple agents with different configurations, create tokens via Settings → Agents → Add agent or the API. Each agent uses its assigned token in CROW_AGENT_SECRET.

Agent creation

Remote Agents

Agents can run on separate machines from the server.

Internal Network

Connect using private IP addresses:

CROW_SERVER: <private-ip>:8000
CROW_GRPC_ADDR: <private-ip>:9000
CROW_AGENT_SECRET: <token>

Public Network

Requires TLS for secure GRPC connection:

CROW_SERVER: crow.mydomain.com
CROW_GRPC_ADDR: grpc.crow.mydomain.com
CROW_GRPC_SECURE: "true"
CROW_AGENT_SECRET: <token>

Requirements:

• Subdomain for GRPC service
• Valid SSL certificate
• TLS-terminating proxy

Caution

Do not prefix CROW_SERVER with https://.

See Reverse Proxy Setup for ingress configuration examples.

Footnotes

1. Pipeline logs are stored in the database. External log storage is planned. ↩