gsadmin/sencho
1
0
Fork 0
mirror of https://github.com/Studio-Saelix/sencho.git synced 2026-08-09 02:12:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(self-hosting): document Docker socket proxy permission profiles (#1798)

Browse Source 
Adds a "Docker socket proxy" section to self-hosting that maps Sencho
features to the Docker Engine API groups a proxy must allow. Three
profiles (monitoring / minimum management / full) with literal flag
values, a feature-to-API reference table, a keep-disabled list, and the
self-update caveat: helpers always mount the host Unix socket, so a
TCP-only proxy does not carry update traffic.

Also adds a production-hardening checklist item pointing at the section,
cross-links from the feature pages whose behavior depends on mutating
Docker access (mesh, file explorer, resources, remote updates, stack
management, scheduled operations), and a pointer from Compose Doctor's
proxy findings to the sizing guidance.

Closes #1796
This commit is contained in:
Anso
2026-08-08 03:17:56 -04:00
committed by GitHub
parent de7ecee497
commit cc2d215b2d
9 changed files with 172 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/compose-doctor.mdx
+2
View File
@@ -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 |
docs/features/remote-updates.mdx
+4
View File
@@ -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.
</Note>
<Note>
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).
</Note>
## Pinned image tags
docs/features/resources.mdx
+4
View File
@@ -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.
</Note>
<Note>
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).
</Note>
## 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.
docs/features/scheduled-operations.mdx
+4
View File
@@ -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. |
<Note>
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).
</Note>
## 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.
docs/features/sencho-mesh.mdx
+4
View File
@@ -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.
<Note>
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).
</Note>
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
docs/features/stack-file-explorer.mdx
+4
View File
@@ -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.
</Note>
<Note>
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).
</Note>
### When a volume cannot be browsed
A volume root shows a short explanation in place of its tree and is not browsable when:
docs/features/stack-management.mdx
+4
View File
@@ -9,6 +9,10 @@ A **stack** in Sencho is a Docker Compose project: a directory inside your `COMP
<img src="/images/stack-management/sidebar-grouped.png" alt="Sencho sidebar showing the stack list grouped by label, with filter chips at the top" />
</Frame>
<Note>
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).
</Note>
## 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:
docs/operations/self-hosting.mdx
+138
View File
@@ -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 |
docs/reference/security.mdx
+8 -7
View File
@@ -285,13 +285,14 @@ For copy-paste verification commands, see [Verifying Images](/operations/verifyi
</Note>
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