diff --git a/docs/features/compose-doctor.mdx b/docs/features/compose-doctor.mdx index d05e90a7..75aab7cb 100644 --- a/docs/features/compose-doctor.mdx +++ b/docs/features/compose-doctor.mdx @@ -119,6 +119,8 @@ All 42 rules are listed below, organized by topic. | Host network mode | High | A service uses `network_mode: host`, bypassing Docker's network isolation and ignoring published-port mappings. | | Check UID/GID alignment | Warning | A service sets a UID or GID and mounts host paths that Sencho cannot inspect from inside its container. Mismatched ownership between the host path and the container user is a common source of permission errors. | +For guidance on which API groups a socket proxy needs for each Sencho feature, see [Self-Hosting: Docker socket proxy](/operations/self-hosting#docker-socket-proxy). + ### Reliability | Rule | Severity | What it detects | diff --git a/docs/features/remote-updates.mdx b/docs/features/remote-updates.mdx index 221b9d0a..0867bc3d 100644 --- a/docs/features/remote-updates.mdx +++ b/docs/features/remote-updates.mdx @@ -90,6 +90,10 @@ If the new container does not come up within 5 minutes, the overlay surfaces a * The self-update helper container inherits all bind mounts from the main Sencho container 1:1. If your `docker-compose.yml` references `env_file`, `configs`, or `secrets` outside the compose working directory, those host paths must be mounted into the Sencho container at the *same container path* as on the host. See [Troubleshooting](/operations/troubleshooting#local-self-update-fails-with-env-file-not-found) if you encounter `env file not found` errors during a local update. + + Self-update helpers always mount the host `/var/run/docker.sock` into the helper container, independent of `DOCKER_HOST`. On a TCP-only socket proxy, update and reapply helpers do not reach the proxy, so use a deployment where the helpers still receive a working host socket path. The generated Pilot Agent compose also mounts the raw socket path, so a TCP-only proxy on an agent node requires editing the generated compose. See [Self-Hosting: Docker socket proxy](/operations/self-hosting#self-update-behind-a-proxy). + + ## Pinned image tags diff --git a/docs/features/resources.mdx b/docs/features/resources.mdx index 84a16f24..ba60c540 100644 --- a/docs/features/resources.mdx +++ b/docs/features/resources.mdx @@ -58,6 +58,10 @@ A confirmation dialog appears before any destructive prune. Sencho first builds Quick Clean is admin-only. The panel is hidden for users without admin permissions. + + Every prune action on this page runs through the Docker API. When Sencho runs behind a Docker socket proxy, pruning requires POST plus the IMAGES, VOLUMES, NETWORKS, and CONTAINERS groups for the resources being cleaned. See [Self-Hosting: Docker socket proxy](/operations/self-hosting#docker-socket-proxy). + + ## Resource tabs Below the hero, three tabs partition your inventory: **Images**, **Volumes**, and **Unmanaged**. The Unmanaged tab shows a count badge whenever orphan containers are detected. diff --git a/docs/features/scheduled-operations.mdx b/docs/features/scheduled-operations.mdx index 6f1fab49..53163cb2 100644 --- a/docs/features/scheduled-operations.mdx +++ b/docs/features/scheduled-operations.mdx @@ -73,6 +73,10 @@ The All tasks toggle swaps the lane track for a sortable table. | **Stop Container** | A specific container by name on a specific node | Stops one container. The container remains on disk for a faster start later. | | **Start Container** | A specific container by name on a specific node | Starts one stopped container by name. | + + Every action in the table runs through the same Docker endpoint as the interactive flows. When Sencho runs behind a Docker socket proxy, scheduled operations inherit whatever API groups the proxy allows. See [Self-Hosting: Docker socket proxy](/operations/self-hosting#docker-socket-proxy). + + ## Creating a scheduled task Click **New Schedule** in the header. The form opens in a centered modal. The Action picker lists every supported operation, grouped by category: Lifecycle, Updates, Security, Upkeep, and Backups. diff --git a/docs/features/sencho-mesh.mdx b/docs/features/sencho-mesh.mdx index 7268b376..a0746936 100644 --- a/docs/features/sencho-mesh.mdx +++ b/docs/features/sencho-mesh.mdx @@ -38,6 +38,10 @@ The user-facing effect is `psql -h db.api.opsix.sencho` from a container on any - Functioning `sencho_mesh` data plane on every node that should participate. The Routing tab shows a red banner if a node's data plane did not come up; the troubleshooting section below covers each cause. - Per-stack opt-in. Enabling mesh on a node does not automatically place every stack into the mesh; each stack is opted in individually. + + Enabling the mesh creates and connects Docker networks on each participating node. When a node runs behind a Docker socket proxy, the proxy must allow the NETWORKS group (create, inspect, connect) and POST. See [Self-Hosting: Docker socket proxy](/operations/self-hosting#docker-socket-proxy). + + App-layer authentication is **not** in scope. Postgres still needs a password, Redis still needs an ACL, your internal HTTP API still needs whatever auth it normally uses. The mesh moves bytes; it does not authenticate the protocols inside those bytes. ## Enable the mesh diff --git a/docs/features/stack-file-explorer.mdx b/docs/features/stack-file-explorer.mdx index e8d27c9e..a0f476be 100644 --- a/docs/features/stack-file-explorer.mdx +++ b/docs/features/stack-file-explorer.mdx @@ -38,6 +38,10 @@ The same source mounted by more than one service is shown as a single root, summ Editing a config file does not restart the service that reads it. After you save, restart the relevant service so it picks up the new content. + + Browsing a named volume works by creating a short-lived helper container through the Docker API. When Sencho runs behind a Docker socket proxy, the proxy must allow CONTAINERS (create, attach, start, wait, remove) and POST for volume browsing to work. See [Self-Hosting: Docker socket proxy](/operations/self-hosting#docker-socket-proxy). + + ### When a volume cannot be browsed A volume root shows a short explanation in place of its tree and is not browsable when: diff --git a/docs/features/stack-management.mdx b/docs/features/stack-management.mdx index f288191a..48c9ddbb 100644 --- a/docs/features/stack-management.mdx +++ b/docs/features/stack-management.mdx @@ -9,6 +9,10 @@ A **stack** in Sencho is a Docker Compose project: a directory inside your `COMP Sencho sidebar showing the stack list grouped by label, with filter chips at the top + + Stack deploy, update, and down run `docker compose` through the same Docker endpoint as the rest of Sencho. When Sencho runs behind a Docker socket proxy, the proxy must allow POST and the CONTAINERS, IMAGES, NETWORKS, and VOLUMES groups for Compose operations to work. See [Self-Hosting: Docker socket proxy](/operations/self-hosting#docker-socket-proxy). + + ## Creating a stack Click **Create Stack** in the left sidebar to open the **New stack** dialog. Pick a source from the tabs at the top: diff --git a/docs/operations/self-hosting.mdx b/docs/operations/self-hosting.mdx index d6fedbfb..f406ccc5 100644 --- a/docs/operations/self-hosting.mdx +++ b/docs/operations/self-hosting.mdx @@ -57,6 +57,144 @@ If your environment requires stricter isolation, the Docker socket itself is the --- +## Docker socket proxy + +A Docker socket proxy sits between Sencho and the Docker Engine. Instead of mounting `/var/run/docker.sock` directly into the Sencho container, the deployment mounts a proxy socket in its place, or points Sencho at the proxy with `DOCKER_HOST`, and the proxy forwards only the Engine API groups its configuration allows. This reduces the blast radius of a compromised Sencho container: an attacker who gains control of Sencho can still call the Docker API, but only the groups the proxy permits. + +A socket proxy is defense-in-depth, not a security boundary. Docker API access remains highly privileged even through a proxy, and the full profile below is still root-equivalent in practice. Use the profiles as a starting point for sizing a proxy, not as a guarantee that a restrictive proxy makes Sencho low-risk. + +Sencho has no socket-proxy setting or UI. The proxy is configured entirely in the deployment compose file, in one of two ways: + +- Mount the proxy socket at `/var/run/docker.sock` so Sencho and the `docker` CLI reach the proxy through the default Docker endpoint +- Set `DOCKER_HOST` to the proxy address (for example `tcp://proxy:2375`) on the Sencho container so the SDK and the Compose CLI reach the proxy through the same endpoint + +The second option matters because Sencho talks to Docker through two paths, and both honor the same endpoint: + +| Path | Mechanism | Proxy-aware? | +|------|-----------|--------------| +| Inventory, stats, events, lifecycle, prune, interactive shell, mesh network operations | Dockerode SDK over the default Docker endpoint | Yes | +| Stack deploy, update, down, pull, compose logs and config | `docker compose` CLI, inherits the container environment | Yes | +| Volume browser helper containers | Dockerode create, attach, start, wait, remove | Yes | +| Self-update and reapply helpers | Helper container mounts `/var/run/docker.sock` directly | Host Unix socket only | + +The last row is the exception to everything above. See [Self-update behind a proxy](#self-update-behind-a-proxy). + +The profiles below use `tecnativa/docker-socket-proxy` style flags as a worked example. Other proxies (for example `linuxserver/socket-proxy`) expose similar API-group flags, and the exact lifecycle allow flags vary by implementation, so check the flag names against the proxy image and version you run. Profile values are the literal strings `1` and `0`. + +Compose Doctor classifies socket-proxy topologies in-app and flags risky configurations such as a proxy that allows mutating API access, publishes a host port, or joins a non-internal network. See [Compose Doctor](/features/compose-doctor). + +### Monitoring / read-only profile + +```env +CONTAINERS=1 +IMAGES=1 +NETWORKS=1 +VOLUMES=1 +INFO=1 +SYSTEM=1 +EVENTS=1 +PING=1 +VERSION=1 +POST=0 +EXEC=0 +BUILD=0 +SESSION=0 +``` + +This profile supports dashboards, inventory, topology, logs, stats, Docker events, disk usage, prune previews, and read-only health and update evidence. + +It does **not** support container start, stop, or restart, Compose deploy, update, or down, prune execution, volume-browser helper containers, the interactive shell, mesh network setup, auto-heal restarts, or self-update. + +### Minimum management profile + +```env +CONTAINERS=1 +IMAGES=1 +NETWORKS=1 +VOLUMES=1 +INFO=1 +SYSTEM=1 +EVENTS=1 +PING=1 +VERSION=1 +POST=1 +ALLOW_START=1 +ALLOW_STOP=1 +ALLOW_RESTARTS=1 +EXEC=0 +BUILD=0 +SESSION=0 +``` + +This profile adds everything in the monitoring profile plus image-backed Compose management, container start, stop, and restart, auto-heal restarts, pruning, mesh setup, and volume-browser helper containers. + +It still does **not** support the interactive shell, build-backed stacks, or reliable self-update on a TCP-only proxy. + +### Full functionality profile + +```env +CONTAINERS=1 +IMAGES=1 +NETWORKS=1 +VOLUMES=1 +INFO=1 +SYSTEM=1 +EVENTS=1 +PING=1 +VERSION=1 +POST=1 +ALLOW_START=1 +ALLOW_STOP=1 +ALLOW_RESTARTS=1 +EXEC=1 +BUILD=1 +SESSION=1 +GRPC=1 +``` + +This profile supports the full Sencho surface: the interactive shell, build-backed stacks, helper containers, cleanup actions, and self-update where a usable host Docker socket path is available to helpers (see the caveat below). + +### Keep these disabled + +Sencho does not use these API groups today. Keep them disabled unless a future feature adds a direct dependency: + +```env +AUTH=0 +CONFIGS=0 +SECRETS=0 +SWARM=0 +SERVICES=0 +TASKS=0 +NODES=0 +PLUGINS=0 +COMMIT=0 +DISTRIBUTION=0 +``` + +### Feature-to-API reference + +| Capability | What the proxy must allow | +|------------|---------------------------| +| Dashboard inventory, topology, logs, stats | CONTAINERS (list, inspect, logs, stats), IMAGES, NETWORKS, VOLUMES, INFO, SYSTEM (disk usage), EVENTS, PING, VERSION | +| Container start, stop, restart, auto-heal | CONTAINERS plus POST plus the lifecycle allow flags | +| Compose deploy, update, down, pull | POST plus the CONTAINERS, IMAGES, NETWORKS, and VOLUMES groups the Compose Engine uses through the same endpoint | +| Build-backed stacks | BUILD plus SESSION and GRPC as the BuildKit path requires | +| Interactive shell | EXEC plus CONTAINERS | +| Volume browser | CONTAINERS create, attach, start, wait, remove, IMAGES (helper image), POST; no EXEC | +| Mesh network setup | NETWORKS create, inspect, connect plus POST | +| Image update checks | IMAGES inspect plus CONTAINERS inspect | +| Prune execution | IMAGES, VOLUMES, NETWORKS, CONTAINERS prune or remove plus POST | +| Vulnerability scanning (local images) | IMAGES list and inspect (Sencho enumerates local images through the API; Trivy runs as a host binary) | +| Self-update and reapply | Helper mounts the host `/var/run/docker.sock`; a TCP-only `DOCKER_HOST` does not substitute | + +### Self-update behind a proxy + +Self-update and reapply helpers hardcode the host Unix socket mount into the helper container (`-v /var/run/docker.sock:/var/run/docker.sock`). They do not inherit `DOCKER_HOST`, so in a TCP-only proxy setup the day-to-day Dockerode and Compose traffic works but the update and reapply helpers will not reach the proxy. + +If the deployment is behind a TCP-only proxy, use the fleet update or manual upgrade paths that fit the topology, or make sure the helpers still receive a working host socket path. The generated Pilot Agent compose also mounts the raw socket path, so a TCP-only proxy on an agent node requires editing the generated compose. + +--- + ## Resource recommendations | Resource | Minimum | Recommended | Notes | diff --git a/docs/reference/security.mdx b/docs/reference/security.mdx index 7e8c6037..d0713267 100644 --- a/docs/reference/security.mdx +++ b/docs/reference/security.mdx @@ -285,13 +285,14 @@ For copy-paste verification commands, see [Verifying Images](/operations/verifyi 1. **Place Sencho behind a TLS reverse proxy** (nginx, Traefik, Caddy) so that session cookies are transmitted over HTTPS only. See [Self-Hosting](/operations/self-hosting). -2. **Enable at least one SSO provider** to centralize identity management and reduce password sprawl. See [SSO & LDAP Authentication](/features/sso). -3. **Enroll all admin accounts in 2FA** to protect against credential theft. See [Two-Factor Authentication](/features/two-factor-authentication). -4. **Use scoped API tokens** instead of sharing admin credentials with CI/CD pipelines. See [API Tokens](/features/api-tokens). -5. **Set `FRONTEND_URL`** to restrict CORS to your domain. See [Configuration](/getting-started/configuration). -6. **Verify Docker image signatures** before deploying to confirm the image has not been tampered with. See [Verifying Images](/operations/verifying-images). -7. **Review the audit log regularly** or assign a dedicated Auditor-role user for ongoing compliance monitoring. See [Audit Log](/features/audit-log). -8. **Keep Sencho updated** to receive security patches and dependency upgrades. See [Upgrade](/operations/upgrade). +2. **Configure the Docker socket proxy** with the minimum API groups the Sencho features you use require, keeping mutating and build groups disabled where possible. See [Self-Hosting: Docker socket proxy](/operations/self-hosting#docker-socket-proxy). +3. **Enable at least one SSO provider** to centralize identity management and reduce password sprawl. See [SSO & LDAP Authentication](/features/sso). +4. **Enroll all admin accounts in 2FA** to protect against credential theft. See [Two-Factor Authentication](/features/two-factor-authentication). +5. **Use scoped API tokens** instead of sharing admin credentials with CI/CD pipelines. See [API Tokens](/features/api-tokens). +6. **Set `FRONTEND_URL`** to restrict CORS to your domain. See [Configuration](/getting-started/configuration). +7. **Verify Docker image signatures** before deploying to confirm the image has not been tampered with. See [Verifying Images](/operations/verifying-images). +8. **Review the audit log regularly** or assign a dedicated Auditor-role user for ongoing compliance monitoring. See [Audit Log](/features/audit-log). +9. **Keep Sencho updated** to receive security patches and dependency upgrades. See [Upgrade](/operations/upgrade). ## Reporting a vulnerability