# RustBox Docker

Run all commands from the `docker/` directory.

The Compose files use the project name `rustbox` and the examples below additionally pass `-p rustbox`. Using `-p` is intentional: a globally exported `COMPOSE_PROJECT_NAME` has higher priority than the `name: rustbox` field in a Compose file and could otherwise attach RustBox to an unrelated Compose project/network.

## Quick start

PostgreSQL + S3/SILO + OpenSearch:

```bash
PORT=3009 \
IMAP_HOST=mail.linuxiarz.pl \
SMTP_HOST=mail.linuxiarz.pl \
docker compose -p rustbox -f compose-postgres-s3-opensearch.yml up --build
```

SQLite, local blobs and local Tantivy:

```bash
IMAP_HOST=mail.linuxiarz.pl \
SMTP_HOST=mail.linuxiarz.pl \
docker compose -p rustbox -f compose-single-sqlite.yml up --build
```

MySQL + NFS + OpenSearch:

```bash
NFS_SERVER=10.0.0.10 \
NFS_EXPORT=/exports/rustbox \
IMAP_HOST=mail.linuxiarz.pl \
SMTP_HOST=mail.linuxiarz.pl \
docker compose -p rustbox -f compose-mysql-nfs-opensearch.yml up --build
```

Check only the RustBox project:

```bash
docker compose -p rustbox -f compose-postgres-s3-opensearch.yml ps
```

Stop it without deleting persistent volumes:

```bash
docker compose -p rustbox -f compose-postgres-s3-opensearch.yml down
```

To also delete the Compose volumes, use `down -v` only when you really want to remove local database, S3 and OpenSearch data.

## Environment variables

Copy the supplied template if you prefer a persistent local configuration:

```bash
cp .env.example .env
```

| Variable | Default | Used by | Description |
|---|---|---|---|
| `HOST` | `0.0.0.0` | all | Address RustBox listens on inside the container. |
| `PORT` | `3001` | all | RustBox HTTP port. The same value is used for the container listener and host port mapping. Example: `PORT=3009` publishes `3009:3009`. |
| `IMAP_HOST` | `mail.example.com` | all | IMAP server hostname used for mailbox access/authentication. Set this for a real mail system. |
| `IMAP_PORT` | `993` | all | IMAP server port. |
| `SMTP_HOST` | `mail.example.com` | all | SMTP server hostname used for sending mail. |
| `SMTP_PORT` | `587` | all | SMTP submission port. |
| `TLS_ENABLED` | `true` | all | Enables TLS for mail connections according to RustBox configuration. |
| `RUST_LOG` | `info` | all | Rust logging filter/level. |
| `SESSION_ENCRYPTION_KEY` | development key | PostgreSQL, MySQL | Shared key used to encrypt session data. All application nodes must use the same value. Replace it outside local testing. |
| `POSTGRES_PASSWORD` | `rustbox-dev-password` | PostgreSQL | Password for PostgreSQL user `rustbox`; also used in `DATABASE_URL`. |
| `S3_ACCESS_KEY` | `rustbox` | PostgreSQL/S3 | Access key for the bundled S3-compatible SILO service and RustBox S3 client. |
| `S3_SECRET_KEY` | `rustbox-s3-dev-password` | PostgreSQL/S3 | Secret key for SILO and RustBox S3 client. Replace it outside local testing. |
| `MYSQL_PASSWORD` | `rustbox-dev-password` | MySQL/NFS | Password for MySQL user `rustbox`; also used in `DATABASE_URL`. |
| `MYSQL_ROOT_PASSWORD` | `rustbox-root-password` | MySQL/NFS | MySQL root password used by the container and health check. |
| `NFS_SERVER` | none | MySQL/NFS | NFS server address. Required for `compose-mysql-nfs-opensearch.yml`. |
| `NFS_EXPORT` | `/rustbox` | MySQL/NFS | Export path on the NFS server. |
| `COMPOSE_PROJECT_NAME` | `rustbox` in `.env.example` | Compose | Compose project name. A value exported in the shell overrides the file's `name:`. The documented commands use `-p rustbox`, which has the highest priority. |

`RUSTBOX_CONFIG` and `DATABASE_URL` are set by the Compose files themselves and normally should not be supplied from the shell for these bundled topologies.

## Avoiding another Compose project

If `docker compose ... ps` shows containers from another application, inspect the effective project-name override:

```bash
printf 'COMPOSE_PROJECT_NAME=%s\n' "${COMPOSE_PROJECT_NAME:-<unset>}"
docker compose -p rustbox -f compose-postgres-s3-opensearch.yml ps
```

For RustBox use `-p rustbox` in operational commands. This isolates service discovery too: the RustBox container resolves PostgreSQL as `postgres` only on the RustBox Compose network.

Useful DNS/database checks:

```bash
docker compose -p rustbox -f compose-postgres-s3-opensearch.yml \
  run --rm --no-deps --entrypoint getent rustbox hosts postgres

docker compose -p rustbox -f compose-postgres-s3-opensearch.yml \
  exec postgres pg_isready -U rustbox -d rustbox
```

## Topologies

### `compose-single-sqlite.yml`

Single RustBox node with SQLite, filesystem blob storage and local Tantivy search. Persistent application data is stored in the `rustbox-data` Docker volume.

### `compose-postgres-s3-opensearch.yml`

Cluster-ready backing topology with PostgreSQL, SILO providing an S3-compatible API, and OpenSearch. The RustBox application container itself has no persistent `data_dir` volume.

The bundled SILO topology is intended for local/integration validation of the S3 API. Production deployments should use a security-reviewed S3-compatible service with an appropriate lifecycle and HA policy.

### `compose-mysql-nfs-opensearch.yml`

MySQL, shared POSIX/NFS blob storage and OpenSearch. The NFS volume driver is deliberate: a normal local Docker named volume is not shared between Docker hosts and therefore is not a valid blob backend for a multi-host RustBox deployment.

## Production notes

Replace all example passwords, S3 credentials and `SESSION_ENCRYPTION_KEY` before production use.

The OpenSearch examples disable its security plugin to keep the local Compose topology self-contained. Production should use TLS/authentication and HTTPS URLs in `search.urls`.

The two cluster-ready examples intentionally start one RustBox application container so they can run directly on a single Docker host. For multiple RustBox application nodes, put them behind an external load balancer and do not publish the same host port from every node; SQL, blob storage and OpenSearch must remain shared between the nodes.

## Sessions and HTTP/HTTPS

Docker Compose defaults to `ENVIRONMENT=development`. In this mode session cookies do not carry the `Secure` attribute, so login works when RustBox is opened directly over plain HTTP, for example `http://localhost:3009`.

For a production deployment behind HTTPS set:

```bash
ENVIRONMENT=production docker compose -p rustbox -f compose-postgres-s3-opensearch.yml up -d --build
```

In `production`, RustBox intentionally marks authentication cookies as `Secure`. Opening the application directly over plain HTTP in that mode causes the browser not to send the session cookie and protected requests return `Invalid or expired session`.

After changing from production/HTTP to development/HTTP, log in again. If the browser still has stale RustBox state, clear cookies/site data for the RustBox origin once and reload.