fix: harden Railway startup persistence and readiness

Dockerfile

@@ -18,7 +18,9 @@ ENV PYTHONUNBUFFERED=1 \
     # Customer-side cloud session and entitlement display cache. Keep it on /data rather
     # than the container's ephemeral home so reconnects do not lose rotated credentials.
     # License issuance, trial state, leases, and revocations remain private services.
-    ENGRAPHIS_STATE_DIR=/data/.engraphis
+    ENGRAPHIS_STATE_DIR=/data/.engraphis \
+    # Dashboard-managed non-secret settings must survive a Railway redeploy with the volume.
+    ENGRAPHIS_ENV_FILE=/data/.engraphis/config.env
 
 WORKDIR /app
 
@@ -33,6 +35,8 @@ RUN apt-get update \
 COPY pyproject.toml README.md LICENSE NOTICE ./
 COPY engraphis ./engraphis
 COPY scripts ./scripts
+# The declared distribution license assets are part of the package build metadata.
+COPY deploy ./deploy
 
 # Railway runs CPU workloads.  Install the CPU-only PyTorch wheel before the embedding
 # stack so pip cannot select PyPI's multi-gigabyte CUDA dependency chain.  The public

deploy/railway-template.json

@@ -15,6 +15,11 @@
     }
   },
   "variables": {
+    "ENGRAPHIS_HOST": {
+      "value": "0.0.0.0",
+      "prompt": "Bind the public Railway service on all IPv4 interfaces so the platform PORT and health probe are reachable.",
+      "required": true
+    },
     "ENGRAPHIS_SERVICE_MODE": {
       "value": "customer",
       "required": true
@@ -27,6 +32,10 @@
       "value": "/data/.engraphis",
       "required": true
     },
+    "ENGRAPHIS_ENV_FILE": {
+      "value": "/data/.engraphis/config.env",
+      "required": true
+    },
     "ENGRAPHIS_API_TOKEN": {
       "value": "${{ secret(48) }}",
       "secret": true,

docker-entrypoint.sh

@@ -6,10 +6,11 @@
 # create /data/engraphis.db or customer state under /data/.engraphis and crashes at
 # startup with `sqlite3.OperationalError: unable to open database file`.
 #
-# We therefore start the container as root, chown the mounted volume to `engraphis`, and
-# exec the real command as `engraphis` via gosu — keeping the deliberate non-root runtime
-# while making the volume writable. When not running as root (e.g. a local `docker run`
-# that already dropped privileges) this is a no-op passthrough.
+# We therefore start the container as root, repair ownership once, and exec the real command
+# as `engraphis` via gosu — keeping the deliberate non-root runtime while making the volume
+# writable. A marker avoids recursively walking a large Hugging Face cache on every restart.
+# When not running as root (e.g. a local `docker run` that already dropped privileges) this is
+# a no-op passthrough.
 set -e
 
 # Default bind host, decided at runtime (not baked into the image). Uvicorn's `::`
@@ -27,11 +28,66 @@ if [ -z "${ENGRAPHIS_HOST:-}" ]; then
 fi
 
 if [ "$(id -u)" = "0" ]; then
-    # ENGRAPHIS_STATE_DIR defaults to /data/.engraphis; ensure both it and the volume root
-    # exist and are owned by the app user. `|| true` so a transient FS hiccup never blocks
-    # startup — the app surfaces any real write failure itself.
-    mkdir -p "${ENGRAPHIS_STATE_DIR:-/data/.engraphis}" 2>/dev/null || true
-    chown -R engraphis:engraphis /data 2>/dev/null || true
+    # ENGRAPHIS_STATE_DIR defaults to /data/.engraphis. Repair the complete volume only on
+    # first boot; later restarts verify the mount and state roots without walking the cache.
+    state_dir="${ENGRAPHIS_STATE_DIR:-/data/.engraphis}"
+    ownership_marker="${state_dir}/.volume-ownership"
+    config_file="${ENGRAPHIS_ENV_FILE:-}"
+    if ! mkdir -p "$state_dir"; then
+        printf '%s\n' "[engraphis] unable to create state directory: $state_dir" >&2
+        exit 1
+    fi
+    if [ -n "$config_file" ]; then
+        config_parent=$(dirname "$config_file")
+        if ! mkdir -p "$config_parent"; then
+            printf '%s\n' "[engraphis] unable to create config directory: $config_parent" >&2
+            exit 1
+        fi
+        if [ -L "$config_file" ]; then
+            printf '%s\n' "[engraphis] refusing symlinked trusted config file: $config_file" >&2
+            exit 1
+        fi
+        if [ ! -e "$config_file" ] && ! : > "$config_file"; then
+            printf '%s\n' "[engraphis] unable to create trusted config file: $config_file" >&2
+            exit 1
+        fi
+        if ! chmod 600 "$config_file"; then
+            printf '%s\n' "[engraphis] unable to restrict trusted config file: $config_file" >&2
+            exit 1
+        fi
+    fi
+    # The app user owns the persistent marker after first boot. Fail closed if it has
+    # replaced that trusted root-startup input with a symlink or a non-regular path:
+    # chown follows symlinks by default and would otherwise let the marker redirect
+    # root's ownership change to an arbitrary target on the mounted volume.
+    if [ -L "$ownership_marker" ]; then
+        printf '%s\n' "[engraphis] refusing symlinked volume ownership marker: $ownership_marker" >&2
+        exit 1
+    fi
+    if [ ! -e "$ownership_marker" ]; then
+        if ! chown -R engraphis:engraphis /data; then
+            printf '%s\n' "[engraphis] unable to repair /data ownership" >&2
+            exit 1
+        fi
+        if ! : > "$ownership_marker"; then
+            printf '%s\n' "[engraphis] unable to create volume ownership marker" >&2
+            exit 1
+        fi
+        if ! chown engraphis:engraphis "$ownership_marker"; then
+            printf '%s\n' "[engraphis] unable to own volume ownership marker" >&2
+            exit 1
+        fi
+    elif [ ! -f "$ownership_marker" ]; then
+        printf '%s\n' "[engraphis] refusing non-regular volume ownership marker: $ownership_marker" >&2
+        exit 1
+    elif ! chown engraphis:engraphis /data "$state_dir" "$ownership_marker"; then
+        printf '%s\n' "[engraphis] unable to verify /data ownership" >&2
+        exit 1
+    fi
+    if [ -n "$config_file" ] && ! chown engraphis:engraphis "$config_file"; then
+        printf '%s\n' "[engraphis] unable to own trusted config file" >&2
+        exit 1
+    fi
     exec gosu engraphis "$@"
 fi
 

docs/HOSTING_RAILWAY.md

@@ -13,13 +13,20 @@ Use the `Dockerfile`, mount a private persistent volume at `/data`, and configur
 
 ```dotenv
 ENGRAPHIS_SERVICE_MODE=customer
+ENGRAPHIS_HOST=0.0.0.0
 ENGRAPHIS_DB_PATH=/data/engraphis.db
 ENGRAPHIS_STATE_DIR=/data/.engraphis
+ENGRAPHIS_ENV_FILE=/data/.engraphis/config.env
 ENGRAPHIS_API_TOKEN=<strong-random-secret>
 ENGRAPHIS_JSON_LOGS=1
 ENGRAPHIS_FORWARDED_ALLOW_IPS=*
 ```
 
+Keep the image entrypoint and default command (`engraphis-dashboard --no-open`) in place. A
+Railway service-level Start Command override can bypass `docker-entrypoint.sh`, which is
+responsible for volume ownership repair, and can leave the app bound only to loopback. Clear
+old Start Command overrides before deploying this image.
+
 Set `ENGRAPHIS_FORWARDED_ALLOW_IPS=*` only when the container is reachable exclusively through
 Railway's trusted proxy. Set the dashboard's public URL where the runtime supports it, terminate
 TLS at the platform edge, and keep the volume private.

docs/RAILWAY_TEMPLATE.md

@@ -8,7 +8,9 @@ issuer, relay, managed compute, Auto Dreaming, Auto Consolidation, or Team ident
 
 - Source: `Coding-Dev-Tools/engraphis`, branch `main`, `Dockerfile` build.
 - Service mode: `customer`.
+- Bind host: `0.0.0.0` so Railway's injected `PORT` and public health probes reach the process.
 - Persistent volume: `/data`.
+- Trusted runtime settings: `/data/.engraphis/config.env` on the persistent volume.
 - Health check: `/api/ready`.
 - `ENGRAPHIS_DASHBOARD_URL` derived from Railway's generated public domain (override it with the
   canonical HTTPS custom domain once one is active so public MCP origin checks remain strict).

tests/test_railway_runtime.py

@@ -50,12 +50,24 @@ def test_container_runtime_matches_the_railway_persistence_and_port_contract():
     assert "useradd --create-home --uid 10001 engraphis" in dockerfile
     assert "HF_HOME=/data/.cache/huggingface" in dockerfile
     assert "ENGRAPHIS_STATE_DIR=/data/.engraphis" in dockerfile
+    assert "ENGRAPHIS_ENV_FILE=/data/.engraphis/config.env" in dockerfile
+    assert "COPY deploy ./deploy" in dockerfile
 
     assert 'if [ -z "${ENGRAPHIS_HOST:-}" ]; then' in entrypoint
     assert '[ -n "${RAILWAY_SERVICE_NAME:-}" ]' in entrypoint
     assert "ENGRAPHIS_HOST=\"::\"" in entrypoint
     assert "ENGRAPHIS_HOST=\"0.0.0.0\"" in entrypoint
     assert "chown -R engraphis:engraphis /data" in entrypoint
+    assert ".volume-ownership" in entrypoint
+    assert 'if [ -L "$ownership_marker" ]; then' in entrypoint
+    assert "refusing symlinked volume ownership marker" in entrypoint
+    assert 'if [ ! -e "$ownership_marker" ]; then' in entrypoint
+    assert 'elif [ ! -f "$ownership_marker" ]; then' in entrypoint
+    assert "refusing non-regular volume ownership marker" in entrypoint
+    assert 'config_file="${ENGRAPHIS_ENV_FILE:-}"' in entrypoint
+    assert "refusing symlinked trusted config file" in entrypoint
+    assert 'chmod 600 "$config_file"' in entrypoint
+    assert "chown -R engraphis:engraphis /data 2>/dev/null || true" not in entrypoint
     assert 'exec gosu engraphis "$@"' in entrypoint
 
 

tests/test_release_infrastructure.py

@@ -22,6 +22,11 @@ def test_published_image_and_railway_template_fail_safe_to_customer_mode():
     assert railway["$schema"] == "https://railway.com/railway.schema.json"
     assert template["format"] == "engraphis-railway-template-composer-source/v1"
     assert template["variables"]["ENGRAPHIS_SERVICE_MODE"]["value"] == "customer"
+    assert template["variables"]["ENGRAPHIS_HOST"]["value"] == "0.0.0.0"
+    assert (
+        template["variables"]["ENGRAPHIS_ENV_FILE"]["value"]
+        == "/data/.engraphis/config.env"
+    )
     assert template["service"]["healthcheck"] == "/api/ready"
     assert template["service"]["volume"]["mount_path"] == "/data"
     local_api = template["variables"]["ENGRAPHIS_API_TOKEN"]