OrcaCD · timokoessler · Jul 18, 2026 · Jul 18, 2026 · Jul 18, 2026
diff --git a/content/docs/architecture/agents.mdx → ...ent/docs/advanced/architecture/agents.mdx b/content/docs/architecture/agents.mdx → ...ent/docs/advanced/architecture/agents.mdx
diff --git a/content/docs/architecture/applications.mdx → ...cs/advanced/architecture/applications.mdx b/content/docs/architecture/applications.mdx → ...cs/advanced/architecture/applications.mdx
diff --git a/content/docs/architecture/meta.json → content/docs/advanced/architecture/meta.json b/content/docs/architecture/meta.json → content/docs/advanced/architecture/meta.json
diff --git a/content/docs/architecture/notifications.mdx → ...s/advanced/architecture/notifications.mdx b/content/docs/architecture/notifications.mdx → ...s/advanced/architecture/notifications.mdx
diff --git a/content/docs/architecture/overview.mdx → ...t/docs/advanced/architecture/overview.mdx b/content/docs/architecture/overview.mdx → ...t/docs/advanced/architecture/overview.mdx
diff --git a/content/docs/architecture/repositories.mdx → ...cs/advanced/architecture/repositories.mdx b/content/docs/architecture/repositories.mdx → ...cs/advanced/architecture/repositories.mdx
diff --git a/content/docs/advanced/cli.mdx b/content/docs/advanced/cli.mdx
@@ -3,20 +3,22 @@ title: CLI Reference
 description: Hub command-line interface for backup, restore, and key management
 ---
 
+## Hub
+
 The Hub binary includes a CLI for administrative tasks that cannot be performed through the web UI. Run any command with `--help` to see all available options.
 
-When using Docker, prefix commands with `docker compose exec hub /app/hub`:
+When using Docker, prefix commands with:
 
 ```bash
 docker compose exec hub /app/hub <command>
 ```
 
 <Callout>
-	Most commands do not require an interactive terminal. For commands that require confirmation the
-	`--yes`/`-y` can be used
+	Most commands do not require an interactive terminal. For commands that require confirmation
+	`--yes`/`-y` can be used as CLI flag to confirm dangerous operations.
 </Callout>
 
-## export
+### export
 
 Creates a consistent backup of the Hub database. The export uses SQLite's `VACUUM INTO` and is safe to run while the Hub is running.
 
@@ -28,7 +30,7 @@ hub export [--output <path>]
 | ---------------- | ------------------------------- | ------------------------------- |
 | `-o`, `--output` | `hub-export-YYYYMMDD-HHMMSS.db` | Output path for the backup file |
 
-**With Docker:**
+**Usage with Docker:**
 
 ```bash
 docker compose exec hub /app/hub export
@@ -40,7 +42,7 @@ The file is created inside the container under `/app/data/`. Copy it out of the
 docker compose cp hub:/app/data/hub-export-*.db ./backups/
 ```
 
-## import
+### import
 
 Restores a database from a backup file. The existing database is copied to a rollback file before the restore, so you can recover if something goes wrong.
 
@@ -58,7 +60,7 @@ hub import <file> [--yes]
 | `<file>`        | Path to the backup `.db` file |
 | `-y`, `--yes`   | Skip the confirmation prompt  |
 
-**With Docker:**
+**Usage with Docker:**
 
 ```bash
 # Copy the backup into the container
@@ -74,7 +76,7 @@ docker compose run --rm hub /app/hub import data/hub-export-20240101-120000.db
 docker compose up -d hub
 ```
 
-## key rotate
+### key rotate
 
 Re-encrypts all sensitive database fields with a new `APP_SECRET`. Use this when you need to rotate your encryption key.
 
@@ -92,7 +94,7 @@ hub key rotate [--old-secret <secret>] [--yes]
 | `--old-secret` | Previous `APP_SECRET` value. Can also be set via the `OLD_APP_SECRET` env var |
 | `-y`, `--yes`  | Skip the confirmation prompt                                                  |
 
-**With Docker:**
+**Usage with Docker:**
 
 ```bash
 # 1. Create a backup
@@ -110,12 +112,16 @@ docker compose run --rm \
 docker compose up -d hub
 ```
 
-After a successful rotation, all agent tokens and user sessions signed with the old secret are invalidated. Users need to log in again and agents need their tokens re-issued (or simply reconnect. The agent will re-authenticate automatically if the hub is reachable).
+After a successful rotation, all agent tokens and user sessions signed with the old secret are invalidated. Users need to log in again and agents need their tokens re-issued).
 
-## reset-password
+### reset-password
 
 Resets a user's password and forces them to change it on the next login. See [Account Recovery](/docs/troubleshooting/account-recovery) for full details.
 
 ```bash
 hub reset-password <user-id-or-email>
 ```
