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,191 @@ 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
+    # Validate every existing component without resolving through a symlink. The trusted
+    # config path is operator-configured and may be outside /data, so checking only its
+    # leaf or final parent would let an app-writable intermediate directory redirect root's
+    # chmod/chown into the image. Reject dot-dot paths rather than guessing their target.
+    reject_linked_path() {
+        path=$1
+        case "$path" in
+            /*) ;;
+            *) return 1 ;;
+        esac
+        remainder=${path#/}
+        current=
+        while [ -n "$remainder" ]; do
+            case "$remainder" in
+                */*)
+                    component=${remainder%%/*}
+                    remainder=${remainder#*/}
+                    ;;
+                *)
+                    component=$remainder
+                    remainder=
+                    ;;
+            esac
+            case "$component" in
+                ""|.) continue ;;
+                ..) return 1 ;;
+            esac
+            if [ -n "$current" ]; then
+                current="$current/$component"
+            else
+                current="/$component"
+            fi
+            if [ -L "$current" ]; then
+                return 1
+            fi
+        done
+        return 0
+    }
+
+    state_directory_is_owned() {
+        # Only /data is an ownership-repair target. External state paths must be
+        # provisioned for the app beforehand, including on the first boot.
+        case "$1" in
+            /data|/data/*) return 0 ;;
+        esac
+        [ -d "$1" ] && [ "$(stat -c '%u' "$1" 2>/dev/null)" = "$2" ]
+    }
+
+    # 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}"
+    # Keep the marker on the volume it describes; external state may outlive a
+    # replaced /data volume that still needs its first ownership repair.
+    ownership_marker="/data/.volume-ownership"
+    config_file="${ENGRAPHIS_ENV_FILE:-}"
+    app_owner=$(id -u engraphis)
+    if ! reject_linked_path "$state_dir"; then
+        printf '%s\n' "[engraphis] refusing linked or unnormalized state path: $state_dir" >&2
+        exit 1
+    fi
+    # The state directory is app-writable after first boot. Reject a planted link or
+    # non-directory before mkdir/chown can follow it into a root-owned image path.
+    if [ -L "$state_dir" ]; then
+        printf '%s\n' "[engraphis] refusing symlinked state directory: $state_dir" >&2
+        exit 1
+    elif [ -e "$state_dir" ] && [ ! -d "$state_dir" ]; then
+        printf '%s\n' "[engraphis] refusing non-directory state path: $state_dir" >&2
+        exit 1
+    fi
+    if ! state_directory_is_owned "$state_dir" "$app_owner"; then
+        printf '%s\n' "[engraphis] external state directory must already be owned by engraphis: $state_dir" >&2
+        exit 1
+    fi
+    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
+        if ! reject_linked_path "$config_file"; then
+            printf '%s\n' "[engraphis] refusing linked or unnormalized trusted config path: $config_file" >&2
+            exit 1
+        fi
+        config_parent=$(dirname "$config_file")
+        if [ -L "$config_parent" ]; then
+            printf '%s\n' "[engraphis] refusing symlinked trusted config directory: $config_parent" >&2
+            exit 1
+        fi
+        config_parent_created=0
+        if [ ! -e "$config_parent" ]; then
+            config_parent_created=1
+        elif [ ! -d "$config_parent" ]; then
+            printf '%s\n' "[engraphis] refusing non-directory trusted config parent: $config_parent" >&2
+            exit 1
+        fi
+        if ! mkdir -p "$config_parent"; then
+            printf '%s\n' "[engraphis] unable to create config directory: $config_parent" >&2
+            exit 1
+        fi
+        if [ "$config_parent_created" = "1" ]; then
+            if ! reject_linked_path "$config_parent" || [ ! -d "$config_parent" ]; then
+                printf '%s\n' "[engraphis] refusing changed trusted config directory: $config_parent" >&2
+                exit 1
+            fi
+            if ! chown engraphis:engraphis "$config_parent"; then
+                printf '%s\n' "[engraphis] unable to own trusted config directory" >&2
+                exit 1
+            fi
+        fi
+        # Check external existing parents before creating or changing any file.
+        # Parents under /data receive the volume's first-boot ownership repair.
+        case "$config_parent" in
+            /data|/data/*) ;;
+            *)
+                config_owner=$(stat -c '%u' "$config_parent" 2>/dev/null || true)
+                if [ "$config_owner" != "$app_owner" ]; then
+                    printf '%s\n' "[engraphis] trusted config directory must be owned by engraphis: $config_parent" >&2
+                    exit 1
+                fi
+                ;;
+        esac
+        if ! reject_linked_path "$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 ! reject_linked_path "$config_file" || [ ! -f "$config_file" ]; then
+            printf '%s\n' "[engraphis] refusing changed or non-regular 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" ] || ! reject_linked_path "$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" ]; then
+        # A pre-existing config directory may be a separate root-owned mount. Do not
+        # chown an arbitrary existing host path; fail closed if it is unusable instead
+        # of starting a dashboard whose settings silently cannot persist.
+        config_owner=$(stat -c '%u' "$config_parent" 2>/dev/null || true)
+        if [ -z "$config_owner" ] || [ "$config_owner" != "$app_owner" ]; then
+            printf '%s\n' "[engraphis] trusted config directory must be owned by engraphis: $config_parent" >&2
+            exit 1
+        fi
+    fi
+    if [ -n "$config_file" ]; then
+        if ! reject_linked_path "$config_file" || [ ! -f "$config_file" ]; then
+            printf '%s\n' "[engraphis] refusing changed trusted config file: $config_file" >&2
+            exit 1
+        fi
+        if ! chown engraphis:engraphis "$config_file"; then
+            printf '%s\n' "[engraphis] unable to own trusted config file" >&2
+            exit 1
+        fi
+    fi
     exec gosu engraphis "$@"
 fi
 

docs/DOCKER.md

@@ -25,6 +25,13 @@ ENGRAPHIS_COMPOSE_PORT=8787
 
 Then open `http://127.0.0.1:8787`. License issuance, trials, leases, and revocations remain on the private control plane.
 
+The root entrypoint repairs ownership only for the managed `/data` volume. When a custom
+container configuration places `ENGRAPHIS_STATE_DIR` outside `/data`, create that directory
+with the container's `engraphis` UID as owner before startup. Existing external config parent
+directories must also belong to that UID; startup rejects other owners before changing files.
+The repair marker lives at `/data/.volume-ownership`, so reusing external state cannot skip
+the repair of a replaced or restored data volume.
+
 > Port precedence: the dashboard binds `$PORT` when the platform injects one, falling back
 > to `ENGRAPHIS_PORT` (then `8700`). Compose sets both from `ENGRAPHIS_COMPOSE_PORT` so the
 > published host port and the in-container bind stay in sync; a stray desktop `ENGRAPHIS_PORT`

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_container_entrypoint.py

@@ -0,0 +1,93 @@
+"""Exercise the actual POSIX path validator without running privileged startup."""
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+
+
+pytestmark = pytest.mark.skipif(os.name == "nt" or not shutil.which("sh"),
+                                reason="POSIX path and symlink semantics required")
+
+
+def _validate(path: str) -> int:
+    entrypoint = (Path(__file__).resolve().parents[1] / "docker-entrypoint.sh").read_text()
+    body = entrypoint.split("    reject_linked_path() {", 1)[1].split("\n    }", 1)[0]
+    script = 'reject_linked_path() {' + body + '\n}\nreject_linked_path "$1"\n'
+    return subprocess.run(["sh", "-c", script, "validator", path], check=False).returncode
+
+
+@pytest.mark.parametrize("path", ["relative/config.env", "../config.env", "/tmp/../etc/config.env"])
+def test_root_path_validation_rejects_relative_and_parent_traversal(path):
+    assert _validate(path) != 0
+
+
+def test_root_path_validation_checks_intermediate_symlinks_before_dot_segments(tmp_path):
+    target = tmp_path / "target"
+    target.mkdir()
+    (target / "nested").mkdir()
+    link = tmp_path / "link"
+    link.symlink_to(target, target_is_directory=True)
+    assert _validate(str(link / "nested" / "config.env")) != 0
+    assert _validate(str(link) + "/../config.env") != 0
+    assert _validate(str(target / "nested" / "config.env")) == 0
+    assert _validate(str(tmp_path / "new" / "config.env")) == 0
+
+
+def test_external_state_requires_an_existing_app_owned_directory(tmp_path):
+    entrypoint = (Path(__file__).resolve().parents[1] / "docker-entrypoint.sh").read_text()
+    body = entrypoint.split("    state_directory_is_owned() {", 1)[1].split("\n    }", 1)[0]
+    script = 'state_directory_is_owned() {' + body + '\n}\nstate_directory_is_owned "$1" "$2"\n'
+    owner = tmp_path.stat().st_uid
+
+    def check(path, uid):
+        return subprocess.run(["sh", "-c", script, "validator", str(path), str(uid)],
+                              check=False).returncode
+
+    assert check(tmp_path, owner) == 0
+    assert check(tmp_path, owner + 1) != 0
+    assert check(tmp_path / "missing", owner) != 0
+    assert check("/data/new-state", owner) == 0
+
+
+def test_external_state_marker_cannot_skip_repair_of_a_replaced_volume(tmp_path):
+    managed = tmp_path / "data"
+    external = tmp_path / "external-state"
+    binaries = tmp_path / "bin"
+    for directory in (managed, external, binaries):
+        directory.mkdir()
+    legacy_marker = external / ".volume-ownership"
+    legacy_marker.write_text("older external volume")
+    log = tmp_path / "chown.log"
+    shims = {
+        "id": 'case "$*" in "-u engraphis") printf "%s\\n" "$APP_UID";; *) echo 0;; esac\n',
+        "chown": 'printf "%s\\n" "$*" >> "$CHOWN_LOG"\n',
+        "gosu": 'shift\nexec "$@"\n',
+    }
+    for name, body in shims.items():
+        executable = binaries / name
+        executable.write_text("#!/bin/sh\n" + body)
+        executable.chmod(0o755)
+    entrypoint = (Path(__file__).resolve().parents[1] / "docker-entrypoint.sh").read_text()
+    # Remap only the managed volume in this unprivileged startup exercise.
+    entrypoint = entrypoint.replace('ownership_marker="/data/.volume-ownership"',
+                                    'ownership_marker="$MANAGED_VOLUME/.volume-ownership"')
+    entrypoint = entrypoint.replace('chown -R engraphis:engraphis /data',
+                                    'chown -R engraphis:engraphis "$MANAGED_VOLUME"')
+    entrypoint = entrypoint.replace('chown engraphis:engraphis /data',
+                                    'chown engraphis:engraphis "$MANAGED_VOLUME"')
+    script = tmp_path / "entrypoint.sh"
+    script.write_text(entrypoint)
+    env = {**os.environ, "PATH": str(binaries) + os.pathsep + os.environ["PATH"],
+           "APP_UID": str(external.stat().st_uid), "CHOWN_LOG": str(log),
+           "MANAGED_VOLUME": str(managed), "ENGRAPHIS_STATE_DIR": str(external),
+           "ENGRAPHIS_ENV_FILE": ""}
+    subprocess.run(["sh", str(script), "true"], env=env, check=True)
+    assert f"-R engraphis:engraphis {managed}" in log.read_text().splitlines()
+    assert (managed / ".volume-ownership").is_file()
+    assert legacy_marker.read_text() == "older external volume"
+
+    log.write_text("")
+    subprocess.run(["sh", str(script), "true"], env=env, check=True)
+    assert not any(line.startswith("-R ") for line in log.read_text().splitlines())