@or3/cloud 0.1.15 → 0.1.34

package/README.md

@@ -0,0 +1,85 @@
+# OR3 Cloud
+
+Install and operate a supported OR3 container deployment without cloning the
+application repository or installing its dependencies on the host.
+
+## Quick start: local machine
+
+You need Docker Engine with Docker Compose v2 and Node.js 20 or later.
+
+```sh
+npx @or3/cloud init --local
+```
+
+The installer asks for the owner email, generates a bootstrap password, and
+saves both values in the mode-`0600`
+`or3-cloud/.or3-initial-credentials` file. It does not print the password.
+Save the file in a password manager, then delete it. Open
+[http://127.0.0.1:3000](http://127.0.0.1:3000) and sign in.
+
+The published Cloud image supports `linux/amd64` and `linux/arm64` and uses
+Basic Auth + SQLite + filesystem storage. The CLI checks the image manifest
+before it writes deployment state.
+
+## Run it publicly on a VPS
+
+Before starting, point a domain at the VPS and allow inbound TCP ports `80`
+and `443` in its firewall. Then run:
+
+```sh
+npx @or3/cloud init --public --domain cloud.example.com
+```
+
+OR3 Cloud uses Caddy to obtain and renew HTTPS certificates. It does not
+change your DNS, firewall, Cloudflare, or Tailscale settings.
+
+## Day-to-day commands
+
+Run these from the deployment directory created by `init`:
+
+```sh
+npx @or3/cloud doctor
+npx @or3/cloud backup
+npx @or3/cloud update
+npx @or3/cloud rollback --yes
+npx @or3/cloud recover
+npx @or3/cloud status
+npx @or3/cloud logs --tail 200
+npx @or3/cloud start
+npx @or3/cloud stop
+npx @or3/cloud restart
+```
+
+Do not run `docker compose down --volumes` on a normal deployment: it deletes
+the application data. Use `backup` before an update or any destructive action.
+For a destructive purge, export a fresh backup to a new directory on another
+filesystem first; `remove --purge-data --yes` verifies that export before it
+will delete anything.
+
+Managed registration is invite-only: the bootstrap owner signs in first and
+invites additional users from the in-product admin flow. Guest access and
+anonymous registration stay disabled. Uploading/installing custom plugins or
+themes is disabled in the immutable image because it cannot rebuild trusted
+source; bundled extensions remain available.
+
+Remote OR3 Connect is withheld from the managed Cloud release until its
+Cloudflare/domain staging flow is proved. Local Intern is independently
+supported through the coordinated published release:
+
+```sh
+npx @or3/connect@0.1.3 intern
+```
+
+See the [Connect release status](https://github.com/Saluana/or3-intern/blob/main/docs/connect-release-status.md).
+Do not substitute a bare package command or paste a generic remote URL/token as
+a workaround. The [Start Here guide](https://github.com/Saluana/or3-chat/blob/main/docs/start-here.md)
+routes each supported setup path.
+
+## More help
+
+```sh
+npx @or3/cloud --help
+```
+
+For VPS requirements, firewall guidance, updates, restores, and migration,
+read the [installation guide](https://github.com/Saluana/or3-chat/blob/main/docs/installation.md).

package/assets/Caddyfile

@@ -1,7 +1,18 @@
 {$OR3_PUBLIC_DOMAIN} {
-	encode zstd gzip
-	reverse_proxy or3:3000 {
-		# Preserve incremental SSE/chat output instead of buffering it at the proxy.
-		flush_interval -1
+	# Security headers. Caddy 308-redirects plain HTTP to HTTPS before this
+	# site handler runs, so Strict-Transport-Security is only ever emitted on
+	# HTTPS responses (it is meaningless on plain HTTP).
+	header {
+		Strict-Transport-Security "max-age=31536000; includeSubDomains"
+		X-Content-Type-Options "nosniff"
+		X-Frame-Options "DENY"
+		Referrer-Policy "strict-origin-when-cross-origin"
+		Permissions-Policy "camera=(), microphone=(), geolocation=()"
 	}
+
+	encode zstd gzip
+	# Caddy recognizes text/event-stream and flushes it immediately. Keeping the
+	# default stream behavior also lets client disconnects cancel foreground
+	# provider requests instead of leaving a paid generation running.
+	reverse_proxy or3:3000
 }

package/assets/compose.public.yaml

@@ -1,8 +1,13 @@
 services:
   caddy:
-    image: caddy:2.10-alpine
+    # Pinned to the exact patch release and image digest so a floating tag
+    # cannot silently change proxy behavior or the base image.
+    image: caddy:2.10.2-alpine@sha256:4c6e91c6ed0e2fa03efd5b44747b625fec79bc9cd06ac5235a779726618e530d
     depends_on:
       or3:
+        # This gates Caddy's initial startup only. A later unhealthy OR3
+        # healthcheck does not trigger automatic container restarts; use the
+        # Cloud CLI's doctor/status/restart flow for persistent degradation.
         condition: service_healthy
     environment:
       OR3_PUBLIC_DOMAIN: ${OR3_PUBLIC_DOMAIN}
@@ -15,6 +20,26 @@ services:
       - caddy-data:/data
       - caddy-config:/config
     restart: unless-stopped
+    # Container hardening. The official image runs as root (no caddy user) and
+    # /data + /config are root-owned, so the process stays root but all
+    # capabilities are dropped except NET_BIND_SERVICE, which is required to
+    # bind the privileged ports 80/443. The root filesystem is read-only;
+    # certificates/state live on the caddy-data/caddy-config volumes and
+    # scratch space is a small noexec tmpfs at /tmp.
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE
+    read_only: true
+    tmpfs:
+      - /tmp:size=64m,noexec,nosuid
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
 
 volumes:
   caddy-data:

package/assets/compose.yaml

@@ -18,12 +18,43 @@ services:
     volumes:
       - or3-data:/data
     restart: unless-stopped
+    # Leave enough time for Nuxt to close SSE responses and upstream provider
+    # connections before Docker sends SIGKILL.
+    stop_grace_period: 25s
+    # Container hardening: the runtime image already runs as a non-root user and
+    # listens on port 3000 (no privileged ports), so all capabilities are
+    # dropped and the root filesystem is read-only. Persistent state lives on
+    # the or3-data volume (/data: SQLite, storage, admin data, extensions);
+    # scratch space (SQLite WAL, H3 multipart uploads, Nuxt server caches)
+    # is a 256m tmpfs at /tmp. Phase-5 smokes must re-verify uploads and
+    # plugin installs against this read-only profile.
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    read_only: true
+    tmpfs:
+      - /tmp:size=256m
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
     healthcheck:
+      # Deep health, mirroring the CLI's HEALTH_SCRIPT: exit non-zero unless
+      # the response is HTTP ok AND the parsed body status is exactly 'ok'.
+      # A degraded provider (e.g. sync/storage/auth down) reports HTTP 200
+      # with status 'degraded' and is therefore marked unhealthy. Docker
+      # Compose uses that state for startup dependencies and `or3 status`
+      # reports it, but Docker does not restart a running container solely
+      # because a healthcheck fails; `restart: unless-stopped` covers process
+      # exits only. Operators should run `or3 doctor`/`or3 restart` for a
+      # persistent degraded state.
       test:
         - CMD
-        - node
+        - /nodejs/bin/node
         - -e
-        - "fetch('http://127.0.0.1:3000/api/health').then(r=>{if(!r.ok)process.exit(1)}).catch(()=>process.exit(1))"
+        - "fetch('http://127.0.0.1:3000/api/health?deep=true').then(async r=>{const b=await r.json().catch(()=>({}));if(!r.ok||b.status!=='ok')process.exit(1)}).catch(()=>process.exit(1))"
       interval: 10s
       timeout: 5s
       retries: 12