+
+## Agent
+
+The Agent CLI does not currently provide any helpful commands for end users.
diff --git a/content/docs/brand.mdx b/content/docs/brand.mdx
@@ -18,7 +18,7 @@ OrcaCD in blog posts, talks, integrations, or third-party tooling.
 The OrcaCD logo is an orca mark on a rounded, colored tile. It is available as a scalable SVG and as
 pre-rendered PNGs in several fixed sizes for places that don't support SVG (favicons, app manifests, etc.).
 
-![Logo](/assets/logo-dark-256.png?url)
+<img src="/assets/logo-dark.svg" alt="OrcaCD logo" className="w-64 h-64" />
 
 ### Available files
 

diff --git a/content/docs/configuration/env-variables.mdx b/content/docs/configuration/env-variables.mdx
@@ -6,35 +6,42 @@ description: Complete reference for all OrcaCD configuration options
 Below are all the environment variables supported by OrcaCD. These should be configured in your `.env` file.
 Be cautious when modifying environment variables that are not recommended to change.
 
+Each variable is tagged with a **Type**:
+
+- <Badge variant="red">Required</Badge> - OrcaCD will not function correctly without this being set.
+- <Badge variant="amber">Recommended</Badge> - optional, but recommended to change
+- <Badge variant="purple">Security</Badge> - optional, but recommended to harden your deployment.
+- <Badge variant="gray">Optional</Badge> - safe to leave at the default value.
+
 ## General
 
 These environment variables can be used in both the agent and the hub.
 
-| Variable    | Default Value | Recommended to change | Description                                                |
-| ----------- | ------------- | --------------------- | ---------------------------------------------------------- |
-| `LOG_LEVEL` | `info `       | no                    | Log level. Options: trace, debug, info, warn, error, fatal |
-| `LOG_JSON`  | `false`       | no                    | Enable JSON formatted logs.                                |
+| Variable    | Default Value | Type                                   | Description                                                |
+| ----------- | ------------- | -------------------------------------- | ---------------------------------------------------------- |
+| `LOG_LEVEL` | `info `       | <Badge variant="gray">Optional</Badge> | Log level. Options: trace, debug, info, warn, error, fatal |
+| `LOG_JSON`  | `false`       | <Badge variant="gray">Optional</Badge> | Enable JSON formatted logs.                                |
 
 ## Hub
 
-| Variable               | Default Value | Recommended to change | Description                                                                                                                                                             |
-| ---------------------- | ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `APP_URL`              | `-`           | yes (required)        | The URL of the OrcaCD instance                                                                                                                                          |
-| `APP_SECRET`           | `-`           | yes (required)        | Secret used for authentication and encryption. Generate one with `openssl rand -base64 42`                                                                              |
-| `HOST`                 | `0.0.0.0`     | no                    | Host address                                                                                                                                                            |
-| `PORT`                 | `8080`        | no                    | Container port                                                                                                                                                          |
-| `DISABLE_LOCAL_AUTH`   | `false`       | no                    | Disable password authentication. Useful when using SSO with OIDC                                                                                                        |
-| `TRUSTED_PROXIES`      | `-`           | no                    | Recommended if using a reverse proxy. Comma seperated list of network origins                                                                                           |
-| `ALLOWED_IPS`          | `-`           | no                    | Harden the hub by only allowing requests from certain IPs. Comma seperated list of CIDR ranges or single IPs. This does not apply to webhooks or the agent connections. |
-| `DISABLE_UI`           | `false`       | no                    | Disable serving the frontend. Useful when using the hub only for API access.                                                                                            |
-| `ALLOWED_INTERNAL_IPS` | `-`           | no                    | Private IPs that should be ignored by the SSRF protection. Comma seperated list of CIDR ranges or single IPs                                                            |
-| `DEMO`                 | `false`       | no                    | This mode disables all functions except the login and additionally seeds some demo data in the database                                                                 |
+| Variable               | Default Value | Type                                       | Description                                                                                                                                                             |
+| ---------------------- | ------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `APP_URL`              | `-`           | <Badge variant="red">Required</Badge>      | The URL of the OrcaCD instance                                                                                                                                          |
+| `APP_SECRET`           | `-`           | <Badge variant="red">Required</Badge>      | Secret used for authentication and encryption. Generate one with `openssl rand -base64 42`                                                                              |
+| `TRUSTED_PROXIES`      | `-`           | <Badge variant="amber">Recommended</Badge> | Recommended if using a reverse proxy. Comma seperated list of network origins                                                                                           |
+| `DISABLE_LOCAL_AUTH`   | `false`       | <Badge variant="purple">Security</Badge>   | Disable password authentication. Useful when using SSO with OIDC                                                                                                        |
+| `ALLOWED_IPS`          | `-`           | <Badge variant="purple">Security</Badge>   | Harden the hub by only allowing requests from certain IPs. Comma seperated list of CIDR ranges or single IPs. This does not apply to webhooks or the agent connections. |
+| `HOST`                 | `0.0.0.0`     | <Badge variant="gray">Optional</Badge>     | Host address                                                                                                                                                            |
+| `PORT`                 | `8080`        | <Badge variant="gray">Optional</Badge>     | Container port                                                                                                                                                          |
+| `DISABLE_UI`           | `false`       | <Badge variant="gray">Optional</Badge>     | Disable serving the frontend. Useful when using the hub only for API access.                                                                                            |
+| `ALLOWED_INTERNAL_IPS` | `-`           | <Badge variant="gray">Optional</Badge>     | Private IPs that should be ignored by the SSRF protection. Comma seperated list of CIDR ranges or single IPs                                                            |
+| `DEMO`                 | `false`       | <Badge variant="gray">Optional</Badge>     | This mode disables all functions except the login and additionally seeds some demo data in the database                                                                 |
 
 ## Agent
 
