> For the complete documentation index, see [llms.txt](https://docs.alpha-security.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-security.app/deployment/environment.md).

# Environment Variables

All configuration is done through environment variables. The server validates them on startup and will refuse to boot if required values are missing or malformed.

## Required

| Variable             | Description                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `ALPHA_DATABASE_URL` | PostgreSQL connection string. Example: `postgres://al:password@localhost:5432/alpha`                                |
| `ALPHA_JWT_SECRET`   | Secret for signing authentication tokens. Must be at least 16 characters. Generate one with `openssl rand -hex 32`. |

## Optional

| Variable                      | Default          | Description                                                                                                                                                           |
| ----------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NODE_ENV`                    | `development`    | Set to `production` in deployed environments.                                                                                                                         |
| `ALPHA_HOST`                  | `0.0.0.0`        | Address the server listens on.                                                                                                                                        |
| `ALPHA_PORT`                  | `8080`           | Port the server listens on.                                                                                                                                           |
| `ALPHA_JWT_EXPIRES_IN`        | `8h`             | How long auth tokens stay valid. Accepts values like `1h`, `30m`, `7d`.                                                                                               |
| `ALPHA_RETENTION_CHECK_HOURS` | `6`              | How often the server checks retention policies (in hours).                                                                                                            |
| `ALPHA_TOTP_ISSUER`           | `Alpha`          | Issuer name shown in authenticator apps when operators enroll in MFA.                                                                                                 |
| `ALPHA_TOTP_ENCRYPTION_KEY`   | (none)           | 32-byte hex string (64 characters) used to AES-256-GCM encrypt TOTP secrets at rest. Required only if any operator enables MFA. Generate with `openssl rand -hex 32`. |
| `ALPHA_OBJECT_STORE`          | `fs`             | Storage backend for binary artifacts. `fs` for local filesystem, `s3` for S3-compatible (MinIO).                                                                      |
| `ALPHA_OBJECT_STORE_PATH`     | `./data/objects` | Local path for artifact storage when using `fs` backend.                                                                                                              |
| `ALPHA_S3_ENDPOINT`           | (none)           | S3-compatible endpoint URL. Required when `ALPHA_OBJECT_STORE=s3`.                                                                                                    |
| `ALPHA_S3_ACCESS_KEY`         | (none)           | S3 access key. Required when `ALPHA_OBJECT_STORE=s3`.                                                                                                                 |
| `ALPHA_S3_SECRET_KEY`         | (none)           | S3 secret key. Required when `ALPHA_OBJECT_STORE=s3`.                                                                                                                 |

## Docker Compose

In the Docker Compose setup, Postgres-related variables are also used:

| Variable            | Description                                                               |
| ------------------- | ------------------------------------------------------------------------- |
| `POSTGRES_PASSWORD` | Password for the Postgres container. The `ALPHA_DATABASE_URL` must match. |

Set these in `deploy/.env` (copy from `.env.example`).

## Generating secrets

```bash
# JWT secret
openssl rand -hex 32

# TOTP encryption key (only needed if you'll use MFA)
openssl rand -hex 32

# Postgres password
openssl rand -base64 24
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alpha-security.app/deployment/environment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.