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

# General Installation

> Console process, database, object storage, and reverse proxy

Shared foundation for every executor. Backend-specific knobs live on each backend page.

## Starting the Console

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
git clone <starforge repo> && cd starforge
uv sync
uv run forge-console serve --port 8080 --serve    # --serve binds 0.0.0.0
```

All configuration goes through environment variables (prefixed `FORGE_`) or a `.env` at the repo root (the root `.env.example` is the fully annotated template).

## Core configuration

| Environment variable                                            | Description                                                                                                                                                      |
| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FORGE_DEFAULT_FLEET_KIND`                                      | `local` \| `node` \| `kuberay` \| `slurm`                                                                                                                        |
| `FORGE_WEB_JWT_SECRET`                                          | **Must be set** to a fixed strong random string; the default random generation logs everyone out on restart and makes tokens non-interchangeable across replicas |
| `FORGE_PUBLIC_URL`                                              | Externally reachable address (for OIDC callbacks / CLI authorization)                                                                                            |
| `FORGE_INGEST_URL`                                              | Address training containers report metrics to; **must be a console URL reachable from inside the cluster network**, never 127.0.0.1                              |
| `FORGE_ALLOWED_IMAGE_REGISTRIES`                                | Comma-separated registry hosts for user `--image`. Empty: first-class framework overrides unrestricted, **custom images rejected**                               |
| `FORGE_IMAGE_VERL` / `FORGE_IMAGE_TRL` / `FORGE_IMAGE_OPENRLHF` | Default OCI images for those frameworks (deployment artifacts; catalog does not embed the reference)                                                             |
| `FORGE_DB_PATH` / `FORGE_DB_URL`                                | Defaults to SQLite (`.forge/web.db`); production can switch to PostgreSQL                                                                                        |
| `FORGE_REDIS_URL`                                               | Strongly recommended for multi-replica deployments: instant token revocation, distributed rate limiting, consistency                                             |
| `FORGE_TIMEZONE`                                                | Service-level timezone (schedule windows and daily-report boundaries)                                                                                            |

## Object storage (MinIO / S3)

Datasets, job package distribution (required for kuberay), and artifact archiving share one setup:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
FORGE_S3_ENDPOINT=https://minio.internal
FORGE_S3_ACCESS_KEY=…
FORGE_S3_SECRET_KEY=…
FORGE_S3_BUCKET=starforge
```

The job side only ever receives **presigned URLs** and never holds storage credentials.

## Reverse proxy (nginx)

`deploy/nginx.conf.example` provides a template. Key points:

* Disable proxy buffering for `/api` (SSE log streaming);
* Reverse-proxy `/docs` to the Mintlify-hosted site (see `mintlify/README.md`);
* Relax WebSocket / long-connection timeouts.

## Database migrations

Alembic migrations run automatically at service startup; to run them manually:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
uv run alembic upgrade head
```

## First administrator

On a fresh deployment, the first user is created via `/api/auth/setup` (the console's first-visit onboarding), or added by the CLI `sf admin user-add` under the local account system. For OIDC integration, see [Authentication and Accounts](/en/ops/auth).

<Tip>
  Before going live, run the [E2E closed loop](/en/ops/e2e-testing) once: a single command verifies the full "submit → schedule → container → ingest" chain is configured correctly.
</Tip>