From d6d64863d8179a7c602cdc13be9051ad0450b151 Mon Sep 17 00:00:00 2001 From: alex289 Date: Thu, 16 Jul 2026 19:19:10 +0200 Subject: [PATCH 1/2] feat: Installation prerequisites --- content/docs/setup/installation.mdx | 31 ++++++++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/content/docs/setup/installation.mdx b/content/docs/setup/installation.mdx index e1845b3..2a7e608 100644 --- a/content/docs/setup/installation.mdx +++ b/content/docs/setup/installation.mdx @@ -8,6 +8,21 @@ description: Get OrcaCD running quickly with Docker breaking changes at any time. +## Prerequisites + +OrcaCD consists of two components: the **Hub**, the central control plane that serves the web UI and manages your deployments, and the **Agent**, which runs on every machine where applications should be deployed and executes the deployments there. One Hub can manage many Agents on different machines, but both can also run together on a single machine — which is what this quickstart sets up. See the [architecture overview](../architecture/overview) for more details. + +Before you start, make sure you have: + +- A machine to run the Hub and Agent on — typically a Linux server or VPS, but any machine with Docker works for testing. +- [Docker Engine](https://docs.docker.com/engine/install/) with the [Docker Compose plugin](https://docs.docker.com/compose/install/) installed. +- For a publicly reachable setup: a domain with a DNS record pointing to your server, and a reverse proxy for HTTPS. OrcaCD does not bind ports 80/443 or terminate TLS itself — the Hub listens on port `8080` (bound to localhost in the provided compose file), and you put your own reverse proxy (Nginx, Caddy, Traefik, ...) in front of it. See the [reverse proxy guide](../guides/reverse-proxy). + + + Just trying OrcaCD out? You don't need a domain or reverse proxy: run everything locally, set + `APP_URL=http://localhost:8080` in the `.env` file, and access the Hub at `http://localhost:8080`. + + ## Start Hub and Agent [step] Download the [`docker-compose.yml`](https://raw.githubusercontent.com/OrcaCD/orca-cd/main/docker-compose.yml) and [`.env`](https://raw.githubusercontent.com/OrcaCD/orca-cd/main/.env.example) file: @@ -22,7 +37,14 @@ wget -O docker-compose.yml https://raw.githubusercontent.com/OrcaCD/orca-cd/main wget -O .env https://raw.githubusercontent.com/OrcaCD/orca-cd/main/.env.example ``` -Edit the `.env` file according to the instructions in the file. You can also customize other environment variables as needed. +Edit the `.env` file according to the instructions in the file. The most important values are: + +- `APP_URL` — the URL under which the Hub will be reachable. OrcaCD does not provision this URL for you: it is your domain pointing at your reverse proxy (e.g. `https://orcacd.example.com`), or `http://localhost:8080` for a local setup. +- `APP_SECRET` — used for authentication and database encryption. Generate one with `openssl rand -base64 42`. +- `HUB_URL` — the URL the Agent uses to reach the Hub, usually the same as `APP_URL`. +- `AUTH_TOKEN` — leave empty for now; you will create it in the Hub UI in a later step. + +You can also customize other environment variables as needed. See the [environment variables page](../configuration/env-variables) for more details. @@ -38,11 +60,14 @@ docker compose up -d ## Configure your Reverse Proxy [step] -See the [reverse proxy guide](../guides/reverse-proxy) for instructions on how to configure a reverse proxy for your Hub. +The Hub only listens on port `8080` on localhost. To make it reachable under your domain with HTTPS, configure a reverse proxy that forwards traffic to it. +See the [reverse proxy guide](../guides/reverse-proxy) for instructions for Nginx, Caddy and Traefik. + +You can skip this step if you are running OrcaCD locally without a domain. ## Create an Admin Account [step] -Create an admin account on `https:///login` +Open the Hub in your browser at the `APP_URL` you configured (e.g. `https://orcacd.example.com/login` or `http://localhost:8080/login`) and create an admin account. ![Setup Admin Account](/assets/docs/account-setup.png?url) From 951dd96cfb26969584e6d24c9fafb20dff5fb750 Mon Sep 17 00:00:00 2001 From: alex289 Date: Thu, 16 Jul 2026 19:33:30 +0200 Subject: [PATCH 2/2] feat: Improve server definition --- content/docs/setup/installation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/setup/installation.mdx b/content/docs/setup/installation.mdx index 2a7e608..b4bb1eb 100644 --- a/content/docs/setup/installation.mdx +++ b/content/docs/setup/installation.mdx @@ -14,7 +14,7 @@ OrcaCD consists of two components: the **Hub**, the central control plane that s Before you start, make sure you have: -- A machine to run the Hub and Agent on — typically a Linux server or VPS, but any machine with Docker works for testing. +- A machine to run the Hub and Agent on — typically a Linux server like a VPS, but any machine with Docker works for testing. - [Docker Engine](https://docs.docker.com/engine/install/) with the [Docker Compose plugin](https://docs.docker.com/compose/install/) installed. - For a publicly reachable setup: a domain with a DNS record pointing to your server, and a reverse proxy for HTTPS. OrcaCD does not bind ports 80/443 or terminate TLS itself — the Hub listens on port `8080` (bound to localhost in the provided compose file), and you put your own reverse proxy (Nginx, Caddy, Traefik, ...) in front of it. See the [reverse proxy guide](../guides/reverse-proxy).