Configure the root environment
The unified runtime reads .env in the motherrepo root. Start with first installation if the machine is not prepared. Use environment reference to look up exact variables.
Prepare a new configuration
Restore a checked archive through secrets management, or copy .env.example only for a new empty installation. Do not overwrite an existing file with the template.
The file contains text assignments, not shell commands. Keep one assignment per variable. Do not execute it with source or export $(...). Standalone service .env.example files describe separate entrypoints. They do not override the unified root contract.
Keep the instance ID, tenant identity, database credentials, Kafka cluster identity, and encryption keys when retaining data. A changed password assignment does not change a password already stored by a service.
Choose placement and execution separately
ECS_DEPLOYMENT_MODE | ECS_REMOTE_SIMULATION | Result |
|---|---|---|
Missing or fulllocal | Missing or false | Selected infrastructure runs locally |
partialRemote | true | Real local services exercise the remote configuration path |
partialRemote | Missing or false | Prepared remote Kafka, ClamAV, Collabora, Tika, and Qdrant |
fulllocal | true | Invalid configuration |
In real remote mode, BFF, Account, backend/.NET services, PostgreSQL, SeaweedFS/S3, OpenSearch, Dragonfly, proxy, and keys remain local. Simulation is not a lower-memory deployment.
Development execution watches source. Production execution runs compiled output. Saved service modes can differ. See execution modes.
Fill the remote block
Complete remote prerequisites before selecting real remote mode. Values in .env.example are local simulation examples, not ready remote endpoints.
| Root input | Required meaning |
|---|---|
REMOTE_KAFKA_BOOTSTRAP_SERVERS | Three reachable advertised host:port endpoints, separated by commas |
REMOTE_KAFKA_SECURITY_PROTOCOL, REMOTE_KAFKA_SASL_MECHANISM | Broker-compatible transport and SASL mechanism |
REMOTE_KAFKA_APP_USERNAME, REMOTE_KAFKA_APP_PASSWORD | Remote application role credentials |
REMOTE_KAFKA_ADMIN_USERNAME, REMOTE_KAFKA_ADMIN_PASSWORD | Separate remote administration role credentials |
REMOTE_KAFKA_EXPECTED_CLUSTER_ID | Expected existing remote cluster identity |
REMOTE_CLAMAV_SCAN_URL, REMOTE_CLAMAV_SCAN_TOKEN | Authenticated HTTPS scanner URL ending exactly in /scan, with its token |
REMOTE_KNOWLEDGE_EXTRACTOR_URL, REMOTE_KNOWLEDGE_EXTRACTOR_TOKEN | HTTPS extractor origin with a separate token |
REMOTE_COLLABORA_URL | Collabora origin, without credentials or an endpoint path |
REMOTE_QDRANT_URL, REMOTE_QDRANT_API_KEY | Qdrant origin and its API key |
REMOTE_WOPI_ORIGIN, REMOTE_WOPI_ALLOWED_CIDRS | Reachable local callback origin and restricted renderer source addresses |
WOPI_CALLBACK_MODE, WOPI_TAILSCALE_HOST, WOPI_TAILSCALE_BIND_IP, WOPI_TAILSCALE_PORT | Callback mode and this local machine's Tailscale HTTPS binding |
Do not add queries, fragments, or embedded credentials to service origins. The scanner requires its fixed /scan path. The extractor client adds its own path. Use root REMOTE_* inputs rather than manually assigning generated consumer values.
REMOTE_CLAMAV_HOST / REMOTE_CLAMAV_PORT describe the simulation TCP scanner. In real mode, retain them only for an explicitly approved private TCP configuration. A Docker name such as clamav is not a remote private IP.
Coolify values
SERVICE_URL_* contains an origin with a protocol. SERVICE_FQDN_* contains a hostname. SERVICE_PASSWORD_* values belong to that Coolify resource. The laptop cannot resolve a remote resource's variable reference. Obtain its resolved credential securely.
Configure HTTP domains through Coolify's managed proxy. An internal service port is not necessarily a public client port. Preserve unrelated proxy resources. The local setup does not provision Coolify resources.
Kafka transport and identity
Kafka uses its own TCP protocol, not an HTTPS URL. Clients contact the bootstrap broker, then the brokers named in metadata. All advertised endpoints must work. A successful connection to one port is insufficient.
Real sasl_plaintext is restricted to canonical Tailscale IPv4 endpoints in 100.64.0.0/10, with PLAIN. Other remote Kafka connections require sasl_ssl. REMOTE_KAFKA_CA_PATH is unsupported and does not install custom trust.
KAFKA_CLUSTER_ID is retained local identity. REMOTE_KAFKA_EXPECTED_CLUSTER_ID checks the selected remote cluster. Do not change either merely to remove an ownership error.
Office callback
Remote Collabora reads a file through a short-lived, signed WOPI grant from the local BFF. WOPI is the document-access protocol used by the renderer. Login, Graph permission, personal email keys, and the WOPI signing key have separate roles.
For WOPI_CALLBACK_MODE=tailscale-proof, the hostname and bind IP identify the local developer machine. REMOTE_WOPI_ALLOWED_CIDRS restricts the remote renderer, normally to its single /32 source. Prepare valid TLS and Tailscale access rules separately. A configuration assignment does not grant network access.
Use the existing NPM proxy and restricted callback routes. Do not expose the whole BFF/admin surface or send private signing keys to the renderer. The callback address does not replace the Account or BFF login address.
In fulllocal, retained remote callback settings are inactive. You do not need to delete them.
Apply or reverse a configuration change
On a new machine, complete configuration before bash 0daysetup.sh. On a working machine, use an agreed maintenance window and normal restart.
- Preserve configuration, keys, and data backups. Select one full active stack.
- With the old settings, run
bash stopDevServer.sh. It preserves volumes. - Before a new remote Kafka/Qdrant target, have the operator transfer and check state with application writers stopped.
- Change only the required selectors and remote fields. Retain local database, S3, OpenSearch, and Dragonfly values.
- Run the checks and ordinary restart:
bash devstack.sh validate
bash restartDevServers.sh
bash devstack.sh status
Normal restart preserves saved execution modes. Add --prod to explicitly choose production for the selected full stack. Neither restart path runs schema initialization. Plain restart does not rebuild compiled artifacts. For a code release, use the production publication procedure. Then check login, mailbox data, bodies, search, Office, and knowledge retrieval at the actual application addresses.
Kafka offsets and database deduplication state belong together. A new empty cluster is not equivalent to the original. Switching back to fulllocal does not copy newer remote events or Qdrant points into old local volumes. Check freshness and reverse migration first.
quickStarter.sh resumes unchanged prepared containers. It does not apply this configuration change. Remote mode rejects reset even in simulation. Do not switch to local mode to bypass it.
Source selection and isolated tests
Missing, empty, or . ECS_APPLICATION_SOURCE_ROOT uses this checkout. An absolute reviewed snapshot selects application source while root configuration, identity, state, authorization, and data remain local. See reviewed source.
A separate test instance needs its own physical snapshot, configuration, fresh data, keys, and Kafka/Qdrant namespace. A shell ECS_INSTANCE_ID override is insufficient. Prepare an isolated test instance with agreed routing and capacity.