> ## 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.

# Quick Start

> Deploy Hyperspeed locally with Docker Compose and complete first-time setup in minutes.

This guide walks you through running Hyperspeed on your local machine using Docker Compose. You will have a working workspace by the end.

## Prerequisites

* **Docker** and **Docker Compose v2** — Compose v2 is required because `docker-compose.yml` uses `depends_on` health conditions. Verify your versions:

```bash theme={null}
docker --version
docker compose version
```

<Note>
  Docker Compose v2 ships with Docker Desktop and as a plugin (`docker compose`). If your system only has the legacy `docker-compose` binary (v1), upgrade before continuing.
</Note>

## Deploy locally

<Steps>
  <Step title="Clone the repository">
    Clone the full repository. The build contexts for the API and web images are inside `apps/`, so the entire repo is required — not just `docker-compose.yml`.

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

  <Step title="Copy the environment file">
    Copy the example environment file to `.env`. Docker Compose reads this file automatically.

    ```bash theme={null}
    cp .env.example .env
    ```
  </Step>

  <Step title="Set your secrets">
    Open `.env` and set the two required secrets before starting the stack.

    **`JWT_SECRET`** — HMAC key used to sign access tokens. Use a random string of at least 32 characters:

    ```bash theme={null}
    openssl rand -base64 32
    ```

    **`HS_SSH_ENCRYPTION_KEY`** — Encrypts stored SSH credentials for the terminal. Must be base64-encoded 32 bytes:

    ```bash theme={null}
    openssl rand -base64 32
    ```

    Paste both values into `.env`:

    ```bash theme={null}
    JWT_SECRET=<your-generated-value>
    HS_SSH_ENCRYPTION_KEY=<your-generated-value>
    ```

    For a local setup, leave `CORS_ORIGIN=http://localhost` as-is — this matches the address Caddy serves the app on.

    <Warning>
      The default `JWT_SECRET` in `.env.example` (`dev-change-me-in-production-min-32-chars-long`) is a placeholder. Never use it in a real deployment.
    </Warning>
  </Step>

  <Step title="Build and start the stack">
    From the **repository root** (the directory containing `docker-compose.yml`), run:

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

    This builds the API (Go) and web (Vite) images, then starts Caddy, Postgres, Redis, MinIO, the API, and the web container. The first build takes a few minutes.

    <Tip>
      Run with `-d` to start in detached mode: `docker compose up --build -d`
    </Tip>
  </Step>

  <Step title="Open Hyperspeed">
    Once all containers are healthy, open [http://localhost](http://localhost) in your browser. Caddy serves the app on port **80**; the API is also available at [http://localhost:8080](http://localhost:8080) for debugging.
  </Step>

  <Step title="Complete the setup wizard">
    The first time you open the app, clicking **Register** launches the setup wizard. No organization exists yet, so the wizard walks you through creating the singleton workspace:

    1. Enter your **name**, **email**, and **password** to create the admin account.
    2. Enter a **workspace name** for your organization.
    3. Review the hostname and go-live notes, then finish setup.

    After the wizard completes, you are logged in as the workspace admin.

    <Note>
      Hyperspeed supports exactly one organization per database. Once the wizard runs, the **Register** page switches to an access-request flow for subsequent users. Add teammates via invites or enable open registration under workspace settings.
    </Note>
  </Step>

  <Step title="Create your first space">
    A **space** is a project container — it holds a kanban board, chat rooms, a file tree, terminal connections, and automations.

    1. Click **New space** in the sidebar.
    2. Give the space a name and confirm.
    3. Open the **Board** tab to create your first tasks.
  </Step>
</Steps>

## Stack services

The Compose stack runs the following services:

| Service | Image | Purpose |
| - | - | - |
| `caddy` | `caddy:2-alpine` | Reverse proxy; serves the app on ports 80 and 443 |
| `postgres` | `postgres:16-alpine` | Primary database |
| `redis` | `redis:7-alpine` | Pub/sub, presence, and file collab relay |
| `minio` | `minio/minio:latest` | Object storage for uploaded files |
| `api` | Built from source | Go REST API server |
| `web` | Built from source | Static web UI |

## Next steps

* **Deploy to a server** — See [Deployment](/deployment) to run Hyperspeed on a VPS or cloud host with HTTPS.
* **Configure environment variables** — See [Environment Variables](/configuration/environment-variables) for the full reference.
* **Invite your team** — Open workspace settings and generate invite links or enable open registration.


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