Skip to content

docs: Sync documentation with current hub and agent #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alex289 merged 11 commits into from
Oct 28, 2026
Merged

docs: Sync documentation with current hub and agent #81

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e477243
docs: Sync documentation with current hub and agent
alex289 Oct 21, 2026
cfafa87
docs: Address review feedback
alex289 Oct 22, 2026
cb2fa23
docs(advanced): add Tailscale guide and fix proxy comment syntax
alex289 Oct 22, 2026
b3dd8ed
Merge branch 'main' into docs/sync-with-code-changes
alex289 Oct 25, 2026
45d1600
docs: Sync with changes up to v0.5.0
alex289 Oct 26, 2026
3fb8af5
docs: Refresh screenshots for the new font and agent setup dialog
alex289 Oct 26, 2026
34e1bac
docs(repositories): Document signed commits
alex289 Oct 26, 2026
ae33ea5
fix: Cleanup
alex289 Oct 26, 2026
2e20e0b
docs: Stop explaining every form field
alex289 Oct 28, 2026
9f7e5d7
docs(env): Shorten environment variable descriptions
alex289 Oct 28, 2026
b8a93b6
chore: Cleanup
alex289 Oct 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 56 additions & 12 deletions content/docs/advanced/architecture/agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,29 +10,36 @@ An **Agent** is a lightweight service that runs on the target host where your Do
Before deploying the Agent, you need to register it in the Hub to obtain an authentication token.

1. Navigate to the **Agents** page in the OrcaCD UI.
2. Click **Add Agent** and give it a name (e.g., `production`, `staging`).
3. Copy the generated `AUTH_TOKEN` (only shown once).
2. Click **Add Agent** and give it a name (e.g., `production`, `staging`) and optionally an icon.
3. The setup dialog shows a `compose.yml` for the Agent that already contains `HUB_URL`, the generated `AUTH_TOKEN` and an Agent image matching the version of the Hub. Copy it with **Copy**, or copy only the token with **Copy agent auth token** in the menu next to it. The token is only shown once.
4. Start the Agent (see below). The dialog waits for the first connection and shows **Connected** as soon as the Agent is online. If the Agent connects but cannot reach Docker, the dialog shows an error instead.

![Create Agent](/assets/docs/create-agent.png?url)

`HUB_URL` in the generated file is the address you used to open the UI. If the Agent reaches the Hub through a different URL, change it before starting the Agent.

## Deploying an Agent

### Same Host as the Hub

The default `docker-compose.yml` includes both Hub and Agent. If you are running both on the same machine, just set the `AUTH_TOKEN` in your `.env` and restart:
The default `docker-compose.yml` includes both Hub and Agent. If you are running both on the same machine, set the `AUTH_TOKEN` in your `agent.env` and recreate the Agent:

```bash
docker compose up -d
docker compose up -d agent
```

### Remote Host

