RustBox/docker/README.md

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:

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:

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

MySQL + NFS + OpenSearch:

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:

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

Stop it without deleting persistent volumes:

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:

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:

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:

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.