From 9e597fbce53a5a8ef9cfc795f9a598e680c3073d Mon Sep 17 00:00:00 2001 From: bifrost0x Date: Wed, 11 Nov 2026 09:49:43 +0100 Subject: [PATCH] Tighten the README entry point and fix the tour links The tour links pointed at site/demo.html, which GitHub renders as HTML source. They now open the published tour, and the header links straight to Quick Start. Quick Start leads with the requirement and the commands; the evaluation and upgrade notes follow. The feature list is shorter and routes detail to the Wiki, the WebSSH 3 highlights are folded into it, and the support line lists every funding option. Adds the selfhost.directory listing badge. --- README.md | 125 +++++++++------------------ tests/test_public_product_surface.py | 3 +- 2 files changed, 43 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 1ac7ccb1..49d40fcf 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,8 @@

Product site · - Watch the full tour · + Watch the full tour · + Quick Start · Documentation · Roadmap · Container image · @@ -24,13 +25,14 @@ Interactive code map Latest release GitHub stars + Listed on selfhost.directory No telemetry

## Product tour

- + WebSSH 3 dashboard with saved SSH routes and infrastructure

@@ -47,31 +49,6 @@ a hosted control plane or runtime CDN dependencies.

-## New in WebSSH 3 - - - - - - - -
-

Status-first overview

- Host readiness, open sessions, automation results and reachability at a - glance. Arrange panels freely, dismiss handled alerts and find hosts with - /. - 		-

Native automation

- Run command sets and templates now or on a schedule, with exact-target - review, saved passwords or keys and bounded per-step output. - 		-

Find SSH hosts

