mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-27 04:11:01 +00:00
Anso
7663f4cd8b
* feat(fleet): sencho mesh in traffic and routing tab Lights up Sencho Mesh: cross-node container forwarding rendered as if the container next to you were on localhost. Builds on the dormant TCP frame plumbing from the prior PR (pilot tunnel TCP frames + sencho-mesh sidecar package) and exposes the Admiral-only orchestrator surface. Backend - New mesh_stacks table (per-node opt-ins) + nodes.mesh_enabled column via DatabaseService.migrateMeshTables. - MeshService singleton: sidecar lifecycle via Dockerode, opt-in/out with cascading override regeneration, request-based resolver from sidecar control WS, cross-node TCP forwarding via PilotTunnelManager (same-node fast path included), in-memory 1000-event activity ring buffer with durable mirror to audit_log for state-change events, per-node and per-route diagnostics, and the Test upstream probe. - MeshComposeOverride: pure YAML generator that injects extra_hosts using host-gateway. The user's docker-compose.yml is never mutated; overrides live under DATA_DIR/mesh/overrides. - ComposeService deploy/update splice the override file when the stack is opted in; non-mesh stacks behave identically to today. - Pilot agent resolveMeshTarget consults the local mesh_stacks table (defense in depth) and resolves Compose containers via Dockerode. - /api/mesh router with 13 Admiral-gated endpoints covering status, enable/disable, stack opt-in/out, alias listing, per-route diagnostic, Test upstream probe, per-node diagnostic, sidecar restart, activity log paginated and SSE. - meshControl WS slot at /api/mesh/control validates the mesh_sidecar JWT minted by MeshService; dispatched as upgrade slot 2 (canonical order preserved). Frontend - New Traffic Routing tab in FleetView, gated by isAdmiral and wrapped in AdmiralGate. Tab uses the cyan brand glyph and italic-serif state typography from the audit. - RoutingTab masthead with mesh activity drawer, per-node card grid with TogglePill, alias rows with five-state pill taxonomy (healthy / degraded / unreachable / tunnel-down / not-authorized), inline Test buttons. - Four sheets: opt-in picker with port-collision inline error, per-route detail with diagnostic + filtered activity, per-node diagnostics with active streams + resolver cache + restart action, fleet-wide activity log with filters. - meshRouteState helper centralizes pill-state mapping; pure-function tests cover all five states. Docs - User docs at /docs/features/sencho-mesh.mdx covering opt-in, troubleshooting, security model (4 guarantees + 4 explicit non-guarantees), and V1 limitations. - Internal architecture and runbook pages. - websocket-dispatch internal doc updated with the new slot. * fix(mesh): validate stack name before path use; fix test DB lifecycle Two surgical fixes against the prior PR. Path-injection (CodeQL js/path-injection): MeshService.optInStack, optOutStack, ensureStackOverride, and removeStackOverride now validate stackName via isValidStackName from utils/validation, reject malicious names at the API boundary, and additionally check isPathWithinBase on the resolved override file path for defense in depth. The dataflow from req.params.stackName to fs.writeFile no longer reaches an unsanitized path expression. Test DB lifecycle: mesh-service.test.ts used per-test setupTestDb / cleanupTestDb, which deletes the temp dir while DatabaseService still holds an open SQLite handle. On Linux CI this raises SQLITE_READONLY_DBMOVED on the next prepare() because the inode has been unlinked. Switched to file-scoped beforeAll/afterAll matching agents-routes.test.ts, with a per-test beforeEach that truncates mesh_stacks plus non-default nodes and resets the MeshService singleton in-memory state. Adds a new test case asserting the path-traversal rejection. * fix(compose): use discovered compose filename instead of hardcoded docker-compose.yml composeArgs() hardcoded `-f docker-compose.yml` for every deploy. Sencho writes its canonical compose file as `compose.yaml`, so any stack created via the UI failed to deploy with `open ...docker-compose.yml: no such file or directory`. When no mesh override applies, drop the explicit `-f` so docker compose's built-in discovery resolves the actual filename. When an override exists, look up the real base filename via FileSystemService.getComposeFilename() and pass both files explicitly. Also hoist the MeshService import to module top now that the dependency is known to be acyclic, and revert the matching unit-test assertion.
Sencho
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.
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
- 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's architecture combines a Distributed API model with an optional Pilot Agent for complex networks.
- Distributed API: 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.
- Pilot Agent: For nodes behind NAT or strict firewalls, the Pilot Agent establishes secure outbound tunnels to the primary dashboard instance. This guarantees full fleet visibility and management without requiring port-forwarding, VPNs, or inbound network access.
Quick Start
Docker run (quickest):
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):
services:
sencho:
image: saelix/sencho:latest
container_name: sencho
restart: unless-stopped
ports:
- "1852:1852"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./data:/app/data
# 1:1 Compose Path Rule: the host path MUST match the container path
- /opt/docker:/opt/docker
environment:
- COMPOSE_DIR=/opt/docker
- DATA_DIR=/app/data
docker compose up -d
Then open http://your-server:1852 and create your admin account.
See the full documentation for configuration details, multi-node setup, and more.
Documentation
Development
# Backend (Express + TypeScript)
cd backend && npm install && npm run dev
# Frontend (React + Vite)
cd frontend && npm install && npm run dev
The frontend dev server proxies /api requests to the backend on port 1852.
Contributing
See CONTRIBUTING.md for development setup and PR guidelines.
Security
See SECURITY.md for vulnerability reporting. Do not open public issues for security vulnerabilities.
License
Sencho is licensed under the Business Source License 1.1. 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.