136 lines
4.9 KiB
Markdown
136 lines
4.9 KiB
Markdown
# WebSSH - Browser-based SSH Client
|
|
|
|
[](https://hub.docker.com/r/danaildr/webssh)
|
|
[](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.4.0` - 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`.
|