-| Variable                              | Default Value | Recommended to change | Description                                                                                                            |
-| ------------------------------------- | ------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `HUB_URL`                             | `-`           | yes (required)        | The URL of the Hub. Example: `https://example.com`                                                                     |
-| `AUTH_TOKEN`                          | `- `          | yes (required)        | The authentication token of the agent. Register an agent in the hub frontend to retrieve it                            |
-| `RESTRICT_VOLUMES_TO_DEPLOYMENTS_DIR` | `false`       | no                    | Restrict the volumes that can be mounted to locations within the OrcaCD deployments directory. This enhances security. |
-| `ALLOWED_PRIVILEGED_APPS`             | `-`           | no                    | Comma seperated list of app id that are allowed to bypass certain restrictions enforced by OrcaCD                      |
+| Variable                              | Default Value | Type                                     | Description                                                                                                            |
+| ------------------------------------- | ------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `HUB_URL`                             | `-`           | <Badge variant="red">Required</Badge>    | The URL of the Hub. Example: `https://example.com`                                                                     |
+| `AUTH_TOKEN`                          | `- `          | <Badge variant="red">Required</Badge>    | The authentication token of the agent. Register an agent in the hub frontend to retrieve it                            |
+| `RESTRICT_VOLUMES_TO_DEPLOYMENTS_DIR` | `false`       | <Badge variant="purple">Security</Badge> | Restrict the volumes that can be mounted to locations within the OrcaCD deployments directory. This enhances security. |
+| `ALLOWED_PRIVILEGED_APPS`             | `-`           | <Badge variant="gray">Optional</Badge>   | Comma seperated list of app id that are allowed to bypass certain restrictions enforced by OrcaCD                      |
diff --git a/content/docs/demo.mdx b/content/docs/demo.mdx
@@ -3,6 +3,10 @@ title: Demo
 description: Live demo of Orca CD in action, showcasing its features and capabilities.
 ---
 
