mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-05 08:27:42 +00:00
Anso
c4e2595ded
* docs: remove security-sensitive implementation details from public documentation Generalize or remove internal architecture details that could aid targeted attacks — CVE tables, database schema, rate limit thresholds, proxy internals, encryption algorithm names, and WebSocket middleware bypass info. * test(metrics): fix flaky minute-bucket aggregation test Floor baseTime to the start of the current minute so baseTime + 5000 never crosses a minute boundary and produces 2 buckets instead of 1.
97 lines
4.2 KiB
Plaintext
97 lines
4.2 KiB
Plaintext
---
|
|
title: Self-Hosting Best Practices
|
|
description: Volume mounts, Docker socket security, networking, and resource recommendations for running Sencho in production.
|
|
---
|
|
|
|
## The 1:1 path rule
|
|
|
|
This is the most common setup mistake. When Sencho deploys a Docker Compose stack, Docker resolves bind-mount volume paths relative to the **host filesystem**, not the Sencho container. If your compose files reference relative paths like `./data:/app/data`, Docker looks for `./data` on the host — starting from the directory where the compose file lives on the host.
|
|
|
|
This means the path to your compose directory **must be identical** inside and outside the container:
|
|
|
|
```yaml
|
|
# Correct - same path on both sides
|
|
volumes:
|
|
- /opt/compose:/opt/compose
|
|
environment:
|
|
- COMPOSE_DIR=/opt/compose
|
|
|
|
# Wrong - different paths, relative volumes will break
|
|
volumes:
|
|
- /opt/compose:/app/compose
|
|
```
|
|
|
|
See the [Configuration guide](/getting-started/configuration#compose-directory-the-11-path-rule) for a detailed explanation with examples.
|
|
|
|
---
|
|
|
|
## Volume mount checklist
|
|
|
|
Sencho requires three volume mounts to function correctly:
|
|
|
|
| Mount | Purpose | Required |
|
|
|-------|---------|----------|
|
|
| `/var/run/docker.sock:/var/run/docker.sock` | Docker Engine access for managing containers | Yes |
|
|
| `./sencho-data:/app/data` | Persistent storage for SQLite database and encryption keys | Yes |
|
|
| `/opt/compose:/opt/compose` | Your compose project files (must follow 1:1 path rule) | Yes |
|
|
|
|
<Note>
|
|
The data directory contains your Sencho database and encryption keys. Losing this directory means losing your Sencho configuration entirely.
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Docker socket security
|
|
|
|
Mounting the Docker socket (`/var/run/docker.sock`) grants the container the ability to manage all containers, images, volumes, and networks on the host. This is equivalent to root access on the host machine.
|
|
|
|
Sencho mitigates this with privilege dropping:
|
|
|
|
1. The container starts as root to fix volume ownership and resolve Docker socket group permissions
|
|
2. The entrypoint script (`docker-entrypoint.sh`) then drops to a non-root `sencho` user via `su-exec`
|
|
3. All application code runs as the `sencho` user
|
|
|
|
If your environment requires stricter isolation, consider:
|
|
|
|
- Running Sencho on a dedicated Docker host
|
|
- Using Docker's `--userns-remap` for user namespace isolation
|
|
- Placing Sencho behind a reverse proxy with authentication (see [Configuration](/getting-started/configuration#reverse-proxy-setup))
|
|
|
|
---
|
|
|
|
## Resource recommendations
|
|
|
|
| Resource | Minimum | Recommended | Notes |
|
|
|----------|---------|-------------|-------|
|
|
| CPU | 1 core | 1-2 cores | More cores help with concurrent stack operations |
|
|
| RAM | 256 MB | 512 MB | Higher for multi-node setups with many stacks |
|
|
| Disk | 100 MB | 500 MB | Database is typically < 50 MB; allocate headroom for metrics retention |
|
|
|
|
Sencho itself is lightweight. The majority of resource usage on your host comes from the Docker containers it manages, not from Sencho.
|
|
|
|
---
|
|
|
|
## Networking
|
|
|
|
- **Listen port:** 3000 by default, configurable via the `PORT` environment variable
|
|
- **Inbound:** Only the listen port needs to be reachable (directly or through a reverse proxy)
|
|
- **Outbound:** No outbound connections are required for local-only setups. If you use multi-node management, Sencho needs HTTP/HTTPS access to remote Sencho instances on their configured API URLs
|
|
- **Health check:** `GET /api/health` returns `200` when the application is ready. The Docker image includes a built-in `HEALTHCHECK` that polls this endpoint every 30 seconds
|
|
|
|
---
|
|
|
|
## Environment variable checklist
|
|
|
|
Quick reference for all environment variables. See [Configuration](/getting-started/configuration) for full details.
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `JWT_SECRET` | *(required)* | Secret key for signing JWT tokens |
|
|
| `COMPOSE_DIR` | `/app/compose` | Path to compose project files (1:1 rule applies) |
|
|
| `PORT` | `3000` | HTTP server listen port |
|
|
| `DATA_DIR` | `/app/data` | Persistent data directory |
|
|
| `NODE_ENV` | `production` | Set automatically in Docker image |
|
|
| `FRONTEND_URL` | *(empty)* | Frontend origin for CORS; leave empty for same-origin |
|
|
|
|
SSO variables are documented separately in the [SSO Quickstart](/getting-started/sso-quickstart).
|