218 lines
6.8 KiB
Markdown
218 lines
6.8 KiB
Markdown
# Socktop WebTerm
|
|
|
|
A web-based terminal using xterm.js and Rust, part of the Socktop project.
|
|
|
|
|
|
|
|
## About
|
|
|
|
This is a modern web terminal server that provides browser-based terminal access with WebSocket support. It's built with Rust using the Actix-Web framework and xterm.js for the frontend.
|
|
|
|
## Features
|
|
|
|
- 🖥️ Full-featured terminal emulation via xterm.js
|
|
- 🔌 WebSocket-based communication using the Terminado protocol
|
|
- 🚀 High-performance Rust backend
|
|
- ⚡ Zero-downtime rolling deployments via CI/CD
|
|
- 🐳 Containerized deployment with Docker
|
|
- ☸️ Kubernetes/k3s ready with automated deployments
|
|
|
|
## Architecture
|
|
|
|
The application consists of two main components:
|
|
|
|
### Backend (Rust)
|
|
- **Websocket Actor**: Implements WebSocket communication using the [Terminado](https://github.com/jupyter/terminado) protocol
|
|
- **Terminal Actor**: Manages PTY communication with spawned processes using [portable-pty](https://crates.io/crates/portable-pty)
|
|
- **Actix-Web Server**: Serves static files and handles HTTP/WebSocket routing
|
|
|
|
### Frontend
|
|
- **xterm.js**: Provides the terminal UI in the browser
|
|
- **Static Assets**: HTML, CSS, and JavaScript served by Actix-Web
|
|
|
|
## Prerequisites
|
|
|
|
- Rust 1.90+ (2021 edition)
|
|
- Node.js and npm (for xterm.js dependencies)
|
|
- Docker (optional, for containerized deployment)
|
|
- Kubernetes/k3s (optional, for orchestrated deployment)
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://gt.wittyoneoff.com/jason/socktop-webterm
|
|
cd socktop-webterm
|
|
|
|
# Install npm dependencies
|
|
npm install
|
|
|
|
# Verify setup (optional but recommended)
|
|
./check-setup.sh
|
|
|
|
# Build and run
|
|
cargo build
|
|
cargo run
|
|
```
|
|
|
|
Then head to `http://localhost:8082/` to see it in action!
|
|
|
|
### Setup Verification
|
|
|
|
Before running the server, you can verify that all required files and dependencies are in place:
|
|
|
|
```bash
|
|
./check-setup.sh
|
|
```
|
|
|
|
This will check for:
|
|
- Required directories (static, templates, node_modules)
|
|
- Critical files (templates, JavaScript, CSS)
|
|
- xterm.js installation
|
|
- Build tools (cargo, npm)
|
|
|
|
**Note**: The server must be run from the project root directory, as it expects `./static`, `./templates`, and `./node_modules` to be accessible in the current working directory.
|
|
|
|
### Command Line Options
|
|
|
|
```bash
|
|
webterm-server --help
|
|
```
|
|
|
|
Options:
|
|
- `-p, --port <PORT>` - The port to listen on (default: 8082)
|
|
- `-H, --host <HOST>` - The host or IP to listen on (default: localhost)
|
|
- `-c, --command <COMMAND>` - The command to execute (default: /bin/sh)
|
|
|
|
Example:
|
|
```bash
|
|
cargo run -- --port 8080 --host 0.0.0.0 --command /bin/bash
|
|
```
|
|
|
|
## Production Deployment
|
|
|
|
### Docker
|
|
|
|
```bash
|
|
# Build the image
|
|
docker build -t socktop-webterm:latest .
|
|
|
|
# Run the container
|
|
docker run -d -p 8082:8082 socktop-webterm:latest
|
|
```
|
|
|
|
### Kubernetes/k3s
|
|
|
|
Automated deployment via Gitea Actions CI/CD:
|
|
|
|
1. Push to `main` branch
|
|
2. Workflow automatically builds arm64 image
|
|
3. Image tagged with version from `Cargo.toml`
|
|
4. Deployed to k3s cluster with zero-downtime rolling update
|
|
|
|
See `.gitea/workflows/build-and-deploy.yaml` for the complete workflow.
|
|
|
|
Manual deployment:
|
|
```bash
|
|
kubectl apply -f kubernetes/
|
|
```
|
|
|
|
## CI/CD Pipeline
|
|
|
|
This project includes a complete CI/CD pipeline using Gitea Actions:
|
|
|
|
- **Automatic builds** on every push to main/master
|
|
- **Version tagging** from Cargo.toml
|
|
- **Container registry** integration
|
|
- **Automated k3s deployment** with rolling updates
|
|
- **Zero downtime** deployments
|
|
|
|
For setup instructions, see:
|
|
- [Getting Started Guide](GETTING-STARTED-CI-CD.md)
|
|
- [CI/CD Overview](CI-CD-OVERVIEW.md)
|
|
- [Quick Reference](.gitea/QUICKSTART.md)
|
|
|
|
## Technology Stack
|
|
|
|
- **Backend**: Rust 2021, Actix-Web 4.x, Actix 0.13, portable-pty
|
|
- **Frontend**: xterm.js, HTML5, CSS3
|
|
- **Templating**: Handlebars 6.x
|
|
- **CLI**: clap 4.x
|
|
- **Async Runtime**: Tokio 1.x
|
|
- **Containerization**: Docker, Kubernetes/k3s
|
|
- **CI/CD**: Gitea Actions
|
|
|
|
## Security Considerations
|
|
|
|
⚠️ **Warning**: This application provides shell access to anyone who can access the web interface. It is intended for use in controlled environments only. Only run in Run in isolated containers/namespaces.
|
|
|
|
## Credits
|
|
|
|
### Original Author
|
|
This project is a fork of [webterm](https://github.com/fubarnetes/webterm) originally created by:
|
|
- **Fabian Freyer** (fabian.freyer@physik.tu-berlin.de)
|
|
|
|
### Socktop Enhancements
|
|
Modernized and enhanced for the Socktop project by:
|
|
- **Jason Witty** (jasonpwitty+socktop@proton.me)
|
|
|
|
#### Major Changes from Original
|
|
- Updated to Rust 2021 edition
|
|
- Modernized dependencies (Actix-Web 1.x → 4.x, Tokio 0.1 → 1.x)
|
|
- Replaced deprecated `tokio-pty-process` with `portable-pty`
|
|
- Added automated CI/CD pipeline with Gitea Actions
|
|
- Containerized deployment with Docker
|
|
- Kubernetes/k3s orchestration support
|
|
- Added idle session timeout (5 minutes)
|
|
- Improved error handling and logging
|
|
- Modern CLI with clap instead of structopt
|
|
- Updated to latest xterm.js
|
|
|
|
## License
|
|
|
|
This project is licensed under the **BSD 3-Clause License** - see below:
|
|
|
|
```
|
|
Copyright (c) 2019 Fabian Freyer
|
|
Copyright (c) 2024 Jason Witty
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
|
|
1. Redistributions of source code must retain the above copyright notice,
|
|
this list of conditions and the following disclaimer.
|
|
|
|
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
this list of conditions and the following disclaimer in the documentation
|
|
and/or other materials provided with the distribution.
|
|
|
|
3. Neither the name of the copyright holder nor the names of its contributors
|
|
may be used to endorse or promote products derived from this software
|
|
without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
POSSIBILITY OF SUCH DAMAGE.
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit pull requests or open issues.
|
|
|
|
## Links
|
|
|
|
- **Repository**: https://gt.wittyoneoff.com/jason/socktop-webterm
|
|
- **Original Project**: https://github.com/fubarnetes/webterm
|
|
- **xterm.js**: https://xtermjs.org/
|
|
- **Actix-Web**: https://actix.rs
|
|
- **portable-pty**: https://crates.io/crates/portable-pty
|