+<Callout title="Not available" type="warn">
+	The demo instance is currently not available. Please check back later for updates.
+</Callout>
+
 To access the live demo of Orca CD, please visit the following link:
 
 [Live Demo](https://demo.orcacd.com)

diff --git a/content/docs/guides/github-actions.mdx b/content/docs/guides/github-actions.mdx
@@ -8,17 +8,7 @@ OrcaCD supports triggering deployments directly from GitHub Actions using [GitHu
 ## Prerequisites
 
 - A GitHub repository connected in OrcaCD with provider type **GitHub**
-- **GitHub Actions OIDC** enabled on that repository in OrcaCD (Repository Settings → enable the toggle)
-- The OrcaCD Hub must be reachable from GitHub's network
-
-## How It Works
-
-When a GitHub Actions workflow runs, it requests a short-lived OIDC token from GitHub. OrcaCD verifies this token against GitHub's public OIDC endpoint and checks that:
-
-1. The token's repository claim matches a GitHub repository registered in OrcaCD with GitHub Actions OIDC enabled.
-2. The workflow was **not** triggered by a `pull_request` or `pull_request_target` event (to prevent untrusted forks from triggering deployments).
-
-If verification succeeds, OrcaCD finds all applications linked to the matching repository and branch, then dispatches the requested actions.
+- The OrcaCD Hub must be reachable from GitHub's network.
 
 ## Example Workflow
 
@@ -28,22 +18,32 @@ Add a step at the end of your CI workflow to notify OrcaCD after a successful bu
 permissions:
   id-token: write
 
-- uses: OrcaCD/deploy-action@...
+- uses: OrcaCD/deploy-action@... # Replace ... with the latest version or hash
   with:
-    # The OrcaCD hub URL (e.g., https://orca.example.com)
+    # The OrcaCD hub URL (required)
     # Required
     hub: https://orca.example.com
 
     # Whether to sync the repo content (compose files)
     # Optional, default: true
     syncRepo: true
 
-    # Whether to pull the latest container image versions
+    # Whether to pull the latest container image versions,
+    # even it the compose file has not changed
     # Optional, default: false
     pullImages: false
 ```
 
-## Branch and Tag Support
+## Use Cases
 
-- **Branch pushes**: OrcaCD deploys all applications linked to the pushed branch.
-- **Tag pushes**: OrcaCD resolves which branches the tagged commit belongs to and deploys all applications linked to those branches.
+- Trigger on tag creation to deploy a new version of your application when a new release is created
+- To deploy a new version of a mutable image (e.g. `latest`) after a successful build and push to the registry
+
+## How It Works
+
+When a GitHub Actions workflow runs, it requests a short-lived OIDC token from GitHub. OrcaCD verifies this token against GitHub's public OIDC endpoint and checks that:
+
+1. The token's repository claim matches a GitHub repository registered in OrcaCD with GitHub Actions OIDC enabled.
+2. The workflow was **not** triggered by a `pull_request` or `pull_request_target` event (to prevent untrusted forks from triggering deployments).
+
+If verification succeeds, OrcaCD finds all applications linked to the matching repository and branch, then dispatches the requested actions.
diff --git a/content/docs/guides/meta.json b/content/docs/guides/meta.json
@@ -0,0 +1,3 @@
+{
+	"pages": ["reverse-proxy", "oidc", "github-actions"]
+}
diff --git a/content/docs/guides/oidc.mdx b/content/docs/guides/oidc.mdx
@@ -5,7 +5,7 @@ description: Learn how to use OIDC providers for auhentication in OrcaCD
 
 OrcaCD supports OIDC authentication, allowing users to log in using their existing accounts from various OIDC providers. This guide will walk you through the process of setting up OIDC authentication in OrcaCD.
 
-<Callout title="Disable password login" type="warn">
+<Callout title="Disable password login" type="info">
 	When using OIDC authentication, you can disable password login to enhance security. This ensures
 	that users can only log in using their OIDC provider accounts, reducing the risk of unauthorized
 	access through weak or compromised passwords. Before disabling password login, make sure the OIDC
@@ -15,11 +15,11 @@ OrcaCD supports OIDC authentication, allowing users to log in using their existi
 
 </Callout>
 
-## Example (Pocket Id)
+## Example (Pocket ID)
 
-To set up OIDC authentication with Pocket Id, follow these steps:
+To set up OIDC authentication with Pocket ID, follow these steps:
 
-### 1. Create a Pocket Id Application
+### 1. Create a Pocket ID Application
 
 Go to your Pocket ID dashboard and create a new application. Give it a name and leave the redirect URI blank for now.
 
@@ -31,19 +31,19 @@ You can find the OrcaCD logo [here](https://github.com/OrcaCD/orca-cd/tree/main/
 
 1. Go to the OrcaCD Admin settings and navigate to the OIDC configuration section.
 2. Create a new OIDC provider configuration with the following details:
-   - **Name**: A name for your OIDC provider (e.g., "Pocket Id").
-   - **Issuer URL**: The issuer URL provided by Pocket Id (e.g., `https://pocketid.com`).
-   - **Client ID**: The client ID from your Pocket Id application.
-   - **Client Secret**: The client secret from your Pocket Id application.
+   - **Name**: A name for your OIDC provider (e.g., "Pocket ID").
+   - **Issuer URL**: The issuer URL provided by Pocket ID (e.g., `https://example.com`).
+   - **Client ID**: The client ID from your Pocket ID application.
+   - **Client Secret**: The client secret from your Pocket ID application.
 3. Save the configuration and ensure it is enabled.
 
 ![OrcaCD OIDC Configuration](/assets/docs/orca-sso-registration.png?url)
 
 ### 3. Test the Configuration
 
 1. Log out of OrcaCD if you are currently logged in.
-2. Click on the "Login with Pocket Id" button on the login page.
+2. Click on the "Login with Pocket ID" button on the login page.
 3. You will be redirected to the Pocket Id login page. Enter your credentials and log in.
-4. After successful authentication, you will be redirected back to OrcaCD and logged in with your Pocket Id account.
+4. After successful authentication, you will be redirected back to OrcaCD and logged in with your Pocket ID account.
 
 <div className="w-xl mx-auto">![OrcaCD Login Page](/assets/docs/sso-login-screen.png?url)</div>