Resume service execution modes

The runtime records each service's development or production mode after a successful start. restartDevServers.sh, devstack.sh restart SERVICE, and devstack.sh start SERVICE resume the saved modes. A development worker can therefore keep its mode beside a production BFF.

quickStarter.sh starts prepared, stopped containers. It does not rebuild them or change execution mode.

Command	Effect
bash restartDevServers.sh --prod	Build production artifacts and select production execution for all selected services
bash devstack.sh start SERVICE --prod	Build and select production for an already stopped, prepared service; refuse a running container
bash devstack.sh restart SERVICE	Resume the service's saved mode. Do not add --prod.
bash startDevServers.sh	Choose development execution for a new full start
bash startDevServers.sh --prod	Choose production execution for a new full start

A normal full restart without --prod preserves saved service modes. It does not rebuild production artifacts or run database/schema initialization. For code publication, use the full/scoped release procedures. It is not a guaranteed switch from production to development. A service absent from saved state defaults to development during normal resume.

Do not edit runtime state by hand. A failed start does not establish successful prepared state. Mode changes do not delete data or volumes.

For instance boundaries and startup prerequisites, read Docker development.

Change infrastructure placement

Use this procedure for an existing installation that must return from real partialRemote placement to fulllocal. Execution mode (development or production) and infrastructure placement are separate settings. For the remote direction, use selected remote infrastructure.

Preserve existing state

Retain the local Kafka and Qdrant volumes. Check their freshness against remote writes before the switch. Complete any required reverse transfer with application writers stopped. The runtime checks volume presence, but does not prove data freshness. Do not use reset, --reset, cleanup, or volume deletion to change placement.

Run the commands from the motherrepo root for the intended instance. Keep only one complete stack active during cold bootstrap. Check host memory and the active instances before startup. Use the Docker prerequisites.

1. With the original settings, run bash stopDevServer.sh. This stops the instance's containers and retains volumes.
2. In the root .env, set ECS_DEPLOYMENT_MODE=fulllocal and ECS_REMOTE_SIMULATION=false. Preserve the instance identity and existing local connection settings.
3. Run bash devstack.sh validate. Correct any reported configuration or readiness failure before continuing.
4. Run bash restartDevServers.sh. This applies the new placement and preserves saved service execution modes.
5. Check the endpoints and complete the lifecycle acceptance checks below.

The root configuration controls placement. Shell overrides do not replace these selectors. fulllocal is the default when the placement selector is absent. Simulation defaults to false. fulllocal with simulation true is invalid. Inactive remote fields can remain, but they do not select remote placement.

If retained local Kafka/Qdrant volumes are absent, the return from real remote placement stops before startup. Resolve migration readiness before continuing. Do not create replacement data to bypass this check. If no prepared runtime exists, use bash startDevServers.sh after the installation prerequisites are complete.

Restart or quick-start

A normal restart recreates runtime containers with the current configuration. It preserves volumes and saved execution modes. Use it after a placement or endpoint change. A scoped service restart cannot apply a global placement change.

Quick-start requires the prepared configuration and container identities to match the saved state. It starts existing stopped containers without initialization, builds, or recreation. After a configuration change, quick-start refuses stale state and directs you to ordinary restart. Do not edit the saved runtime state to bypass this check.

Check placement and lifecycle behavior

Check bash devstack.sh status after the transition. Local Kafka brokers and Qdrant must appear for full-local placement. Also check the selected endpoint fields inside a running consumer. Container health or a mode label alone does not prove endpoint selection.

For example, run bash devstack.sh shell queue, then run this command inside the container:

printenv KAFKA_NETWORK KAFKA_LAN_BOOTSTRAP_SERVERS KAFKA_TAILSCALE_BOOTSTRAP_SERVERS QDRANT_URL KNOWLEDGE_EXTRACTOR_URL

For full-local placement, the Kafka bootstrap lists use broker1:9092,broker2:9092,broker3:9092. The standard local endpoints are http://qdrant:6333 and http://knowledge-extractor:9998. Check other affected consumers against the intended placement. Inspect only selected fields, without full environment or configuration dumps. Exit the container shell before the next command.

During an agreed maintenance window, require all four lifecycle scripts to succeed:

Command from the motherrepo root	Required result
bash startDevServers.sh	Full startup completes with development execution. Use --prod if production execution is intended.
bash restartDevServers.sh	Restart completes and preserves the prepared execution modes and data.
bash stopDevServer.sh	The instance's containers stop, including local infrastructure. Volumes remain.
bash quickStarter.sh	The stopped, prepared containers resume with unchanged configuration and execution modes.

Run these checks in table order. Stop on a failure and inspect its diagnostic before another attempt. After quick-start, repeat the endpoint checks and read existing application data. Check a permitted application action and its persisted result. Healthy containers alone do not complete acceptance. Placement checks do not establish a latency cause or a performance benchmark.

Preserve the isolated runtime owner marker

Before a source refresh, check the isolated instance's .docker-state/owner identity separately from its file permissions. For this maintenance, require a physical file owned by the operator, with permissions 0600.

Only repair permissions on a verified, stopped, owned isolated instance. Preserve the marker content and instance identity. Preserve all environment files, keys, and data. Refuse the repair if ownership or identity is uncertain. Do not modify another clone's marker or copy its runtime state.

These are operator safeguards. The runtime checks marker identity, but it does not automatically enforce the marker's 0600 permissions or operator ownership. The isolated snapshot checks reject symbolic and hard links. A permission repair must leave the identity unchanged.