mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-08-11 11:16:55 +00:00
Anso
7d9dcc77d4
- Fix Cyrillic character in quickstart image ref and correct registry to Docker Hub (saelix/sencho) - Correct backup guide WAL references (Sencho uses SQLite default journal mode) - Add SSL/TLS reverse proxy examples for Nginx, Traefik, and new Caddy configuration - Add missing env vars (PORT, DATA_DIR, NODE_ENV, FRONTEND_URL, SSO_LDAP_DISPLAY_NAME) to .env.example - Add upgrade & migration guide documenting automatic schema migrations - Add self-hosting best practices (1:1 path rule, Docker socket security, resource recs) - Add architecture overview (system design, request flow, database schema, multi-node model) - Add development & contributor guide (setup, tests, code style, PR workflow) - Update OpenAPI spec from v0.23.0 to v0.25.3 with Registries and Image Updates endpoints - Update docs.json navigation with all new pages and API groups
98 lines
4.4 KiB
Plaintext
98 lines
4.4 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 `sencho.db` (all settings, nodes, alerts, metrics) and `encryption.key` (used to encrypt secrets at rest). 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` | Database and encryption key directory |
|
|
| `NODE_ENV` | `production` | Set automatically in Docker image |
|
|
| `FRONTEND_URL` | *(empty)* | Frontend origin for CORS; leave empty for same-origin |
|
|
| `API_RATE_LIMIT` | `100` | Max API requests per minute per IP |
|
|
|
|
SSO variables are documented separately in the [SSO Quickstart](/getting-started/sso-quickstart).
|