ADR 0012 Self Contained Compose

ADR 0012: Ship one self-contained single-node Compose deployment

• Status: Accepted
• Date: 2026-09-21

Context

Niyān needs a deployment path that a laboratory can operate without first assembling a database, object store, reverse proxy, scheduler, and application containers independently. Maintaining several Compose variants for every combination of bundled and managed infrastructure would multiply test paths and make the simplest installation ambiguous. At the same time, institutions with established PostgreSQL, S3-compatible storage, TLS termination, and container orchestration must be able to deploy the Niyān image without the bundled services.

Large-file bytes must continue to travel directly between clients and an S3-compatible endpoint. The default object service therefore needs a browser-reachable HTTPS origin, persistent storage, multipart support, presigned URLs, and CORS behavior compatible with the Niyān web origin. Background reconciliation is bounded PostgreSQL-backed maintenance and does not require a message broker.

Decision

The repository ships one production-oriented Docker Compose file for a self-contained single-node installation. It runs:

• PostgreSQL 17 for control-plane state;
• SeaweedFS in its single-node weed mini mode for the private S3-compatible data plane;
• Caddy for automatic HTTPS and distinct application and object-storage origins;
• the Niyān server;
• the Niyān maintenance process; and
• an explicit one-shot migration service.

PostgreSQL, SeaweedFS, Git repositories, and Caddy state use distinct durable volumes. Redis and Celery are not part of v1. Operators using existing infrastructure deploy the same versioned Niyān image directly and configure its documented environment variables; Niyān does not ship Compose variants for managed-service combinations.

Release tags publish multi-platform images to ghcr.io/niyan-project/niyan. Production installations should pin a semantic version or immutable digest rather than a moving development tag.

Consequences

• A small installation has one documented path whose services, dependencies, health checks, persistence, and TLS routing can be tested together.
• Browser transfers still bypass Django, but the bundled object endpoint requires its own DNS name and HTTPS certificate.
• The bundled stack is a single-node topology and does not claim high availability. PostgreSQL and SeaweedFS volumes remain failure domains that require coordinated backups.
• Institutions can replace the bundled services without requiring another repository artifact or a deployment-specific Niyān build.
• SeaweedFS becomes a supported deployment dependency for the bundled path, while Niyān's application boundary remains provider-neutral S3.