- modernize packages and rust edition. - increase timeout for rollout -
increment cargo version
This commit is contained in:
@@ -1,31 +1,217 @@
|
||||
# webterm
|
||||
web terminal based on xterm.js in rust
|
||||
# Socktop WebTerm
|
||||
|
||||
A web-based terminal using xterm.js and Rust, part of the Socktop project.
|
||||
|
||||
|
||||
|
||||
# Is it any good?
|
||||
[Yes.](https://news.ycombinator.com/item?id=3067434)
|
||||
## About
|
||||
|
||||
# How does it work?
|
||||
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.
|
||||
|
||||
There is a rust backend based [Actix], consisting of two actors:
|
||||
* `Websocket` implements a websocket that speaks the [Terminado] protocol
|
||||
* `Terminal` handles communication to a child spawned on a PTY using [tokio-pty-process].
|
||||
## Features
|
||||
|
||||
The frontend is a static HTML page served by [actix-web][Actix] providing an [xterm.js] UI.
|
||||
- 🖥️ 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
|
||||
|
||||
[Actix]: https://actix.rs
|
||||
[Terminado]: https://github.com/jupyter/terminado
|
||||
[tokio-pty-process]: https://crates.io/crates/tokio-pty-process
|
||||
[xterm.js]: https://xtermjs.org/
|
||||
## Architecture
|
||||
|
||||
# Local development
|
||||
```
|
||||
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:8080/` to see it in action!
|
||||
|
||||
# Should I run this on the internet?
|
||||
Then head to `http://localhost:8082/` to see it in action!
|
||||
|
||||
Probably not. It lets anyone who can access the webpage control your system.
|
||||
### 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
|
||||
|
||||
Reference in New Issue
Block a user