Initial commit

docker-hub-overview.md

@@ -0,0 +1,135 @@
+# WebSSH - Browser-based SSH Client
+
+[![Docker Pulls](https://img.shields.io/docker/pulls/danaildr/webssh)](https://hub.docker.com/r/danaildr/webssh)
+[![Docker Image Size](https://img.shields.io/docker/image-size/danaildr/webssh/latest)](https://hub.docker.com/r/danaildr/webssh)
+
+Multi-connection SSH client that runs entirely in your browser with JWT authentication, SFTP file manager, and automatic session recording. Built with Python, Paramiko, WebSockets, and xterm.js.
+
+**Perfect for:** System administrators, DevOps engineers, developers who need quick SSH access from any browser without installing clients.
+
+## Features
+
+- **Multi-connection support** - Manage multiple SSH connections simultaneously through a sidebar interface
+- **JWT Authentication** - Secure token-based authentication (configurable users, 8-hour token expiry)
+- **Password & SSH Key authentication** - Support for both password and SSH key (RSA, Ed25519, ECDSA)
+- **SFTP File Manager** - Built-in file manager with drag-and-drop upload/download, directory navigation, and file operations
+- **Terminal emulator** - Full xterm.js terminal experience with proper scrolling and colors
+- **Session Recording** - Automatic recording of SSH sessions in asciinema format with playback and configurable retention
+- **Auto-Lock & Auto-Disconnect** - Automatic session locking after inactivity (configurable per connection) and auto-disconnect for extended inactivity
+- **Single port deployment** - All services (HTTP API, WebSocket SSH, WebSocket SFTP) run through one port
+- **Multi-architecture** - Images available for `linux/amd64` and `linux/arm64`
+- **Lightweight** - Images with integrated Caddy reverse proxy included
+
+## Quick Start
+
+### Single Container
+```bash
+docker run -d \
+  -p 8080:8080 \
+  -e WEBSSH_USERS=admin:admin \
+  -e MAX_UPLOAD_SIZE=100M \
+  --name webssh \
+  --restart unless-stopped \
+  danaildr/webssh:latest
+```
+
+Then open http://localhost:8080 in your browser.  
+**Default credentials:** `admin` / `admin`
+
+### With Persistent Data & Auto-Lock
+```bash
+docker run -d \
+  -p 8080:8080 \
+  -v webssh_data:/data \
+  -e WEBSSH_USERS=user1:pass1,user2:pass2 \
+  -e JWT_SECRET=your-256-bit-secret-here \
+  -e MAX_UPLOAD_SIZE=500M \
+  -e RECORDING_ENABLED=true \
+  -e RECORDING_RETENTION_DAYS=30 \
+  --name webssh \
+  --restart unless-stopped \
+  danaildr/webssh:latest
+```
+
+**Note:** Auto-lock and auto-disconnect settings are configured per connection in the connection settings modal.
+
+## Environment Variables
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `WEBSSH_USERS` | Comma-separated user:pass pairs | `admin:admin` | No |
+| `JWT_SECRET` | Secret for token signing | Auto-generated | Recommended |
+| `MAX_UPLOAD_SIZE` | Max file upload (e.g., `10M`, `1G`) | `100M` | No |
+| `RECORDING_ENABLED` | Enable session recording | `true` | No |
+| `RECORDING_RETENTION_DAYS` | Days to keep recordings | `30` | No |
+| `TZ` | Timezone | `UTC` | No |
+
+## Architecture
+
+This container uses Caddy as a reverse proxy to route traffic:
+- Port `8080` - Main entry point
+- `/ws` → WebSocket SSH server
+- `/api/*` → HTTP API (login, verify, SFTP operations)
+- Everything else → Static files (UI)
+
+Internal services (not exposed):
+- WebSocket SSH: port 8081
+- HTTP API: port 8082  
+- WebSocket SFTP: port 8083
+
+## Reverse Proxy Setup
+
+### Caddy
+```caddyfile
+your-domain.com {
+    reverse_proxy localhost:8080
+}
+```
+
+## Docker Compose
+
+```yaml
+services:
+  webssh:
+    image: danaildr/webssh:latest
+    container_name: webssh
+    restart: unless-stopped
+    ports:
+      - "8080:8080"
+    environment:
+      - WEBSSH_USERS=user1:pass1,user2:pass2
+      - JWT_SECRET=your-secret-key-here
+      - MAX_UPLOAD_SIZE=100M
+```
+
+## Security Notes
+
+⚠️ **Important for Production:**
+- **Change default credentials** - Set strong passwords via `WEBSSH_USERS`
+- **Set a strong `JWT_SECRET`** - Use at least 32 random characters
+- **Use HTTPS** - Configure reverse proxy with SSL/TLS (container handles HTTP internally)
+- **SSH host keys** - Uses `AutoAddPolicy()` by default; configure strict host key checking for production
+- **Session recordings** - Stored in `/data/recordings/` with metadata in SQLite database
+- **File uploads** - Limited by `MAX_UPLOAD_SIZE` (default 100MB)
+- **Volumes** - Mount `/data` for persistent storage of credentials and recordings
+
+## API
+
+- `POST /api/login` - Authenticate and get JWT token
+- `POST /api/verify` - Verify token validity  
+- `GET /api/connections` - List saved connections
+- `POST /api/connections` - Save a new connection
+- `GET /api/config` - Get server configuration
+- WebSocket: `/ws?token=<JWT>` - SSH terminal connection
+
+## Source
+
+https://github.com/danaildr/web-ssh
+
+## Tags
+
+- `latest` - Most recent stable build
+- `0.3.1` - Version-specific tag (Grouped recordings + Bulk operations + Multi-arch support)
+- `0.1.9` - Previous version
+
+Multi-arch: All tags support both `linux/amd64` and `linux/arm64`.