Modernize docker compose defaults and override knobs

Author: pRizz

.env.example

@@ -0,0 +1,26 @@
+# opencode-cloud Docker Compose overrides
+#
+# Copy to .env in this directory to customize runtime defaults.
+
+# Container image to run.
+# Production recommendation: pin to an explicit tag (for example 15.2.0).
+OPENCODE_IMAGE=prizz/opencode-cloud-sandbox:latest
+
+# Image pull behavior for docker compose.
+# Common values: missing (default), always.
+OPENCODE_PULL_POLICY=missing
+
+# Host:container port mapping.
+# Local-safe default binds localhost only; use 3000:3000 for public exposure.
+OPENCODE_PORT_MAPPING=127.0.0.1:3000:3000
+
+# Hostname passed to opencode web in the container.
+OPENCODE_HOST=0.0.0.0
+
+# Graceful shutdown window before Docker sends SIGKILL.
+OPENCODE_STOP_GRACE_PERIOD=30s
+
+# Container log settings (json-file driver with rotation by default).
+OPENCODE_LOG_DRIVER=json-file
+OPENCODE_LOG_MAX_SIZE=10m
+OPENCODE_LOG_MAX_FILE=3

README.md

@@ -97,6 +97,22 @@ docker compose up -d
 
 This uses the included `docker-compose.yml` which configures all persistent volumes automatically.
 
+Optional `.env` overrides (same directory as `docker-compose.yml`):
+
+```bash
+# Example: expose publicly and pin a reproducible image tag
+cat > .env <<'EOF'
+OPENCODE_PORT_MAPPING=3000:3000
+OPENCODE_IMAGE=prizz/opencode-cloud-sandbox:15.2.0
+EOF
+```
+
+By default, Compose uses `OPENCODE_PULL_POLICY=missing`. To force-refresh to newer image layers:
+
+```bash
+docker compose pull && docker compose up -d
+```
+
 Retrieve the Initial One-Time Password (IOTP) and open `http://localhost:3000`:
 
 ```bash

docker-compose.yml

@@ -14,13 +14,21 @@
 
 services:
   opencode:
-    image: prizz/opencode-cloud-sandbox:latest
+    image: ${OPENCODE_IMAGE:-prizz/opencode-cloud-sandbox:latest}
+    pull_policy: ${OPENCODE_PULL_POLICY:-missing}
     container_name: opencode-cloud-sandbox
     restart: unless-stopped
+    init: true
+    stop_grace_period: ${OPENCODE_STOP_GRACE_PERIOD:-30s}
     ports:
-      - "127.0.0.1:3000:3000"
+      - "${OPENCODE_PORT_MAPPING:-127.0.0.1:3000:3000}"
     environment:
-      - OPENCODE_HOST=0.0.0.0
+      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
       - opencode-state:/home/opencoder/.local/state/opencode

docs/deploy/digitalocean-droplet.md

@@ -289,11 +289,12 @@ for the default `opencoder` account or use username/password fallback.
 
 #### 6) Expose publicly (optional)
 
-Edit `docker-compose.yml` and change the port binding:
+Set a Compose override so the service binds on all interfaces:
 
-```yaml
-ports:
-  - "3000:3000"  # was "127.0.0.1:3000:3000"
+```bash
+cat > .env <<'EOF'
+OPENCODE_PORT_MAPPING=3000:3000
+EOF
 ```
 
 Then restart:

docs/deploy/docker-desktop.md

@@ -38,6 +38,10 @@ volumes automatically.
 # Clone or download docker-compose.yml from the repository root
 curl -O https://raw.githubusercontent.com/pRizz/opencode-cloud/main/docker-compose.yml
 
+# Optional: copy defaults and customize Compose knobs
+curl -O https://raw.githubusercontent.com/pRizz/opencode-cloud/main/.env.example
+cp .env.example .env
+
 # Start the service
 docker compose up -d
 ```
@@ -168,19 +172,26 @@ Docker Desktop), Docker creates anonymous volumes automatically. This protects
 against accidental data loss on container restarts, but anonymous volumes are
 deleted when the container is removed.
 
-## Environment Variables
+## Environment Variables (`.env` for Docker Compose)
 
 | Variable | Default | Notes |
 |----------|---------|-------|
-| `OPENCODE_HOST` | `0.0.0.0` | Must be `0.0.0.0` for Docker Desktop port forwarding to work |
-| `OPENCODE_PORT` | `3000` | Container port for the web UI |
+| `OPENCODE_IMAGE` | `prizz/opencode-cloud-sandbox:latest` | Set a pinned tag (for example `15.2.0`) for reproducible deploys |
+| `OPENCODE_PULL_POLICY` | `missing` | Compose pull behavior. `missing` does not re-pull when image already exists; use `always` to check registry on each `up` |
+| `OPENCODE_PORT_MAPPING` | `127.0.0.1:3000:3000` | Host:container port mapping. Use `3000:3000` to expose publicly |
+| `OPENCODE_HOST` | `0.0.0.0` | Hostname passed to opencode inside the container |
+| `OPENCODE_STOP_GRACE_PERIOD` | `30s` | Grace period before force kill on shutdown |
+| `OPENCODE_LOG_DRIVER` | `json-file` | Docker log driver used for container logs |
+| `OPENCODE_LOG_MAX_SIZE` | `10m` | Maximum size for each rotated log file |
+| `OPENCODE_LOG_MAX_FILE` | `3` | Number of rotated log files to retain |
 
 ## Updating
 
 To update to a newer image version:
 
 ```bash
 # Docker Compose
+# default pull policy is "missing"
 docker compose pull
 docker compose up -d
 
@@ -200,7 +211,14 @@ Named volumes persist across this process. Your data is preserved.
 Another service is using port 3000. Change the host port:
 
 ```bash
-# Docker Compose: edit docker-compose.yml, change "127.0.0.1:3000:3000" to "127.0.0.1:8080:3000"
+# One-off override
+OPENCODE_PORT_MAPPING=127.0.0.1:8080:3000 docker compose up -d
+
+# Persistent override
+cp .env.example .env
+echo "OPENCODE_PORT_MAPPING=127.0.0.1:8080:3000" >> .env
+docker compose up -d
+
 # Docker CLI: use -p 127.0.0.1:8080:3000
 ```