To deploy an Agent on a separate server, copy only the Agent service definition to that machine. See [installation](/docs/setup/installation) for instructions on how to set up the Agent service.
To deploy an Agent on a separate server, save the `compose.yml` from the setup dialog on that machine and start it with `docker compose up -d`. If you prefer to keep the token out of the Compose file, move `HUB_URL` and `AUTH_TOKEN` into an `agent.env` file and reference it with `env_file`, as in the [default compose file](https://github.com/OrcaCD/orca-cd/blob/main/docker-compose.yml).

The Agent will connect to the Hub. Once connected, its status in the Hub UI changes to **Online**.

<Callout>The Agent needs access to the Docker socket to manage containers on the host.</Callout>

### Hub with a Private CA

If the Hub uses a self-signed certificate or a certificate from a private CA, mount the CA certificate into the Agent container and set `CA_CERT_FILE` to its path. The certificates are added to the system CAs. See [environment variables](/docs/configuration/env-variables#agent).

## Multiple Agents

You can register as many agents as you need. For example, one per environment:
Expand All @@ -45,21 +52,58 @@ You can register as many agents as you need. For example, one per environment:

Each Application in OrcaCD is assigned to exactly one Agent. You can split workloads across agents freely.

## How the Agent Deploys

For every application, the Agent creates a directory `<DEPLOYMENTS_DIR>/<project>/` (by default `/deployments/<project>/` inside the Agent container) containing:

- `compose.yaml`: the Compose file from your repository.
- `compose.override.yaml`: generated by OrcaCD to mark the containers as managed by OrcaCD. The file is rewritten on every deployment, so manual changes are overwritten.

The Compose project name is derived from the application name. The Agent does not touch Compose projects that were not created by OrcaCD.

Before deploying, the Agent checks the Compose file against the [deployment policy](/docs/advanced/security#compose-deployment-policy).

## Rotating an Agent Token

If a token is compromised or needs to be rotated, navigate to the Agent in the UI, open the options menu, and select **Rotate Token**. A new token is generated immediately and the old token becomes invalid.
If a token is compromised or needs to be rotated, navigate to the Agent in the UI, open the options menu, and select **Rotate token**. A new token is generated immediately, the old token becomes invalid and a running Agent is disconnected right away.

Update the `AUTH_TOKEN` in the Agent's `.env` and restart it:
Update the `AUTH_TOKEN` in the Agent's `agent.env` (or its Compose file) and recreate the container:

```bash
docker compose up -d
docker compose up -d agent
```

## Deleting an Agent

Deleting an Agent removes it and all of its applications (including their history) from the Hub and disconnects the Agent. This also works while the Agent is offline, e.g. if the host no longer exists.

<Callout type="warn">
Comment thread
alex289 marked this conversation as resolved.
Deleting an Agent does **not** remove the containers of its applications from the host. If the
containers should be removed, delete the applications first while the Agent is still online
(applications can not be deleted while their Agent is offline), or remove them manually on the
host afterwards.
</Callout>

## Agent Status

| Status | Meaning |
| --------- | --------------------------------------------------- |
| `online` | Agent is connected and ready to receive deployments |
| `offline` | Agent has disconnected or has not yet connected |
| Status | Meaning |
| --------- | --------------------------------------------------------------------------------------------- |
| `Online` | Agent is connected and ready to receive deployments |
| `Offline` | Agent has disconnected or has not yet connected |
| `Error` | Agent is connected but cannot reach its Docker daemon. Deployments fail until it is reachable |

If an Agent is offline, deployment dispatch fails immediately and the application is marked out-of-sync with an error. Deployments are not queued or retried automatically. Trigger the deployment again once the Agent is back online.

### Connection

The Hub sends a ping to all Agents every 60 seconds. If the Agent does not hear from the Hub for about 150 seconds, it drops the connection and reconnects. When the Hub restarts, all Agents are marked offline until they reconnect.

When an Agent disconnects, the health of its applications changes to `Unknown`, and deployments that were still running are marked as failed.

Offline [notifications](/docs/advanced/notifications) are only sent after the Agent has been disconnected for 60 seconds, so short reconnects (e.g. Agent restarts or token rotation) do not trigger them.

## Versions

The Agents page shows the Agent and Docker version reported by each Agent. Agents that are older than the Hub are marked as outdated, and Agents older than the minimum version supported by the Hub as unsupported. See [Upgrading](/docs/setup/upgrading) for how to update an Agent.

![Agents page with versions and status](/assets/docs/agents-page.png?url)
125 changes: 81 additions & 44 deletions content/docs/advanced/architecture/applications.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,85 +5,122 @@ description: Creating and managing applications in OrcaCD

An **Application** in OrcaCD represents a Docker Compose deployment. It links a repository (and a specific branch and file path) to an Agent, which runs the actual containers.

## Overview Dashboard
Comment thread
alex289 marked this conversation as resolved.

The **Overview** page shows the status of all applications, recent deployments and agents at a glance and lists the applications that need your attention, e.g. because they are unhealthy or their last deployment failed.

![Overview dashboard](/assets/docs/overview-dashboard.png?url)

## Creating an Application

1. Navigate to the **Applications** page and click **Add Application**.
2. Fill in the required fields:
Navigate to the **Applications** page, click **New Application** and select the Agent, the repository, the branch and the Compose file. The name must be unique per Agent, because the Docker Compose project name is derived from it.

OrcaCD reads the Compose file from the latest commit of the branch and immediately deploys it to the selected Agent.

| Field | Description |
| -------------- | ---------------------------------------------------------------------------------------------- |
| **Name** | Display name for the application |
| **Repository** | The repository containing the Compose file |
| **Branch** | The branch to track (e.g., `main`, `production`) |
| **Path** | Path to the `docker-compose.yml` inside the repository (e.g., `apps/myapp/docker-compose.yml`) |
| **Agent** | The agent that will execute the deployment |
## Application Details

3. Click **Create**.
The details page of an application shows its [status](#application-status), the repository, the deployed commit, the Agent and what triggered the last sync. Below, you can see the current Compose file and a diff to the previous version.

OrcaCD will immediately sync the repository and deploy the Compose file to the selected Agent.
![Application details with the Deploy dropdown](/assets/docs/application-details.png?url)

![Diff of the Compose file](/assets/docs/application-manifest-diff.png?url)

## Application Status

Each application shows two status indicators:

### Sync Status

| Status | Meaning |
| ------------- | ---------------------------------------------------- |
| `Synced` | Deployed commit matches the latest repository commit |
| `Out Of Sync` | A new commit exists that has not been deployed yet |
| `Syncing` | A deployment is currently in progress |
| `Unknown` | No deployment has been triggered yet |
| Status | Meaning |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `Synced` | The last deployment, sync or image update succeeded |
| `Out of Sync` | The last deployment, sync or image update failed or was interrupted (e.g. the Agent disconnected or the Hub restarted during it) |
| `Syncing` | A deployment or image update is currently in progress |
| `Unknown` | No deployment has finished yet |

New commits are not shown as out of sync: as soon as OrcaCD sees a new commit (depending on the [sync strategy](/docs/advanced/architecture/repositories#sync-strategies) of the repository), it deploys it automatically. If an application is `Out of Sync`, check the error on the details page or in the [history](#history) and deploy it again.

### Health Status

| Status | Meaning |
| ----------- | ---------------------------------------------------- |
| `Healthy` | All containers from the Compose file are running |
| `Unhealthy` | One or more containers are stopped or in a bad state |
| `Unknown` | Health has not been checked yet |
The health is reported by the Agent, which watches the Docker events of the application's containers and updates the status in real time.

| Status | Meaning |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `Healthy` | All containers are running and none of them reports a failing Docker healthcheck |
| `Unhealthy` | At least one container is not running (e.g. restarting) or reports a failing Docker healthcheck |
| `Stopped` | All containers are created, exited or paused, e.g. after `docker compose stop` |
| `Unknown` | No containers exist, a healthcheck is still starting, a deployment is running, the Agent is disconnected or cannot reach Docker |

## Triggering a Deployment

OrcaCD automatically deploys when the tracked repository branch receives a new commit (depending on the repository sync strategy). You can also trigger a deployment manually:
OrcaCD automatically deploys when the tracked repository branch receives a new commit that changes the Compose file (depending on the repository sync strategy), and when image polling or the image pull webhook detects a new image. You can also trigger a deployment manually from the details page:

1. Open the application.
2. Click **Deploy** in the top-right corner.
| Action | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Deploy** | Redeploys the current Compose file without syncing the repository |
| **Sync repository** | Available in the dropdown next to **Deploy**. Fetches the latest commit and deploys the changes to all applications of this repository |
| **Pull images** | Available in the dropdown next to **Deploy**. Pulls the latest images and redeploys only if an image changed |

This forces an immediate sync and deployment regardless of the current sync status.
<Callout>
The Agent must be online to deploy. If it is offline, the deployment fails immediately and the
application is marked `Out of Sync` with an error. Deployments are not queued or retried
automatically, so trigger the deployment again once the Agent is back online.
</Callout>

## Application Settings
## History

The **History** page of an application records every deployment, commit sync and image update with its time, trigger, the user who triggered it, the commit, the result (`Running`, `Succeeded`, `Failed` or `No change`) and error details.

You can switch between a table and a timeline view. The search filters the history by type, trigger, result, user, commit hash or message, and error message.

![Application history in the timeline view](/assets/docs/application-history-timeline.png?url)

Open an application and navigate to the **Settings** tab to configure it.
## Application Settings

### General

Change the application name, icon, linked repository, branch, path, or agent.
Change the name, icon, Agent, repository, branch and Compose file of the application, or delete it.

Saving does not deploy the application. If you change the Compose file, the Agent or the name, a notification with a **Deploy** button appears so you can apply the changes right away.

![Deploy prompt after saving changes](/assets/docs/deploy-after-edit-toast.png?url)

When you move the application to another Agent or rename it so that its Compose project name changes, OrcaCD first removes the old containers from the current Agent. Deleting an application also removes its containers and deployment directory from the Agent. Both require the current Agent to be online. Otherwise the request fails with `409 Conflict` and nothing is changed.

![General settings of an application](/assets/docs/application-general-settings.png?url)

#### Delete old images

When enabled, OrcaCD removes the images an application no longer uses after every successful deployment, image update and manual image pull. Images are removed by ID, so this works both for changed tags and for new digests of the same tag. Images that are still used by other containers are kept.

### Image Polling
### Image Updates

Image polling lets OrcaCD automatically pull updated Docker images and restart containers, even when no Compose file has changed. This is useful for continuous delivery workflows where a CI pipeline pushes new image tags.
![Image update settings](/assets/docs/application-image-updates.png?url)

| Setting | Description |
| ------------------------ | ---------------------------------------------------------------------------- |
| **Enable image polling** | Turns image polling on or off |
| **Polling interval** | How often to check for new images (minimum 30 seconds, default 120 seconds) |
| **Delete old images** | When enabled, old images are removed from the host after a successful update |
#### Image Polling

## Image Pull Webhooks
Image polling lets OrcaCD automatically pull updated Docker images and restart containers, even when the Compose file has not changed. This is useful for mutable tags like `latest` or for CI pipelines that push new images under the same tag.

Instead of polling, you can trigger an image pull from your container registry via a webhook. This is ideal for registry-side push notifications.
The polling interval is at least 60 seconds (default: 120 seconds).

1. Open the application settings.
The Agent compares the images of the application with the registry. If any image changed, it pulls the images and redeploys the application.

If the check fails, for example because the Agent has no credentials for a private registry, the application changes to `Out of Sync` and the error is recorded in its history. Repeated failures with the same error are only recorded once. The next successful check sets the application back to `Synced`. See [common issues](/docs/troubleshooting/common-issues#deployment-is-stuck-in-syncing) for registry credentials.

#### Image Pull Webhook

Instead of polling, your container registry can notify OrcaCD via a webhook when a new image is pushed.

1. Open the **Image Updates** settings of the application.
2. In the **Image Pull Webhook** section, click **Generate Webhook**.
3. OrcaCD returns a webhook URL and secret.
4. Register this webhook in your container registry (e.g., Docker Hub, GitHub Container Registry, Harbor).
3. Copy the secret. It is only shown once. The webhook URL is shown afterwards in the settings.
4. Register the webhook in your container registry. See [Webhooks](/docs/configuration/webhooks#container-registries) for the setup of Docker Hub, GitHub Packages, Harbor and generic registries.

When a webhook is received, the Agent pulls all images of the application and redeploys it if any image changed. Deliveries for the same application are combined: the pull starts once no further delivery has arrived for 5 seconds, but at the latest 30 seconds after the first one. This way, one push that triggers several webhooks only results in one deployment.

When the registry sends a push event to the webhook URL, OrcaCD instructs the Agent to pull the latest image and restart the affected container.
Click **Regenerate** to create a new secret or **Revoke** to disable the webhook. The old secret stops working immediately.

<Callout>
The Agent must be online for the image pull webhook to succeed. If the Agent is offline, the event
is not queued.
</Callout>

To revoke a webhook and generate a new one, click **Revoke Webhook** and then **Generate Webhook** again.
Loading
Loading