diff --git a/content/docs/architecture/agents.mdx b/content/docs/advanced/architecture/agents.mdx similarity index 100% rename from content/docs/architecture/agents.mdx rename to content/docs/advanced/architecture/agents.mdx diff --git a/content/docs/architecture/applications.mdx b/content/docs/advanced/architecture/applications.mdx similarity index 100% rename from content/docs/architecture/applications.mdx rename to content/docs/advanced/architecture/applications.mdx diff --git a/content/docs/architecture/meta.json b/content/docs/advanced/architecture/meta.json similarity index 100% rename from content/docs/architecture/meta.json rename to content/docs/advanced/architecture/meta.json diff --git a/content/docs/architecture/notifications.mdx b/content/docs/advanced/architecture/notifications.mdx similarity index 100% rename from content/docs/architecture/notifications.mdx rename to content/docs/advanced/architecture/notifications.mdx diff --git a/content/docs/architecture/overview.mdx b/content/docs/advanced/architecture/overview.mdx similarity index 100% rename from content/docs/architecture/overview.mdx rename to content/docs/advanced/architecture/overview.mdx diff --git a/content/docs/architecture/repositories.mdx b/content/docs/advanced/architecture/repositories.mdx similarity index 100% rename from content/docs/architecture/repositories.mdx rename to content/docs/advanced/architecture/repositories.mdx diff --git a/content/docs/advanced/cli.mdx b/content/docs/advanced/cli.mdx index 28b2d6f..a0cc204 100644 --- 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 ``` - 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. -## 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 ] | ---------------- | ------------------------------- | ------------------------------- | | `-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 [--yes] | `` | 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 ] [--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 ``` + +## 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 index bb59c33..d0dbbf9 100644 --- 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) +OrcaCD logo ### Available files diff --git a/content/docs/configuration/env-variables.mdx b/content/docs/configuration/env-variables.mdx index b063c18..d23682b 100644 --- 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**: + +- Required - OrcaCD will not function correctly without this being set. +- Recommended - optional, but recommended to change +- Security - optional, but recommended to harden your deployment. +- Optional - 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 ` | Optional | Log level. Options: trace, debug, info, warn, error, fatal | +| `LOG_JSON` | `false` | Optional | 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` | `-` | Required | The URL of the OrcaCD instance | +| `APP_SECRET` | `-` | Required | Secret used for authentication and encryption. Generate one with `openssl rand -base64 42` | +| `TRUSTED_PROXIES` | `-` | Recommended | Recommended if using a reverse proxy. Comma seperated list of network origins | +| `DISABLE_LOCAL_AUTH` | `false` | Security | Disable password authentication. Useful when using SSO with OIDC | +| `ALLOWED_IPS` | `-` | Security | 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` | Optional | Host address | +| `PORT` | `8080` | Optional | Container port | +| `DISABLE_UI` | `false` | Optional | Disable serving the frontend. Useful when using the hub only for API access. | +| `ALLOWED_INTERNAL_IPS` | `-` | Optional | Private IPs that should be ignored by the SSRF protection. Comma seperated list of CIDR ranges or single IPs | +| `DEMO` | `false` | Optional | 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` | `-` | Required | The URL of the Hub. Example: `https://example.com` | +| `AUTH_TOKEN` | `- ` | Required | The authentication token of the agent. Register an agent in the hub frontend to retrieve it | +| `RESTRICT_VOLUMES_TO_DEPLOYMENTS_DIR` | `false` | Security | Restrict the volumes that can be mounted to locations within the OrcaCD deployments directory. This enhances security. | +| `ALLOWED_PRIVILEGED_APPS` | `-` | Optional | 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 index e3f76d9..e15f2cc 100644 --- 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. --- + + The demo instance is currently not available. Please check back later for updates. + + 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 index db247ab..363d1c8 100644 --- 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,9 +18,9 @@ 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 @@ -38,12 +28,22 @@ permissions: # 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 new file mode 100644 index 0000000..de2a01c --- /dev/null +++ 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 index 0f0614b..282ac9a 100644 --- 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. - + 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 -## 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,10 +31,10 @@ 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) @@ -42,8 +42,8 @@ You can find the OrcaCD logo [here](https://github.com/OrcaCD/orca-cd/tree/main/ ### 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.
![OrcaCD Login Page](/assets/docs/sso-login-screen.png?url)
diff --git a/content/docs/guides/reverse-proxy.mdx b/content/docs/guides/reverse-proxy.mdx index c178b3c..c0e56dd 100644 --- a/content/docs/guides/reverse-proxy.mdx +++ b/content/docs/guides/reverse-proxy.mdx @@ -3,6 +3,14 @@ title: Reverse Proxy description: Learn how to use a reverse proxy with OrcaCD --- +In a production environment, it is strongly recommended to run the OrcaCD Hub behind a reverse proxy with a domain and a valid TLS certificate. + + + Make sure to adjust the `TRUSTED_PROXIES` environment variable to include the IP address of your + reverse proxy, otherwise the Hub will not be able to determine the correct client IP address. You + will also need to set the public URL in the hub and agent environment variables. + + ## Nginx To use Nginx as a reverse proxy for OrcaCD, expose the Hub on localhost only and forward traffic from your public domain to the Hub port. @@ -35,12 +43,6 @@ server { } ``` -Now when registering an agent, you can use following URL as the Hub URL: - -``` -HUB_URL=http://orcacd.example.com -``` - ## Caddy To use Caddy as a reverse proxy for OrcaCD, add the following to your `Caddyfile`: @@ -51,12 +53,6 @@ orcacd.example.com { } ``` -Now when registering an agent, you can use following URL as the Hub URL: - -``` -HUB_URL=https://orcacd.example.com -``` - ## Traefik To use Traefik as a reverse proxy for OrcaCD, you can add the following labels to your Docker Compose configuration for the OrcaCD Hub service: @@ -76,9 +72,3 @@ services: volumes: - ./data/hub:/app/data ``` - -Now when registering an agent, you can use following URL as the Hub URL: - -``` -HUB_URL=http://orcacd.example.com -``` diff --git a/content/docs/helping-out/documentation.mdx b/content/docs/helping-out/documentation.mdx index e9ad91a..dca7d1f 100644 --- a/content/docs/helping-out/documentation.mdx +++ b/content/docs/helping-out/documentation.mdx @@ -1,9 +1,9 @@ --- title: Documentation -description: Contribute to improving the OrcaCD website or documentation +description: Contribute to the OrcaCD website or documentation --- -This guide explains how to add or edit documentation (Fumadocs). +This guide explains how to add or edit the OrcaCD documentation. The source code of the documentation is stored in the [OracaCD/docs GitHub repository](https://github.com/OrcaCD/docs). ## 1. Where docs live @@ -12,10 +12,8 @@ All markdown pages are under `/content/docs`. The file `meta.json` controls the ## 2. Adding a new page 1. Pick the correct folder that matches a collection pattern (e.g. `/guides`). - 2. Create `/content/docs/
/.md`. - -3. Add frontmatter: +3. Add the frontmatter code: ```yaml lineNumbers --- @@ -33,6 +31,6 @@ description: Get OrcaCD running quickly with Docker installation ## 3. Submitting changes -After making changes you can create a pull request to the `main` branch. Please make sure to commit using Conventional Commits (`doc: update guides`). +After making changes you can create a pull request to the `main` branch. Please make sure to commit using Conventional Commits (`docs: update guides`). Thanks for helping out! diff --git a/content/docs/helping-out/translating.mdx b/content/docs/helping-out/translating.mdx index d951261..73fed3a 100644 --- a/content/docs/helping-out/translating.mdx +++ b/content/docs/helping-out/translating.mdx @@ -7,11 +7,11 @@ Help us make OrcaCD accessible in your language by contributing translations. ## Translation Guidelines -Use informal language for translations +Please use informal language for translations if appropriate. ## Getting Started -1. Visit our [Crowdin project page](https://crowdin.com/project/orcacd). +1. Visit our [Crowdin project page](https://crowdin.com/project/orcacd) and join the project. 2. Choose the language you wish to translate into. 3. Open the `en.json` source file. 4. Now you can start translating the strings. diff --git a/content/docs/index.mdx b/content/docs/index.mdx index e845b4a..e08826f 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -1,6 +1,6 @@ --- title: Introduction -description: Welcome to OrcaCD - A simple service for using gitops with docker +description: Welcome to OrcaCD - Simple GitOps for Docker --- @@ -8,16 +8,31 @@ description: Welcome to OrcaCD - A simple service for using gitops with docker breaking changes at any time. -OrcaCD is a simple GitOps tool for Docker. +OrcaCD is a simple GitOps tool for Docker that allows you to deploy your applications using Git as the source of truth. +With OrcaCD, you can easily manage your Docker containers and keep them in sync with your Git repository. -It allows you to deploy your applications with Docker using Git as the source of truth. With OrcaCD, you can easily manage your Docker containers and keep them in sync with your Git repository. +## Why OrcaCD? -This project **initially** started as a course project for the master's degree in computer science - intelligent systems at the [Westphalian University of Applied Sciences](https://www.w-hs.de/). -The goal of this course was to go through the typical phases of a software project like system design, implementation, testing, and documentation. Even though the project was initially created for educational purposes, we decided to make it open source and continue development after the course ended. We believe that OrcaCD can be a useful tool for many developers and we want to share it with the community. +Tools like [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) brought GitOps to Kubernetes, but not every deployment needs a cluster. Many teams run Docker Compose on one or a few VPS instances and don't want the operational overhead of Kubernetes just to get automated, Git-driven deployments. OrcaCD fills that gap with a lightweight GitOps tool built specifically for Docker Compose. -The motivation for this project is based on a prior project for another course where we used [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) for GitOps deployments on Kubernetes. While ArgoCD is a powerful tool, it only supports Kubernetes and is not suitable for everyone. Since most of us already have a VPS with Docker running, we wanted to create a simple GitOps tool that can be used with Docker without the need for Kubernetes. +## Features -The structure, architecture and concepts of OrcaCD can be found in the [architecture documentation](/docs/architecture/overview). +- **Push to deploy** - commit to your Git repository and OrcaCD takes care of the rest. No manual SSH sessions, no forgotten deployment steps. +- **One dashboard, every server** - manage deployments across all your servers and environments from a single place, whether that's one VPS or a dozen. +- **Works with what you already have** - built directly on Docker Compose, so there's nothing new to learn and nothing to migrate. +- **Always up to date** - new image versions are picked up and rolled out automatically, no manual redeploys required. +- **No secrets in your CI pipeline** - connect GitHub Actions securely without storing long-lived credentials. +- **Stay in the loop** - get notified the moment a deployment succeeds or fails, wherever your team already talks. +- **Secure by default** - encrypted communication and data at rest, single sign-on, and IP allowlisting keep your deployments locked down. + +## Origin Story + +OrcaCD **initially** started as a course project for the master's degree in computer science at the [Westphalian University of Applied Sciences](https://www.w-hs.de/). +Having already gathered professional work experience as software engineers, we approached the course like a real-world project, going through the typical phases of a software project: system design, implementation, testing, and documentation. Even though it began for educational purposes, we decided to make it open source and continue development after the course ended, since we believe OrcaCD can be a useful tool for many developers. + +The structure, architecture and concepts of OrcaCD can be found in the [architecture documentation](/docs/advanced/architecture/overview). + +## Screenshots ![Applications Page](/assets/docs/applications-page.png?url) @@ -36,10 +51,6 @@ import { HomeIcon } from "lucide-react"; -## Get to know OrcaCD - -[Try the OrcaCD Demo](/docs/demo) - ## Useful Links - [Installation](/docs/setup/installation) diff --git a/content/docs/meta.json b/content/docs/meta.json index 73d9049..5bc7048 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -5,15 +5,12 @@ "pages": [ "---Getting Started---", "index", - "demo", "---[Rocket]Setup---", "...setup", "---[Settings]Configuration---", "...configuration", "---[Book]Guides---", "...guides", - "---[PencilRuler]Architecture---", - "...architecture", "---[Pickaxe]Advanced---", "...advanced", "---[Bug]Troubleshooting---", diff --git a/content/docs/setup/installation.mdx b/content/docs/setup/installation.mdx index b4bb1eb..345fa7d 100644 --- a/content/docs/setup/installation.mdx +++ b/content/docs/setup/installation.mdx @@ -10,16 +10,16 @@ description: Get OrcaCD running quickly with Docker ## 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. +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](../advanced/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. +- A machine to run the Hub and Agent on - typically a Linux server like a VPS, but any machine with Docker works - [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). +- For a publicly reachable setup: a domain with a DNS record pointing to your server, and a reverse proxy which also handles TLS. By default the Hub only listens on `127.0.0.1:8080`, 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 + Just testing OrcaCD locally? You can skip the domain and reverse proxy setup, set the `APP_URL=http://localhost:8080` in the `.env` file, and access the Hub at `http://localhost:8080`. @@ -39,12 +39,12 @@ wget -O .env https://raw.githubusercontent.com/OrcaCD/orca-cd/main/.env.example 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. +- `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`). +- `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. +We recommend customizing other environment variables as needed. See the [environment variables page](../configuration/env-variables) for more details. @@ -60,14 +60,11 @@ docker compose up -d ## Configure your Reverse Proxy [step] -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. +By default the hub only listens on port `8080` on localhost. Configure your reverse proxy to forward traffic from your domain to the Hub. See the [reverse proxy guide](../guides/reverse-proxy) for instructions for Nginx, Caddy and Traefik. ## Create an Admin Account [step] -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. +Open the Hub in your browser at the `APP_URL` you configured (e.g. `https://orcacd.example.com/login`) and create an admin account. ![Setup Admin Account](/assets/docs/account-setup.png?url) @@ -79,4 +76,4 @@ Navigate to the Agents page and click "Add Agent". Follow the instructions and c ## Start Deploying [step] -Add your first repository and create your first deployment. +Add your first repository and create your first deployment. Connect a [OIDC provider](../guides/oidc) to allow your team to log in or invite them on the admin page. diff --git a/src/components/badge.tsx b/src/components/badge.tsx new file mode 100644 index 0000000..2f53d5f --- /dev/null +++ b/src/components/badge.tsx @@ -0,0 +1,29 @@ +import { cn } from "@/lib/utils"; + +const variants = { + red: "bg-red-500/10 text-red-600 ring-red-500/20 dark:bg-red-500/15 dark:text-red-400 dark:ring-red-500/25", + amber: + "bg-amber-500/10 text-amber-600 ring-amber-500/20 dark:bg-amber-500/15 dark:text-amber-400 dark:ring-amber-500/25", + purple: + "bg-purple-500/10 text-purple-600 ring-purple-500/20 dark:bg-purple-500/15 dark:text-purple-400 dark:ring-purple-500/25", + gray: "bg-fd-muted text-fd-muted-foreground ring-fd-border dark:bg-fd-muted dark:text-fd-muted-foreground", +} as const; + +export function Badge({ + variant, + children, +}: { + variant: keyof typeof variants; + children: React.ReactNode; +}) { + return ( + + {children} + + ); +} diff --git a/src/routes/docs/$.tsx b/src/routes/docs/$.tsx index 4f0ec20..5843e10 100644 --- a/src/routes/docs/$.tsx +++ b/src/routes/docs/$.tsx @@ -18,6 +18,7 @@ import { baseOptions } from "@/lib/layout.shared"; import { getPageMarkdownUrl, source } from "@/lib/source"; import { Suspense } from "react"; import { AccountRecoveryTerminal } from "@/components/account-recovery-terminal"; +import { Badge } from "@/components/badge"; import { ImageZoom } from "fumadocs-ui/components/image-zoom"; export const Route = createFileRoute("/docs/$")({ @@ -80,6 +81,7 @@ const clientLoader = browserCollections.docs.createClientLoader({ components={{ ...defaultMdxComponents, AccountRecoveryTerminal, + Badge, img: (props) => , }} />