> ## Documentation Index
> Fetch the complete documentation index at: https://hyperspeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> Deploy Hyperspeed on a VPS, cloud host, or hosting panel with automatic HTTPS via Caddy and Let's Encrypt.

This guide covers deploying Hyperspeed on a public server — a VPS, a cloud VM, or a managed hosting panel that runs Docker Compose. Caddy handles TLS automatically using Let's Encrypt once you point DNS at your server.

<Warning>
  Hyperspeed supports **one organization per database**. The first user to register creates the workspace through a setup wizard. Subsequent users join via invites or open registration (with admin approval). If you need multiple isolated workspaces, run separate Compose stacks with separate databases.
</Warning>

## Requirements

* A server running Docker and Docker Compose v2
* Ports **80** and **443** available on the host (used by Caddy)
* A domain name with DNS you control
* The **full repository** cloned on the server — not just `docker-compose.yml`

## Deploy to a server

<Steps>
  <Step title="Clone the full repository">
    SSH into your server and clone the entire repository. The Compose file builds `apps/api` and `apps/web`; a standalone `docker-compose.yml` is not enough.

    ```bash theme={null}
    git clone https://github.com/jasfromsolaris/Hyperspeed.git
    cd Hyperspeed
    ```

    All subsequent commands run from this directory (the **repository root**, where `docker-compose.yml` lives).
  </Step>

  <Step title="Point DNS at your server">
    Create an **A record** (and an **AAAA record** if your server has IPv6) for your chosen hostname pointing to the server's public IP address.

    ```
    app.example.com  A  203.0.113.10
    ```

    Caddy uses the HTTP-01 ACME challenge on port **80** to obtain a certificate from Let's Encrypt. DNS must resolve before you start the stack, or certificate issuance will fail.
  </Step>

  <Step title="Configure your production .env">
    Copy the example file and set all required variables:

    ```bash theme={null}
    cp .env.example .env
    ```

    The table below lists every variable you must set for a production deployment.

    | Variable | Required | Description |
    | - | - | - |
    | `JWT_SECRET` | Yes | HMAC key for access tokens. Use at least 32 random characters. Generate with `openssl rand -base64 32`. |
    | `HS_SSH_ENCRYPTION_KEY` | Yes | Base64-encoded 32 bytes. Encrypts stored SSH credentials for the terminal. Generate with `openssl rand -base64 32`. |
    | `CADDY_PUBLIC_HOST` | Yes | Hostname only — no scheme. Example: `app.example.com`. Caddy uses this for the site block and Let's Encrypt. |
    | `CADDY_EMAIL` | Yes | Email address for your Let's Encrypt account. Example: `you@example.com`. |
    | `CORS_ORIGIN` | Yes | Exact browser origin, scheme included. Example: `https://app.example.com`. Must match what users type in the address bar. |
    | `PUBLIC_API_BASE_URL` | Yes | Same public origin as `CORS_ORIGIN`. Used when the API must emit absolute URLs (for example, IDE file previews). |

    A minimal production `.env` looks like this:

    ```bash theme={null}
    JWT_SECRET=<output of: openssl rand -base64 32>
    HS_SSH_ENCRYPTION_KEY=<output of: openssl rand -base64 32>

    CADDY_PUBLIC_HOST=app.example.com
    CADDY_EMAIL=you@example.com
    CORS_ORIGIN=https://app.example.com
    PUBLIC_API_BASE_URL=https://app.example.com
    ```

    <Warning>
      Do not include `https://` in `CADDY_PUBLIC_HOST`. It must be the hostname only. Setting it to `https://app.example.com` will break Caddy's site block.
    </Warning>
  </Step>

  <Step title="Open required ports">
    Ensure your server's firewall or security group allows inbound traffic on these ports:

    | Port | Protocol | Service | Purpose |
    | - | - | - | - |
    | 80 | TCP | Caddy | HTTP and ACME HTTP-01 challenge |
    | 443 | TCP | Caddy | HTTPS |
    | 8080 | TCP | API | Debug access to the API (optional; restrict in production) |

    If your hosting panel already occupies ports 80 or 443, consult your panel's reverse-proxy documentation or adjust the port bindings in `docker-compose.yml`.
  </Step>

  <Step title="Build and start the stack">
    From the repository root:

    ```bash theme={null}
    docker compose up --build -d
    ```

    Compose builds the API and web images, then starts all six services. Caddy contacts Let's Encrypt and obtains a certificate for `CADDY_PUBLIC_HOST` automatically.
  </Step>

  <Step title="Verify the deployment">
    Check that the API is healthy:

    ```bash theme={null}
    curl https://app.example.com/health
    ```

    A successful response looks like:

    ```json theme={null}
    {"status":"ok","version":"1.0.0","git_sha":"abc1234"}
    ```

    <Tip>
      `GET /health` is the canonical health check endpoint. Use it in your load balancer, uptime monitor, or hosting panel's health probe. It returns `"status":"ok"` when the API is running and connected to Postgres and Redis. The `version` and `git_sha` fields are populated when the image is built with the `VERSION` and `GIT_SHA` build args (set `HYPERSPEED_VERSION` and `HYPERSPEED_GIT_SHA` in `.env` and they are forwarded as build args by `docker-compose.yml`).
    </Tip>

    Then open `https://app.example.com` in a browser. The first visit triggers the setup wizard.
  </Step>

  <Step title="Complete the setup wizard">
    Register as the first user. Because no organization exists yet, the registration flow launches the setup wizard:

    1. Enter your name, email, and password.
    2. Name your workspace (organization).
    3. Review the hostname shown in the wizard — it should match your public URL.

    After finishing, you are the workspace admin. Invite teammates from workspace settings.
  </Step>
