Web Shell

Secure browser-based terminal built on our Debian base image with ttyd for web terminal access. Includes common DevOps and hosting tools, optional SSH server, and flexible authentication options.

Quick Start

# Pull the image
docker pull ghcr.io/oorabona/web-shell:latest

# Run with default settings (web terminal on port 7681)
docker run -d --name web-shell -p 7681:7681 ghcr.io/oorabona/web-shell:latest

# Open in browser
# http://localhost:7681

# Run with password and SSH enabled
docker run -d --name web-shell \
  -p 7681:7681 -p 2222:2222 \
  -e SHELL_PASSWORD=mysecretpass \
  -e ENABLE_SSH=true \
  ghcr.io/oorabona/web-shell:latest

Build

# Build with latest upstream ttyd version
./make build web-shell

# Build with specific ttyd version
./make build web-shell 1.7.7

Build Args

Environment Variables

Ports

Included Tools

Authentication

No Authentication (default)

Anyone with network access can use the terminal. Suitable for local development or behind a trusted reverse proxy.

Basic Auth (ttyd built-in)

docker run -d -p 7681:7681 \
  -e TTYD_CREDENTIAL="admin:secretpass" \
  ghcr.io/oorabona/web-shell:latest

TLS Encryption

docker run -d -p 7681:7681 \
  -v /path/to/cert.pem:/certs/cert.pem:ro \
  -v /path/to/key.pem:/certs/key.pem:ro \
  -e TTYD_SSL_CERT=/certs/cert.pem \
  -e TTYD_SSL_KEY=/certs/key.pem \
  ghcr.io/oorabona/web-shell:latest

Reverse Proxy Auth Header

For integration with authentication proxies (OAuth2 Proxy, Authelia, etc.):

docker run -d -p 7681:7681 \
  -e TTYD_AUTH_HEADER="X-Forwarded-User" \
  ghcr.io/oorabona/web-shell:latest

SSH Access

docker run -d -p 7681:7681 -p 2222:2222 \
  -e ENABLE_SSH=true \
  -e SSH_PUBLIC_KEY="ssh-ed25519 AAAA... user@host" \
  ghcr.io/oorabona/web-shell:latest

# Connect via SSH
ssh -p 2222 debian@localhost

Health Check

Built-in health check via ttyd token endpoint:

GET http://localhost:7681/token → {"token": "..."}

Hosting Use Case

Web Shell is designed as a building block for web hosting platforms, providing browser-based terminal access to container environments. Combined with other containers from this project:

┌──────────────────────────────────────────────────────────┐
│  Client Browser                                          │
│  ┌───────────┐  ┌────────────┐  ┌──────────────────┐    │
│  │ Web App   │  │ phpMyAdmin │  │ Web Terminal      │    │
│  │ :80/:443  │  │ :8080      │  │ :7681 (ttyd)     │    │
│  └─────┬─────┘  └─────┬──────┘  └──────┬───────────┘    │
└────────┼───────────────┼────────────────┼────────────────┘
         │               │                │
┌────────┼───────────────┼────────────────┼────────────────┐
│  ┌─────▼─────┐  ┌──────▼─────┐  ┌──────▼───────────┐    │
│  │ OpenResty │  │ PHP-FPM    │  │ Web Shell         │    │
│  │ (proxy)   │  │ WordPress  │  │ (tools + shell)   │    │
│  └───────────┘  └────────────┘  └──────────────────┘    │
│  ┌───────────┐  ┌────────────┐                           │
│  │ PostgreSQL│  │ Vector     │                           │
│  │ (database)│  │ (logs)     │                           │
│  └───────────┘  └────────────┘                           │
│  Docker Host                                             │
└──────────────────────────────────────────────────────────┘

Security Considerations

• Runs as root for chpasswd and sshd, but ttyd spawns shells as the configured SHELL_USER
• Default password is changeme — always override with SHELL_PASSWORD
• SSH listens on port 2222 (non-standard) with root login disabled
• For production: use TTYD_CREDENTIAL or place behind an auth reverse proxy
• Mount TLS certificates for encrypted connections
• The --writable flag enables terminal input — remove for read-only sessions

Dependencies

Links

• ttyd GitHub
• ttyd Wiki
• WebSocket Terminal Protocol
• Debian Base Image