Reference
System Requirements
Minimum hardware, service dependencies, and network requirements for running Monospace in production.
Overview
These are the minimum requirements for running Monospace in production. Sizing covers a single-node deployment — see Scaling for running multiple replicas.
Hardware
Sizing below assumes a single-node deployment and covers the Monospace application container alone. If you run PostgreSQL, RabbitMQ, and Redis on the same host — as in the reference compose file — allocate additional resources for those services.
The disk figure covers the container's own filesystem — the binary, logs, and temp files. It doesn't cover file storage: store assets on an S3-compatible bucket rather than the container's disk. See File / object storage below.
| Minimum | Recommended | |
|---|---|---|
| vCPU | 0.5 | 1 |
| RAM | 1 GB | 2 GB |
| Disk | 20 GB SSD | 50 GB SSD |
Service Dependencies
| Component | Required | Requirement |
|---|---|---|
| Deployment | Required | Docker / Docker Compose. The image is Linux-only, built for linux/amd64 and linux/arm64 — no Windows containers. See the reference compose file. |
| System database | Required | PostgreSQL 14–18, with backups enabled. |
| Event bus | Required | RabbitMQ 3.7.0+ — queues background email delivery (welcome, invite, and password-reset messages) and, in clustered mode, broadcasts metadata changes between replicas. |
| File / object storage | Required | An S3-compatible bucket or a local directory. The container's disk is ephemeral, so local storage needs a persistent volume. In clustered mode, local storage must be a mount shared by every replica. |
| Email / SMTP | Required for invites and password resets | Sends password-reset and invite emails. The instance starts without it and logs a warning, but invites and password resets fail until an emailer and RabbitMQ are configured. |
| TLS / proxy | Required | Monospace doesn't terminate TLS itself. Recommend TLS 1.2+ at the proxy. |
| Secrets / key material | Required | JWT signing keys (Ed25519) and a KMS master key, generated once by the keygen init container into a persistent /keys volume. |
| Cache | Required by default | Redis 7.4+ or Valkey 7.2+. CI tests Redis 7.4 and 8.10 and Valkey 7.2 and 9.1. To run without caching, set MONOSPACE_CACHE__ENABLED to false. See Caching. |
Warning
Back up the
/keys volume. Losing it makes KMS-encrypted data unrecoverable — there's no restore path.Network & Connectivity
| Component | Direction | Requirement |
|---|---|---|
| Application traffic | Inbound | TCP 8100 by default (MONOSPACE_PORT) — single port serves both the API and Studio's static assets in the production image. |
| SMTP relay | Outbound | To whichever host you configure under MONOSPACE_SYSTEM_EMAILER__HOST. |
| Object storage | Outbound | To S3, or an S3-compatible endpoint, if you're not using local disk. |
| Licensing API | Outbound | HTTPS to https://licensing.monospace.io — required when MONOSPACE_LICENSE__KEY is set. The instance activates the key at startup, revalidates on the license's schedule, and does not start if the service is unreachable. Not contacted on the Starter license or with an offline token. Allowlist this if you're behind an egress firewall. See Licensing. |
| Anonymous usage telemetry | Outbound | HTTPS to https://telemetry.monospace.io/v2/events — sends an install ID, version, a configuration snapshot, and operation counts. Never credentials, connection details, or your data. Allowlist this if you're behind an egress firewall. |
Scaling
Monospace supports both vertical and horizontal scaling. Clustered mode is enabled by default, including on a single replica.
- Vertical — increase vCPU, RAM, or disk on the existing node, per the Hardware table above.
- Horizontal — run multiple replicas in clustered mode:
- Replicas coordinate metadata changes through PostgreSQL and RabbitMQ.
- Local disk file storage is rejected outright in clustered mode unless the path is a shared mount every replica can reach (e.g., NFS). Use S3-compatible object storage instead.
- A release with a destructive migration needs a full cluster restart — otherwise the first replica to pick up the new version migrates the database while the others keep querying a schema that no longer matches.
- Rolling back a release needs a database restore. A replica refuses to start against a system database with a migration newer than the one it knows.
See Horizontal Scaling for shared storage, replica configuration, health checks, and upgrades.
See Also
- Installation — set up Monospace with the reference Docker Compose stack
- Configuration — every environment variable, including the ones referenced above
- Licensing — how a license is applied, checked at startup, and revalidated