Operations
Integrated runtime and deployment concerns for Marsad as a system.
Operations
Use this page for runtime concerns that require more than one Marsad service to work together. The root Compose files are the source of truth for service names, images, ports, and mounts; this page explains how to operate their combined deployment safely.
Deployment Topology and Network Boundaries
Both the development and production Compose configurations run the Web App, Model Server, Redis, four Model Server workers, and the documentation site. All services join the default Compose network and use service names such as redis for internal communication.
The production deployment assumes a host-level reverse proxy and firewall restrict access to published ports. Browser traffic should reach only the Web App and documentation site over HTTPS. Redis and the Model Server are internal service boundaries and must not be reachable from untrusted networks.
Compose currently publishes ports to the host; publishing a port is not itself an access-control boundary. Keep the following ports restricted by the host firewall or proxy configuration:
| Service | Development host port | Production host port | Intended access |
|---|---|---|---|
redis | 6379 | 6380 | Internal only |
main-app | 3511 | 3510 | HTTPS via reverse proxy |
model-server | 3531 | 3530 | Internal only |
docs-app | 3551 | 3550 | HTTPS via reverse proxy |
Workers do not publish ports. They use the internal redis:6379 address to consume work and call the Web App through its configured internal service URL.
Shared Volumes
The cross-service data boundary is the bind mount ./main/shared-data, mounted at /app/shared-data in the Web App, Model Server, and every Model Server worker. The same host directory and container path are required in both Compose configurations.
Operationally, verify that each of those containers can read and write the same mounted files before accepting work. The Shared Storage contract is the canonical source for relative-path conventions, approved directories, and file ownership.
| Volume or mount | Consumers | Purpose | Operational requirement |
|---|---|---|---|
./main/shared-data:/app/shared-data | Web App, Model Server, all workers | Uploads, collection outputs, analysis artifacts, and generated reports | Preserve it during deployment; back it up and do not remove files referenced by records or active jobs. |
redis-data | Redis | Redis data directory | Keep it persistent if queued jobs must survive container recreation; the Web App database remains the authoritative user-visible job record. |
model-conda-cache | Model Server and all workers | Conda package and pip caches | Improves rebuild/start performance; it is a cache, not application data. |
main-node-modules | Declared but not mounted by default | Optional local dependency cache | Use only when explicitly enabled for local development. |
Required Services and Workers
The Web App requires PostgreSQL from its own configuration as well as Model Server connectivity and the shared-data mount. Redis and the Model Server worker processes are required for asynchronous work; an accepted request will not complete if its queue has no healthy consumer.
For a full integrated workflow, start Redis, the Web App and Model Server, plus the analysis, data-collection/report, and notification workers. The current Compose topology also includes a Tanbih worker, although the application does not currently enqueue work to its queue.
Workers depend on Redis and the Model Server, but depends_on does not prove that either service is healthy; use service logs and a workflow-level check after deployment. The Queue Ownership contract is the canonical source for queue names, job types, timeouts, retries, and status handling.
Production and Local Differences
The two Compose files have the same service topology and shared-data path. They use separate container names, images, environment files, host ports, and model-server build settings so the environments can coexist on one host.
| Concern | Development | Production |
|---|---|---|
| Compose file | docker-compose.yml | docker-compose.prod.yml |
| Image tags | marsad-main:dev, marsad-model:dev, marsad-docs:dev | marsad-main:prod, marsad-model:prod, marsad-docs:prod |
| Model Server build/runtime | Build argument ENV=dev; port 3531 | Build argument ENV=prod; port 3530 |
| Model Server environment | model-server/.env.dev | model-server/.env.prod |
| Documentation URL | https://dev-docs.marsadlab.com | https://docs.marsadlab.com |
| Documentation host port | 3551 | 3550 |
| External access | May be limited to developers by host policy | Reverse proxy and firewall must expose only intended HTTPS endpoints |
The documentation site includes a container health check in both environments. The rest of the topology must be validated with service logs and an end-to-end request that exercises the relevant queue, shared-data input/output, and status callback.
Change Guidance
Review the affected repository documentation for service-specific steps. Review the cross-repository contracts when changing environment variables, queues, shared paths, service URLs, callbacks, or access controls. If a new port is published, worker is added, or mount changes, update both Compose files, this page, and the host reverse-proxy/firewall configuration together.