feat: Installation prerequisites

content/docs/setup/installation.mdx

@@ -8,6 +8,21 @@ description: Get OrcaCD running quickly with Docker
 	breaking changes at any time.
 </Callout>
 
+## 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 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).
+
+<Callout>
+	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`.
+</Callout>
+
 ## 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.
 
 <Callout>
@@ -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.
+
+<Callout>You can skip this step if you are running OrcaCD locally without a domain.</Callout>
 
 ## Create an Admin Account [step]
 
-Create an admin account on `https://<your-app-url>/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)