From bb50bed0718af83e5ba00dc3cadee5f633c588ec Mon Sep 17 00:00:00 2001 From: Anso Date: Tue, 28 Apr 2026 12:29:48 -0400 Subject: [PATCH] docs: overhaul README, CONTRIBUTING, and SECURITY (#833) README: rewrite to lead with differentiation rather than a flat feature list. Add "Why Sencho?" section covering the four key competitive advantages (Pilot Agent NAT traversal, auto-heal self-healing, atomic deployments, automation-first model). Expand feature coverage from 8 bullets to six grouped domains reflecting the full 38-feature surface. Add architecture note, docker run one-liner, tier comparison table (Community/Skipper/Admiral), and docs link section. Drop stale CI badge; add Docker Pulls badge. CONTRIBUTING: add project layout reference, tier-gate usage guide, TypeScript strictness reminder, and pointer to CLAUDE.md for full coding standards. SECURITY: update supported versions table from stale "0.2.x+" to current "latest release" policy with a note on self-hosted update cadence. --- CONTRIBUTING.md | 41 +++++++++++++-- README.md | 129 +++++++++++++++++++++++++++++++++++++++++++----- SECURITY.md | 10 ++-- 3 files changed, 160 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1aa304e3..12a66d89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,12 +18,47 @@ Thank you for your interest in contributing to Sencho! cd frontend && npm run dev # Vite on :5173 ``` +## Project Layout + +``` +backend/ + src/ + routes/ # One router per feature group (stacks, nodes, fleet, ...) + services/ # Business logic singletons (ComposeService, DockerController, ...) + middleware/ # Auth, tier gates, audit log, node context + websocket/ # Upgrade handlers for log streaming, host console, proxy tunnels +frontend/ + src/ + components/ # Page-level and shared UI components + context/ # Auth, node selection, and other React contexts + hooks/ # Shared React hooks + lib/ # apiFetch wrapper and other utilities +``` + +Read [CLAUDE.md](CLAUDE.md) for full coding standards, architecture rules, and the pre-commit checklist. + ## Development - **Backend:** Node.js + Express + TypeScript in `backend/` - **Frontend:** React 19 + Vite + TypeScript in `frontend/` - **Tests:** `cd backend && npm test` (Vitest) and `npm run test:e2e` (Playwright) - **Lint:** `npm run lint` in both `backend/` and `frontend/` +- **Type check:** Run `cd backend && npx tsc --noEmit` (and the frontend equivalent) before every commit. The CI build will reject type errors. + +## TypeScript Standards + +The project uses `strict: true`. Write code that compiles without `any` casts or `@ts-ignore`. If a library lacks types, import `@types/...` or use `unknown` with narrowing. + +## Tier-Gated Features + +Sencho has three tiers: Community, Skipper, and Admiral. If your change adds a feature that belongs behind a tier gate, use the guards from `backend/src/middleware/tierGates.ts`: + +```typescript +if (!requirePaid(req, res)) return; // Skipper and above +if (!requireAdmiral(req, res)) return; // Admiral only +``` + +Call the guard at the top of the route handler with an early return. Both guards handle proxy-forwarded tier headers automatically. ## Pull Request Process @@ -32,8 +67,8 @@ Thank you for your interest in contributing to Sencho! - Use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages - Update documentation if your change affects user-facing behavior - Add tests for new functionality -- Keep PRs focused - one feature or fix per PR -- Do not edit `CHANGELOG.md` directly. It is generated from your conventional-commit subjects by release-please. If a user-facing change needs more context than the commit subject captures, enrich the auto-opened Release PR description before it is merged. +- Keep PRs focused: one feature or fix per PR +- Do not edit `CHANGELOG.md` directly. It is generated from conventional-commit subjects by release-please. If a user-facing change needs more context, enrich the auto-opened Release PR description before merging. ## Reporting Bugs @@ -41,7 +76,7 @@ Use the [bug report template](https://github.com/AnsoCode/Sencho/issues/new?temp ## Code Style -- TypeScript with `strict: true` - no `any` casts or `@ts-ignore` +- TypeScript with `strict: true`: no `any` casts or `@ts-ignore` - ESLint 9 flat config for both backend and frontend - Tailwind CSS + shadcn/ui for frontend styling - Follow existing patterns in the codebase diff --git a/README.md b/README.md index 39816c96..b179a7bb 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,96 @@ # Sencho -[![CI](https://github.com/AnsoCode/Sencho/actions/workflows/ci.yml/badge.svg)](https://github.com/AnsoCode/Sencho/actions/workflows/ci.yml) -[![Docker](https://img.shields.io/docker/v/saelix/sencho?sort=semver&label=Docker%20Hub)](https://hub.docker.com/r/saelix/sencho) +[![Docker Hub](https://img.shields.io/docker/v/saelix/sencho?sort=semver&label=Docker%20Hub)](https://hub.docker.com/r/saelix/sencho) +[![Docker Pulls](https://img.shields.io/docker/pulls/saelix/sencho)](https://hub.docker.com/r/saelix/sencho) [![License](https://img.shields.io/badge/license-BSL--1.1-blue)](#license) -A self-hosted Docker Compose management dashboard. Manage your stacks, containers, images, volumes, and networks through a modern web UI. +Self-hosted Docker Compose management with self-healing infrastructure, atomic deployments, and multi-network fleet control. Built for engineers who want Kubernetes-grade reliability without the complexity. ![Sencho Dashboard](docs/images/dashboard.png) +--- + +## Why Sencho? + +**Works across every network** + +Pilot Agent tunnels through NAT and firewalls so every node in your fleet is reachable from the dashboard, regardless of network topology. No port-forwarding. No VPN. No SSH. + +**Containers crash. Sencho fixes them.** + +Auto-heal policies watch your stacks and take action (restart, redeploy, notify) before you even open your laptop. Define the rules once; the recovery runs itself. + +**Deploy safely without Kubernetes** + +Atomic deployments mean a failed stack never leaves you in a broken half-up state. Rollback is one click. Deploy enforcement policies block non-compliant images before they ever run. + +**Define behavior, not procedures** + +Auto-update policies, scheduled operations, webhooks, and deploy enforcement let you codify how your infrastructure behaves. The UI is for oversight; the engine runs the work. + +--- + ## Features -- **Stack Management** - Create, edit, start, stop, and remove Docker Compose stacks with a built-in Monaco code editor -- **Multi-Node Support** - Manage remote Sencho instances through a transparent HTTP/WebSocket proxy (Distributed API model) -- **App Store** - One-click deployment from LinuxServer.io templates with editable ports, volumes, and environment variables -- **Resource Hub** - Browse and manage images, volumes, and networks with managed/external/unused classification -- **Live Logs** - Aggregated real-time log streaming across all containers with search and filtering -- **Dashboard** - Container stats, CPU/RAM metrics, health checks, and image update notifications -- **Alerts** - Configurable threshold alerts for CPU, RAM, and disk usage -- **Terminal** - In-browser host console and container exec via WebSocket +### Stack Management +- Monaco editor with syntax highlighting and multi-file support +- Atomic deployments with live progress tracking and one-click rollback +- Git-sourced stacks: pull and sync from any repository +- Stack file explorer and label management + +### Monitoring & Observability +- Live log streaming with search and filtering across all containers +- CPU, RAM, and disk threshold alerts with configurable actions +- Container stats, health checks, and image update notifications +- Global observability view across all nodes in your fleet + +### Fleet Management +- Multi-node via authenticated HTTP/WebSocket proxy (no SSH, no remote socket) +- Fleet view and sync for coordinated updates across nodes +- Pilot Agent for NAT traversal and firewall-crossing connections +- Node compatibility checks before deploying + +### Automation +- Auto-heal policies: detect and recover from container failures automatically +- Auto-update policies: roll out new image versions on your terms +- Scheduled operations with cron expressions +- Webhooks and deploy enforcement rules + +### Security +- SSO: custom OIDC (any spec-compliant provider), Google/GitHub/Okta presets, LDAP/Active Directory +- Two-factor authentication and RBAC with deployer, node-admin, and auditor roles +- Audit log, vulnerability scanning with VEX suppression, and private registry support +- Deploy enforcement to block non-compliant images + +### Operations +- App Store with one-click LinuxServer.io template deployments +- Sencho Cloud Backup for off-site stack archives +- Notification routing to Slack, Discord, email, and webhooks +- Global search across stacks and containers + +--- + +## Architecture + +Sencho uses a Distributed API model. Remote nodes are managed by proxying authenticated HTTP/WebSocket requests to autonomous Sencho instances running on each server. No SSH. No remote Docker socket exposure. No polling agent. Each node speaks the same Sencho API, so the dashboard is just another client. + +--- ## Quick Start +**Docker run (quickest):** + +```bash +docker run -d --name sencho \ + -p 1852:1852 \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -v sencho_data:/app/data \ + -e COMPOSE_DIR=/opt/docker \ + saelix/sencho:latest +``` + +**Docker Compose (recommended for production):** + ```yaml services: sencho: @@ -32,7 +102,7 @@ services: volumes: - /var/run/docker.sock:/var/run/docker.sock - ./data:/app/data - # 1:1 Compose Path Rule: host path MUST match container path + # 1:1 Compose Path Rule: the host path MUST match the container path - /opt/docker:/opt/docker environment: - COMPOSE_DIR=/opt/docker @@ -47,6 +117,39 @@ Then open `http://your-server:1852` and create your admin account. See the [full documentation](https://docs.sencho.io) for configuration details, multi-node setup, and more. +--- + +## Tiers + +| | Community | Skipper | Admiral | +|---|---|---|---| +| **Price** | Free | From $5.99/mo | From $41.99/mo | +| **Nodes** | Unlimited | Unlimited | Unlimited | +| Stack management, logs, alerts, app store | All | All | All | +| Two-factor authentication | Yes | Yes | Yes | +| SSO (custom OIDC) | Yes | Yes | Yes | +| Atomic deployments and auto-update policies | No | Yes | Yes | +| Fleet view, sync, and Sencho Cloud Backup | No | Yes | Yes | +| SSO (Google, GitHub, Okta presets) | No | Yes | Yes | +| RBAC, audit log, and host console | No | No | Yes | +| SSO (LDAP / Active Directory) | No | No | Yes | +| API tokens, private registries, notification routing | No | No | Yes | +| Scheduled operations | No | No | Yes | + +Full tier comparison and pricing at [docs.sencho.io/features/licensing](https://docs.sencho.io/features/licensing). Lifetime licenses available for a limited time. + +--- + +## Documentation + +- [Quick Start](https://docs.sencho.io/getting-started/quickstart) +- [Multi-Node Setup](https://docs.sencho.io/features/multi-node) +- [App Store](https://docs.sencho.io/features/app-store) +- [Security Hardening](https://docs.sencho.io/security) +- [Full Documentation](https://docs.sencho.io) + +--- + ## Development ```bash @@ -69,4 +172,4 @@ See [SECURITY.md](SECURITY.md) for vulnerability reporting. **Do not open public ## License -Sencho is licensed under the [Business Source License 1.1](LICENSE). You may use, modify, and redistribute the code freely, including for production use. The only restriction is offering Sencho as a competing hosted or managed service. On **2030-03-25**, the license automatically converts to [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). +Sencho is licensed under the [Business Source License 1.1](LICENSE). Production use is allowed; the only restriction is offering Sencho as a competing hosted or managed service. On **2030-03-25**, the license automatically converts to [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/SECURITY.md b/SECURITY.md index 4ef59c1b..c68871fd 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,10 +2,12 @@ ## Supported Versions -| Version | Supported | -| ------- | ------------------ | -| 0.2.x+ | Yes | -| < 0.2 | No | +| Version | Supported | +| ------- | --------- | +| Latest release | Yes | +| Older releases | No | + +Sencho is self-hosted software. Always run the latest release to receive security patches. ## Reporting a Vulnerability