- Scan a network range you choose for SSH and SFTP servers, gently and only - on request, then add a host from a prefilled form. -
- -Upgrading from 2.x? Read the [WebSSH 3 changes and upgrade notes](docs/webssh-3.md). - ## Why WebSSH - **One workspace, not a terminal tab.** Keep SSH sessions, SFTP sources, @@ -85,35 +62,25 @@ Upgrading from 2.x? Read the [WebSSH 3 changes and upgrade notes](docs/webssh-3. ## Features +The [WebSSH Wiki](https://github.com/bifrost0x/webssh/wiki) covers each area in +depth. Upgrading from 2.x? Read the +[WebSSH 3 changes and upgrade notes](docs/webssh-3.md). + ### Overview and automation -- Status-first overview: host readiness from stored configuration, open - sessions, 14-day automation results, reachability and recent activity. -- Free layout per account: drag, resize, hide and restore panels, with keyboard - controls and a reset to the default arrangement. +- Status overview with host readiness, open sessions, automation results, + reachability and recent activity, in a layout you arrange per account. - **Needs attention** lists unverified host keys, missing jump hosts, changed - saved passwords and failed runs. Handled items can be dismissed and come back - when the situation changes. -- Optional reachability checks (off, on demand, or automatic): one TCP - connection to the SSH port under the SSH network policy, no login. -- Hosts show their platform and services such as Docker or Nextcloud, read-only - over SSH without elevated rights. -- **Find hosts** scans a range you name for SSH and SFTP servers at a gentle, - fixed pace and opens the host form prefilled. It only runs when you start it. -- Readable route summaries and an expandable SSH map with saved arrangements. -- A classic overview remains available, with a per-account choice of Overview - or Workspaces as the start page after sign-in. -- Reusable workflows from commands, command sets and templates, immediate runs, - cron schedules, cancellation and bounded per-step output history, for saved - hosts or complete groups. Administrators enable Automation; it is disabled by - default and requires HTTPS. -- Optional encrypted, per-account passwords shared by saved hosts and supported - connection types. Administrators enable this under Integrations. -- Application backup exports exclude stored passwords and SSH private keys. - Keep a separate credential recovery plan before restoring. - -See the [WebSSH 3 changes and upgrade notes](docs/webssh-3.md), -[automation guide](docs/automation.md) and [credential guide](docs/credentials.md). + saved passwords and failed runs. +- **Find hosts** scans a network range you name for SSH and SFTP servers, only + on request, and opens the host form prefilled. +- Automation runs commands, command sets and templates now or on a cron + schedule, for saved hosts or complete groups. Administrators enable it; it is + disabled by default and requires HTTPS. +- Optional encrypted, per-account saved passwords, enabled by an administrator. + +See the [automation guide](docs/automation.md) and +[credential guide](docs/credentials.md).
See all eleven themes in WebSSH 3 @@ -124,37 +91,27 @@ See the [WebSSH 3 changes and upgrade notes](docs/webssh-3.md), ### Terminal workspace - Multiple SSH sessions with tabs and 1-, 2-, or 4-pane layouts. -- Optional persistent remote shells through tmux, with session-local mouse - scrolling and folder synchronization after explicit Bash prompt setup. - Saved connections, jump hosts, key, password, SSH server PAM MFA, and optional Tailscale SSH authentication paths. +- Optional persistent remote shells through tmux. - Broadcast input, terminal search, transcripts, reconnect controls, and configurable scrollback. -- Per-account terminal appearance with four self-hosted Nerd Font Mono families - (JetBrains Mono, Hack, Fira Mono, and Source Code Pro), local font selection, - and live shell, code, and character previews. - Session-aware Files, Commands, Diagnostics, and Notes contexts. - **Active Session Monitoring** for supported Linux resource and runtime data. - **Expanded Diagnostics** for resource history, processes, systemd services, and Docker containers. - **Clipboard-Only Service Actions** that prepare allowlisted commands without executing the service change inside WebSSH. - -Fonts and Nerd Font symbols are served locally; see the -[terminal font guide](static/vendor/terminal-fonts/README.md). +- Per-account terminal appearance with four locally served Nerd Font Mono + families; see the [terminal font guide](static/vendor/terminal-fonts/README.md). ### Files and transfers -- Source-first SFTP and opt-in SMB workspace with independent tabs and one or - two file panes. +- SFTP file workspace with independent tabs and one or two file panes; SMB + sources are opt-in. - Uploads, downloads, previews, inline text editing, and common file operations. -- Streamed HTTP bulk transfers with Socket.IO limited to control events and - bounded editor content. - Server-to-server transfers across SFTP and SMB sources with progress, cancellation, explicit conflict handling, and a shared transfer queue. -- Same-source moves between folders without silently replacing existing items. -- Stable, visible transfer reasons such as permission denied, conflict, - unavailable source, timeout, and configured-limit violations. - Per-user ownership checks, size limits, quotas, and path validation. SMB is disabled by default (`SMB_ENABLED=false`) and needs an exact @@ -169,8 +126,8 @@ for authentication, access checks, limits and the trust boundary. - Local multi-user accounts with isolated profiles, keys, files, settings, and SSH host trust. - Optional Passkeys, authenticator apps (TOTP), and one-time Recovery Codes. -- Optional OIDC, admin-configured GitHub App, and LDAP/Active Directory sign-in with conservative account - linking and assurance handling. +- Optional OIDC, admin-configured GitHub App, and LDAP/Active Directory + sign-in. - Action-bound confirmation for protected account and administrative changes. - Encrypted SSH private-key storage and per-user known-host decisions. - CSRF protection, secure response headers, rate limits, request limits, audit @@ -180,10 +137,9 @@ for authentication, access checks, limits and the trust boundary. - Docker and Docker Compose deployment with a persistent data volume. - Health and readiness endpoints for deployment checks. -- User administration, registration controls, security feature gates, and - structured audit export and retention. -- Consistent online backups and restore with maintenance mode, staging - isolation, quotas, explicit confirmation, and bounded execution. +- User administration, registration controls, and structured audit export and + retention. +- Online backup and restore with maintenance mode and explicit confirmation. - Optional Redis-backed rate-limit counters. - Vendored browser dependencies, a same-origin Content Security Policy, and no built-in telemetry. @@ -288,9 +244,7 @@ changes and keeps factors and SSH trust in one account-owned view. ## Quick Start -The supplied Compose file is intended for evaluation and trusted homelab -networks. It stores the database, generated application secret, user data, and -encrypted keys in the `webssh_data` volume. +Requires Docker with the Compose plugin on `linux/amd64` or `linux/arm64`. ```bash mkdir webssh-deployment @@ -301,13 +255,14 @@ docker compose up -d Open . On a new instance, create the first administrator immediately from a trusted network. The one-time browser bootstrap closes after -that account exists. - -Verify readiness with `curl -fsS http://localhost:5000/ready`. +that account exists. Readiness: `curl -fsS http://localhost:5000/ready`. -The supplied Compose file follows `latest`. For controlled upgrades, pin a -published version or verified image digest, keep Compose files from the same -release, and back up the data with matching secrets. See +The supplied Compose file is intended for evaluation and trusted homelab +networks. It stores the database, generated application secret, user data, and +encrypted keys in the `webssh_data` volume, and it follows `latest`. For +controlled upgrades, pin a published version or verified image digest, keep +Compose files from the same release, and back up the data with matching +secrets. See [upgrade and rollback guidance](https://github.com/bifrost0x/webssh/wiki/Upgrading-Rollback-and-FAQ). Do not expose this homelab configuration to the Internet unchanged. Read the @@ -379,7 +334,9 @@ so the security and runtime boundaries can be reviewed before implementation. - Use [Issues](https://github.com/bifrost0x/webssh/issues) for reproducible bugs. - Report vulnerabilities privately through [GitHub Security Advisories](https://github.com/bifrost0x/webssh/security/advisories/new). -- Support ongoing work through [Buy Me a Coffee](https://buymeacoffee.com/bifrost0x). +- Support ongoing work through [GitHub Sponsors](https://github.com/sponsors/bifrost0x), + [Patreon](https://www.patreon.com/bifrost0x) or + [Buy Me a Coffee](https://buymeacoffee.com/bifrost0x). ## Star History diff --git a/tests/test_public_product_surface.py b/tests/test_public_product_surface.py index d27f04d8..073beb37 100644 --- a/tests/test_public_product_surface.py +++ b/tests/test_public_product_surface.py @@ -339,7 +339,8 @@ def test_demo_links_bypass_previously_cached_tour(built_site): assert all(parse_qs(link.query) == {'v': [revision]} for link in demo_links) readme = (ROOT / 'README.md').read_text(encoding='utf-8') page = Page(readme) - assert 'site/demo.html' in page.links() + assert packager().SITE_URL + 'demo.html' in page.links() + assert 'site/demo.html' not in page.links() assert 'assets/dashboard.png' in readme assert 'assets/webssh-themes.gif' in readme assert 'Watch the 60-second' not in readme