Fix Railway volume permissions at runtime

Author: pRizz

docker-compose.railway.yml

@@ -0,0 +1,25 @@
+# opencode-cloud Railway Compose Template
+#
+# Use this file for Railway template import workflows.
+# The canonical docker-compose.yml remains local/quick-deploy focused and
+# includes six volumes that Railway template import does not support.
+
+services:
+  opencode:
+    image: prizz/opencode-cloud-sandbox:latest
+    pull_policy: ${OPENCODE_PULL_POLICY:-missing}
+    restart: unless-stopped
+    init: true
+    stop_grace_period: ${OPENCODE_STOP_GRACE_PERIOD:-30s}
+    environment:
+      OPENCODE_HOST: ${OPENCODE_HOST:-0.0.0.0}
+    logging:
+      driver: ${OPENCODE_LOG_DRIVER:-json-file}
+      options:
+        max-size: ${OPENCODE_LOG_MAX_SIZE:-10m}
+        max-file: "${OPENCODE_LOG_MAX_FILE:-3}"
+    volumes:
+      - opencode-data:/home/opencoder/.local/share/opencode
+
+volumes:
+  opencode-data:

docs/deploy/railway.md

@@ -21,6 +21,23 @@ Steps:
 > **Important:** After deploying, verify that a Railway Volume is attached.
 > Without a volume, all data is lost on every redeploy.
 
+## Template from Compose File (Manual Upload)
+
+If you are creating a Railway template by importing a Compose file, use
+`docker-compose.railway.yml` from this repository.
+
+Do **not** import the root `docker-compose.yml` for Railway templates. That
+file is local/quick-deploy oriented and declares six volumes.
+
+```bash
+curl -O https://raw.githubusercontent.com/pRizz/opencode-cloud/main/docker-compose.railway.yml
+```
+
+Railway template import supports one volume per service. The Railway-specific
+compose file keeps a single persisted mount at
+`/home/opencoder/.local/share/opencode` for compatibility.
+It keeps variable-driven runtime/logging knobs where Railway supports them and
+uses a fixed image reference to avoid Railway parser issues.
 ## Manual Deployment
 
 ### Prerequisites
@@ -155,13 +172,31 @@ the build logs.
 - Verify the image tag exists on Docker Hub
 - Check Railway deployment logs for errors
 
-### Volume permissions
+### `EACCES` creating `/home/opencoder/.local/share/opencode/bin`
+
+**Symptom:** Deploy logs repeatedly show:
+
+```text
+EACCES: permission denied, mkdir '/home/opencoder/.local/share/opencode/bin'
+```
+
+**Cause:** The Railway volume is mounted with root ownership, but the app runs
+as `opencoder`. If the mounted path is not writable by `opencoder`, startup
+fails.
+
+**Immediate workaround (Railway service settings):**
+1. Ensure `RAILWAY_RUN_UID=0` (or remove a conflicting non-root value).
+2. Set the service **Start Command** to:
+
+```bash
+/bin/sh -c 'install -d -m 0755 /home/opencoder/.local/share/opencode && chown -R opencoder:opencoder /home/opencoder/.local/share/opencode && exec /usr/local/bin/entrypoint.sh'
+```
+
+After redeploy, the `EACCES` lines should stop.
 
-Railway volumes require the container to run as root. The opencode-cloud
-image runs its entrypoint as root (which then drops privileges for the
-application), so this should work without additional configuration. If you
-encounter permission errors, ensure `RAILWAY_RUN_UID=0` is not explicitly
-set to a non-root value.
+**Long-term behavior:** Recent images auto-check this mount on startup and
+attempt to fix ownership before launching opencode. Keep the volume mounted at
+`/home/opencoder/.local/share/opencode`.
 
 ## Limitations
 

packages/core/src/docker/files/entrypoint.sh

@@ -579,6 +579,29 @@ EOF
         maybe_initialize_bootstrap_mode
     }
 
+    ensure_opencode_data_dir_writable() {
+        local data_dir="/home/opencoder/.local/share/opencode"
+
+        install -d -m 0755 "${data_dir}"
+
+        if runuser -u opencoder -- test -w "${data_dir}"; then
+            return
+        fi
+
+        log "Detected non-writable opencode data directory; attempting ownership fix: ${data_dir}"
+        if ! chown -R opencoder:opencoder "${data_dir}" 2>/dev/null; then
+            log "WARNING: Failed to change ownership for ${data_dir}; continuing with writability re-check."
+        fi
+
+        if runuser -u opencoder -- test -w "${data_dir}"; then
+            return
+        fi
+
+        log "ERROR: ${data_dir} is not writable by user 'opencoder'."
+        log "If running on Railway, set RAILWAY_RUN_UID=0 and attach a volume mounted at ${data_dir}."
+        exit 1
+    }
+
     load_builtin_home_users
     if ! ensure_jsonc_parser; then
         log "ERROR: JSONC parser is required for auth config checks."
@@ -589,6 +612,7 @@ EOF
     migrate_unmanaged_home_users_to_records
     sync_bootstrap_state
     warn_security_posture
+    ensure_opencode_data_dir_writable
 
     log "Starting opencode on ${OPENCODE_HOST}:${OPENCODE_PORT}"
     /usr/local/bin/opencode-broker &