diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index f1434850..a019c923 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -29,7 +29,7 @@ body: id: version attributes: label: Sencho version - placeholder: "0.2.2" + placeholder: "0.86.6 (find this in Settings → About)" validations: required: true - type: dropdown @@ -54,3 +54,34 @@ body: label: Relevant logs description: Paste any relevant container or browser console logs render: shell + - type: textarea + id: compose + attributes: + label: Compose snippet (if a stack is involved) + description: Paste the relevant `services:` block. Redact secrets first. + render: yaml + - type: textarea + id: container_logs + attributes: + label: Container logs + description: Output of `docker logs sencho` from the time of the issue. + render: shell + - type: textarea + id: browser_console + attributes: + label: Browser console output (if a UI issue) + description: Open DevTools, reproduce, copy any errors or warnings. + render: shell + - type: checkboxes + id: subsystems + attributes: + label: Subsystems involved + description: Tick any that apply. + options: + - label: Trivy / vulnerability scanning + - label: Pilot Agent (NAT tunnel) + - label: Sencho Mesh (cross-node networking) + - label: Fleet Actions / Secrets / Snapshots + - label: Cloud Backup + - label: SSO / LDAP + - label: None of the above diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9ddb3f4a..8b4782ef 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -12,4 +12,4 @@ - [ ] Documentation updated (if applicable) - [ ] ESLint passes (`npm run lint` in backend/ and frontend/) - [ ] Commit messages follow Conventional Commits -- [ ] CHANGELOG.md updated under `## [Unreleased]` (for user-facing changes) +- [ ] Commit message follows Conventional Commits (the CHANGELOG entry is generated from the commit subject by release-please; do not edit `CHANGELOG.md` directly). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 50c3d832..a9844c80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,7 @@ Thank you for your interest in contributing to Sencho! ## Getting Started 1. Fork the repository -2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/Sencho.git` +2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/sencho.git` 3. Create a branch: `git checkout -b feature/your-feature` 4. Install dependencies: ```bash @@ -35,7 +35,7 @@ frontend/ lib/ # apiFetch wrapper and other utilities ``` -Read [CLAUDE.md](CLAUDE.md) for full coding standards, architecture rules, and the pre-commit checklist. +See the rest of this file for the most important contributor-facing standards (TypeScript, tier gates, PR process, code style). Architecture and module layout deep-dives live in the project documentation at [docs.sencho.io](https://docs.sencho.io). ## Development diff --git a/KNOWN_LIMITATIONS.md b/KNOWN_LIMITATIONS.md new file mode 100644 index 00000000..5cad757e --- /dev/null +++ b/KNOWN_LIMITATIONS.md @@ -0,0 +1,38 @@ +# Known limitations + +> [!NOTE] +> Sencho is currently in public beta on the path to v1.0. Core workflows are actively tested, but early users should review the known limitations and avoid deploying it blindly on critical infrastructure without testing in their own environment first. + +Below are the limitations we know about today. If you hit something that is not here, please file a bug. + +## Scale + +- Single-instance use: not benchmarked yet beyond typical homelab loads. Expect comfortable operation on tens of stacks and a few hundred containers per node; very large nodes may show UI slowdowns. +- Fleet: not benchmarked yet. Comfortably tested with small fleets (a handful of nodes); larger fleets work but are less exercised. +- Container log streaming: not benchmarked yet at sustained high log rates; very chatty containers may lag the UI. + +## Platform support + +- Operating systems: Linux (primary), macOS (development), Windows with WSL2 (development). Production deployments should be on Linux. +- Docker: requires Docker Engine 20.10 or later and Docker Compose v2. +- Browsers: latest two stable versions of Chrome, Firefox, Safari, Edge. + +## Architecture + +- Sencho runs as root inside its container by default. Non-root operation is supported via `SENCHO_USER=sencho` but may require adjusting bind-mount ownership. +- Mounting `/var/run/docker.sock` grants Sencho root-equivalent privilege on the host. This is the same model as Portainer, Dockge, Komodo, and similar tools. +- Plain HTTP works on trusted networks but is not safe to expose to the public internet. Always front Sencho with a TLS-terminating reverse proxy in production. +- Multi-node fleets require either the remote node reaching the primary or the primary reaching the remote, depending on Pilot Agent vs direct proxy mode. Both directions blocked at once is not supported. +- There is no downgrade path between minor versions; back up `/app/data` before upgrading. +- Trivy vulnerability scanning requires outbound HTTPS to the Trivy database mirror unless configured for air-gapped operation. + +## Features + +- Mesh networking depends on a shared Docker network alias scheme; it does not currently support overlay networks or Swarm. +- Auto-update applies one image at a time per node; concurrent updates of the same stack are serialized. +- Pilot Agent tunnels have a hard limit of 256 concurrent connections per primary. +- Some features are tier-gated; see [pricing](https://sencho.io/pricing). + +## What we will fix vs document + +Items in this file are either (a) on the roadmap, (b) architectural constraints that will not change in 1.x, or (c) documented for awareness because the right fix is a workaround. Each item should say which. diff --git a/README.md b/README.md index ac2676f8..d4e1f0ef 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,9 @@ Sencho dashboard +> [!NOTE] +> Sencho is currently in public beta on the path to v1.0. Core workflows are actively tested, but early users should review the known limitations and avoid deploying it blindly on critical infrastructure without testing in their own environment first. + --- ## What Sencho is @@ -35,12 +38,25 @@ Sencho is for homelab operators, small DevOps teams, and platform engineers who It runs as a single container on your hardware and gives you a UI for the work you currently do over SSH on compose stacks: deploying, editing files, watching logs, restarting containers, browsing volumes, and recovering from failures. Your compose files stay on the host filesystem and remain the source of truth. -A Sencho instance is autonomous. To manage another machine, you install a second Sencho on it and connect them with a long-lived API token; the primary dashboard then acts as a transparent HTTPS proxy across your fleet. There is no SSH and no exposed Docker socket. For nodes behind NAT or strict firewalls, the Pilot Agent establishes a single outbound WebSocket tunnel to the primary, so the remote host opens no inbound port at all. +A Sencho instance is autonomous. To manage another machine, you install a second Sencho on it and connect them with a long-lived API token; the primary dashboard then acts as an authenticated HTTP and WebSocket proxy across your fleet. Use TLS, a VPN, or a private network for any untrusted link. Each node still uses its local Docker socket (see Quick start), but Sencho does not require SSH and does not expose a remote Docker socket on the network. For nodes behind NAT or strict firewalls, the Pilot Agent establishes a single outbound WebSocket tunnel to the primary, so the remote host opens no inbound port at all. Most capabilities are free in the Community tier. A few advanced automation and fleet-control features ship in paid tiers; pricing lives at [sencho.io/pricing](https://sencho.io/pricing). +## What Sencho is not (yet) + +Sencho is a Docker Compose control plane focused on homelab and small-fleet operators. It is intentionally not: + +- A Kubernetes scheduler or replacement. +- A reverse proxy. Front Sencho with your existing proxy (Caddy, Traefik, nginx) for TLS and authentication on the public edge. +- A monitoring stack. Sencho surfaces container and host metrics in the dashboard but does not replace Prometheus, Grafana, or your existing alerting pipeline. +- A CI / CD pipeline. Use webhooks, the API, or Git-sourced stacks to connect Sencho to your build system. + +See [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) for the current limitation list. + --- +**Tier coverage:** All bullets below are available in the free Community tier unless marked with `(Skipper)` for paid mid-tier or `(Admiral)` for paid top-tier. Full breakdown at [sencho.io/pricing](https://sencho.io/pricing). + ## Capabilities ### Stacks @@ -55,7 +71,7 @@ Most capabilities are free in the Community tier. A few advanced automation and - Aggregated [log search and stream](https://docs.sencho.io/features/global-observability) across every container in the fleet - Live container stats, health checks, and image-update notifications - Threshold alerts for CPU, memory, and network -- Read-only [audit log](https://docs.sencho.io/features/audit-log) of every action +- Read-only [audit log](https://docs.sencho.io/features/audit-log) of every action **(Admiral)** - [Network topology](https://docs.sencho.io/features/fleet-view) view of containers, networks, and nodes ### Fleet @@ -66,30 +82,34 @@ Most capabilities are free in the Community tier. A few advanced automation and - Node compatibility checks before deploying ### Automation -- [Auto-heal policies](https://docs.sencho.io/features/auto-heal-policies) for failed containers -- [Auto-update policies](https://docs.sencho.io/features/auto-update-policies) for image rollouts -- [Scheduled operations](https://docs.sencho.io/features/scheduled-operations) on cron -- [Blueprints](https://docs.sencho.io/features/blueprint-model): declarative fleet templates with drift detection -- [Webhooks](https://docs.sencho.io/features/webhooks) on stack lifecycle events -- Encrypted [Fleet Secrets](https://docs.sencho.io/features/fleet-secrets) pushed to labeled nodes +- [Auto-heal policies](https://docs.sencho.io/features/auto-heal-policies) for failed containers **(Skipper)** +- [Auto-update policies](https://docs.sencho.io/features/auto-update-policies) for image rollouts **(Skipper)** +- [Scheduled operations](https://docs.sencho.io/features/scheduled-operations) on cron **(Skipper)** +- [Blueprints](https://docs.sencho.io/features/blueprint-model): declarative fleet templates with drift detection **(Skipper)** +- [Webhooks](https://docs.sencho.io/features/webhooks) on stack lifecycle events **(Skipper)** +- Encrypted [Fleet Secrets](https://docs.sencho.io/features/fleet-secrets) pushed to labeled nodes **(Skipper)** ### Security - [SSO](https://docs.sencho.io/features/sso): custom OIDC, presets for Google, GitHub, and Okta, plus LDAP and Active Directory - [Two-factor authentication](https://docs.sencho.io/features/two-factor-authentication) with TOTP and backup codes -- [RBAC](https://docs.sencho.io/features/rbac) with admin, editor, and viewer roles -- [Vulnerability scanning](https://docs.sencho.io/features/vulnerability-scanning) via Trivy with VEX-based suppression and SARIF export -- [Private registries](https://docs.sencho.io/features/private-registries) and [deploy enforcement](https://docs.sencho.io/features/deploy-enforcement) for non-compliant images +- [RBAC](https://docs.sencho.io/features/rbac) with five roles: admin (full control), viewer (read-only), deployer (deploy and restart, no edits), node-admin (admin scoped to specific nodes), and auditor (read-only with audit-log access) +- [Vulnerability scanning](https://docs.sencho.io/features/vulnerability-scanning) via Trivy on every tier with VEX-based suppression; SARIF export and SBOM upload **(Skipper)** +- [Private registries](https://docs.sencho.io/features/private-registries) **(Admiral)** and [deploy enforcement](https://docs.sencho.io/features/deploy-enforcement) **(Skipper)** for non-compliant images - [API tokens](https://docs.sencho.io/features/api-tokens) for automation ### Operations -- [Host console](https://docs.sencho.io/features/host-console) in the browser -- [Sencho Cloud Backup](https://docs.sencho.io/operations/backup) for off-site stack archives -- [Notification routing](https://docs.sencho.io/features/notification-routing) to Slack, Discord, email, and webhooks +- [Host console](https://docs.sencho.io/features/host-console) in the browser **(Admiral)** +- Off-site stack archives via custom S3 (every tier) or [Sencho Cloud Backup](https://docs.sencho.io/operations/backup) **(Admiral)** for managed storage +- [Notification routing](https://docs.sencho.io/features/alerts-notifications#notification-routing) to Slack, Discord, email, and webhooks - [Global search](https://docs.sencho.io/features/global-search) across stacks, containers, and services - [Resources view](https://docs.sencho.io/features/resources) for images, volumes, and networks with scoped prune actions --- +### Before you install + +Sencho talks to Docker through the host's `/var/run/docker.sock`. Mounting this socket grants Sencho the same privilege as `sudo docker` on the host. This is the same model used by Portainer, Dockge, Komodo, and other Compose dashboards. If your threat model requires stricter isolation, see [running with a non-root container user](https://docs.sencho.io/operations/self-hosting#non-root-user) and front Sencho with a reverse proxy that enforces authentication. + ## Quick start Sencho runs in a single container. @@ -128,6 +148,8 @@ docker run -d --name sencho \ -p 1852:1852 \ -v /var/run/docker.sock:/var/run/docker.sock \ -v sencho_data:/app/data \ + # 1:1 Compose Path Rule: the host path MUST match the container path + -v /opt/docker:/opt/docker \ -e COMPOSE_DIR=/opt/docker \ saelix/sencho:latest ``` @@ -140,7 +162,7 @@ For the full walkthrough, see the [quickstart guide](https://docs.sencho.io/gett ## Adding remote nodes -To manage a second machine, install Sencho on it the same way, then add it from the primary dashboard with its URL and a long-lived API token. The primary proxies authenticated HTTPS and WebSocket requests to the remote instance. No SSH, no exposed Docker socket, no agent process on the remote. Nodes behind NAT or strict firewalls can opt into the Pilot Agent for outbound-only connectivity. +To manage a second machine, install Sencho on it the same way, then add it from the primary dashboard with its URL and a long-lived API token. The primary proxies authenticated HTTP and WebSocket requests to the remote instance. The remote node does not run SSH for Sencho, does not expose its Docker socket on the network, and does not run a separate agent process. The local Sencho on each node manages its own Docker through the standard socket mount described in Quick start. Nodes behind NAT or strict firewalls can opt into the Pilot Agent for outbound-only connectivity. See the [multi-node guide](https://docs.sencho.io/features/multi-node) for the full token-bearer flow. @@ -155,13 +177,19 @@ See the [multi-node guide](https://docs.sencho.io/features/multi-node) for the f --- +## Telemetry and data handling + +Sencho does not emit telemetry, analytics, or crash reports. The only outbound traffic is license validation against Lemon Squeezy, and only when a paid license key is activated. Community-tier instances make no outbound calls to Sencho-controlled endpoints. Stack metadata, container inventory, and user activity never leave your instance. + +--- + ## Documentation, community, and license - **Documentation:** [docs.sencho.io](https://docs.sencho.io) - **Community:** [GitHub Discussions](https://github.com/studio-saelix/sencho/discussions) - **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) - **Security:** [SECURITY.md](SECURITY.md). Do not open public issues for security vulnerabilities. -- **License:** [Business Source License 1.1](LICENSE). Free for production use; the only restriction is offering Sencho as a competing hosted or managed service. Converts to [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) on **2030-03-25**. +- **License:** [Business Source License 1.1](LICENSE). Free for most self-hosted production use under the BSL Additional Use Grant; see [LICENSE](LICENSE) and the [license FAQ](https://sencho.io/license-faq) for exact terms. Converts to [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) on **2030-03-25**. --- diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..d68a376f --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,36 @@ +# Getting help with Sencho + +Sencho is a solo-maintained project. Here is what to expect. + +## Where to ask + +- **Setup, configuration, "how do I" questions** → [Documentation](https://docs.sencho.io) +- **Discussion, share your setup, propose ideas** → [GitHub Discussions](https://github.com/studio-saelix/sencho/discussions) +- **Bugs, regressions, broken features** → [Bug report](https://github.com/studio-saelix/sencho/issues/new?template=bug_report.yml) +- **Feature requests** → [Feature request](https://github.com/studio-saelix/sencho/issues/new?template=feature_request.yml) +- **Security vulnerabilities** → [SECURITY.md](SECURITY.md). Do not open a public issue. +- **Licensing, billing, refunds** → licensing@sencho.io +- **Support the project** → [Buy Me a Coffee](https://buymeacoffee.com/sencho). Sponsorship is not required and does not change support response times; it helps fund the work. + +## Response times + +Sencho is built by a single maintainer. Volunteer responses target: + +- Security reports: 72 hours initial response (committed in SECURITY.md) +- Bug reports: a few days, typically within a week +- Feature requests: triaged but not always replied to individually; check the roadmap +- Discussions questions: community-first; the maintainer joins when possible + +There is no SLA. Paid tiers (Skipper, Admiral) get priority for licensing-related issues through the email above. A formal paid-support tier may follow 1.0. + +## What is in scope + +- Bugs in shipped functionality, on a supported deployment (Docker Compose or `docker run` with the documented mounts). +- Setup questions where the docs are unclear; tell us which page confused you. +- Feature requests that fit Sencho's scope (Docker Compose control plane for homelab and small fleets). + +## What is out of scope + +- Generic Docker, networking, or Compose troubleshooting unrelated to Sencho. +- Custom modifications, forks, or non-default deployments. +- Migration help from competing tools beyond what the docs already cover. diff --git a/docs/getting-started/quickstart.mdx b/docs/getting-started/quickstart.mdx index 9189ce78..3f31f1de 100644 --- a/docs/getting-started/quickstart.mdx +++ b/docs/getting-started/quickstart.mdx @@ -5,6 +5,10 @@ description: Get Sencho running in under five minutes. This walks you from a clean Docker host to a working Sencho cockpit. Five minutes if your Compose directory is already in the right place, ten if you need to lay it out first. + + Sencho is currently in public beta on the path to v1.0. Core workflows are actively tested, but early users should review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and avoid deploying it blindly on critical infrastructure without testing in their own environment first. + + ## Prerequisites - Docker and Docker Compose installed on the host. diff --git a/docs/operations/trivy-setup.mdx b/docs/operations/trivy-setup.mdx index 57e5a41a..55d85dee 100644 --- a/docs/operations/trivy-setup.mdx +++ b/docs/operations/trivy-setup.mdx @@ -99,7 +99,7 @@ Mount the host's Trivy binary into the Sencho container. This is the simplest op ```yaml services: sencho: - image: sencho/sencho:latest + image: saelix/sencho:latest volumes: - /var/run/docker.sock:/var/run/docker.sock - ./sencho-data:/app/data @@ -123,7 +123,7 @@ Adjust the first path if `which trivy` on the host prints something other than ` If the host's Trivy binary is not ABI-compatible with the Sencho container (for example because you are running macOS host binaries or a different glibc version), install Trivy inside the image instead: ```dockerfile -FROM sencho/sencho:latest +FROM saelix/sencho:latest RUN apk add --no-cache curl ca-certificates \ && curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh \ diff --git a/docs/operations/troubleshooting.mdx b/docs/operations/troubleshooting.mdx index cec98c7e..4e630f4f 100644 --- a/docs/operations/troubleshooting.mdx +++ b/docs/operations/troubleshooting.mdx @@ -3,6 +3,10 @@ title: Troubleshooting description: Solutions to the most common Sencho setup and runtime problems. --- + + Sencho is currently in public beta on the path to v1.0. Core workflows are actively tested, but early users should review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and avoid deploying it blindly on critical infrastructure without testing in their own environment first. + + ## Containers won't start after deploy **Symptom:** You click Deploy and containers immediately exit or never appear. diff --git a/docs/operations/upgrade.mdx b/docs/operations/upgrade.mdx index 188da0c2..f26753c2 100644 --- a/docs/operations/upgrade.mdx +++ b/docs/operations/upgrade.mdx @@ -3,6 +3,10 @@ title: Upgrading Sencho description: How to update Sencho, what happens during upgrades, and the version policy. --- + + Sencho is currently in public beta on the path to v1.0. Core workflows are actively tested, but early users should review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and avoid deploying it blindly on critical infrastructure without testing in their own environment first. + + ## Upgrade steps Upgrading Sencho is a two-command process. Pull the latest image and recreate the container: diff --git a/docs/reference/security.mdx b/docs/reference/security.mdx index 0da876d1..6161e0f8 100644 --- a/docs/reference/security.mdx +++ b/docs/reference/security.mdx @@ -5,6 +5,10 @@ description: How Sencho protects your infrastructure with layered authentication Sencho applies defense-in-depth across authentication, authorization, encryption, and auditing. All security features ship with sensible defaults and work out of the box on a fresh install. + + Sencho is currently in public beta on the path to v1.0. Core workflows are actively tested, but early users should review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and avoid deploying it blindly on critical infrastructure without testing in their own environment first. + + ## The authentication stack Every self-hosted instance includes the full security stack, with advanced features unlocked by tier. diff --git a/docs/reference/settings.mdx b/docs/reference/settings.mdx index df16464e..9e21972c 100644 --- a/docs/reference/settings.mdx +++ b/docs/reference/settings.mdx @@ -200,7 +200,7 @@ See [SSO](/features/sso) for the full configuration walkthrough. ## API Tokens - API Tokens require a Sencho Admiral license. + API Tokens are available on every tier. Creation, listing, and revocation require an admin role. **Scope:** Global, admin-only @@ -374,7 +374,7 @@ See [Webhooks](/features/webhooks) for the full walkthrough including authentica ## Labels - Stack Labels require a Sencho Skipper or Admiral license. + Label organization (create, edit, assign, remove) is available on every tier. Bulk label actions (apply or remove a label across multiple stacks in one operation) require Skipper or Admiral. **Scope:** Per-node