</Steps>

## Port reference

| Port | Bound by | Notes |
| - | - | - |
| 80 | Caddy | Serves HTTP and handles Let's Encrypt HTTP-01 challenges. Redirects to 443 in production. |
| 443 | Caddy | Serves the app over HTTPS with a Let's Encrypt certificate. |
| 8080 | API container | Direct API access on the host. Useful for debugging; consider restricting with a firewall rule in production. |

## Environment variable reference

| Variable | Role |
| - | - |
| `JWT_SECRET` | HMAC key for access tokens (required in production) |
| `HS_SSH_ENCRYPTION_KEY` | Base64, 32 bytes — required for terminal SSH credential storage |
| `CADDY_PUBLIC_HOST` | Hostname for Caddy's site block (`localhost` = HTTP only; real FQDN = HTTPS via Let's Encrypt) |
| `CADDY_EMAIL` | Let's Encrypt account email when using a real hostname |
| `CORS_ORIGIN` | Exact browser origin allowed for API calls (scheme + host, port only if non-standard) |
| `PUBLIC_API_BASE_URL` | Same public origin users use in the browser; needed when the API emits absolute URLs |

For all available variables including optional ones, see [Environment Variables](/configuration/environment-variables).

## Workspace limit

<Warning>
  The open-source Hyperspeed stack allows **at most one organization per database**. The first user to register creates that organization through the setup wizard. If you need multiple isolated teams, deploy separate stacks with separate databases — do not attempt to create a second organization in the same database.
</Warning>

If the API detects more than one organization in the database (for example after a legacy data migration), it logs a warning at startup and refuses to create additional organizations until only one remains.

## Next steps

* **Custom domains and subdomains** — See the [Domains](/configuration/domains) guide for BYO domain configuration and optional `*.hyperspeedapp.com` subdomains.
* **TLS behind another proxy** — See the [TLS](/configuration/tls) guide if Caddy sits behind Traefik, nginx, or a cloud load balancer.
* **Backups** — See [Backups](/administration/backups) for Postgres and MinIO backup strategies.
* **Upgrades** — See [Upgrades](/administration/upgrades) for the upgrade process and breaking change notes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.