Webterminal 1.0 Docker Setup for Browser and Native Access

Webterminal 1.0 and the Legacy Django Repository

Webterminal addresses a specific access-control problem: bringing heterogeneous infrastructure connections under a controlled gateway while retaining records of what users did. Its intended users are system administrators, DevOps teams, database operators, and organizations that need a bastion or jump-host workflow. The README lists SSH, SFTP, Telnet, RDP, VNC, WinRM, MySQL, PostgreSQL, SQL Server, Oracle, Redis, MongoDB, and Kubernetes as supported connection types. Browser sessions use web terminals, in-browser RDP or VNC desktops, and browser file transfer. Native clients can use the built-in protocol proxies instead.

There is an important implementation distinction. The repository's primary language is Python, and its `requirements.txt` contains Django 3.1.7, Channels, Redis integration, Paramiko, Django REST framework, cryptography, and related packages. The Dockerfile also builds the older Python application with nginx, supervisor, guacamole-related ports, and an earlier service arrangement. However, the README explicitly says that the Python/Django source is the legacy implementation and directs users to `README_LEGACY.md` for its deployment and usage documentation.

The recommended product is Release 1.0, described as a ground-up rewrite with a Go backend, React frontend, nginx, and SQLite in one container. It does not require Redis for single-node deployments because state falls back to memory. The default `docker-compose.yml` in the repository still references `webterminal/webterminal:beta`, a separate `redis` service, and ports 80 and 2100. That makes the compose file unsuitable as a substitute for the documented 1.0 quick start unless you first reconcile the version and deployment model.

Authorization, Audit, and Session Routing in Webterminal

Webterminal models access around principals, assets, accounts, protocols, and actions. A principal can be a user, group, or department. The policy target is an asset or node paired with an account, protocol, and permitted actions such as connect, upload, download, clipboard access, or port forwarding. The README also states that access can have validity windows, approvals, and broader policies. This is more specific than merely placing a web terminal in front of a server because it gives administrators a place to define who may perform which operation on which resource.

Session control is built around audit history and replay. The README lists SSH, RDP, and VNC recording and replay, command filtering or blocking, and database SQL filtering. A session therefore has both an access decision and an audit record. The documentation also describes vaulted credentials, one-time connection tokens, and license binding to a host fingerprint. Those are stated security features, but the README does not document the underlying key-management procedure, token lifetime, or exact configuration for each policy, so those details should be verified before deployment.

Network routing can either connect directly to an asset or pass through lightweight `gw-*` gateway agents over encrypted tunnels. The documented resolution path is asset to node to direct. Gateway agents are installed with a one-line command generated on the Gateways page, and the README states that the installation uses SHA-256 verification and host-key pinning. This design is useful when a target network segment cannot be reached directly from the main Webterminal service. It also adds a deployment dependency: the gateway agent and its host identity become part of the operational path.

Running the Recommended Webterminal 1.0 Container

The README gives a Docker quick start for the all-in-one 1.0 image. The command creates a named container, persists `/data`, publishes the HTTPS console and the native proxy ports, and starts the image with an automatic restart policy. Port 80 is recommended for redirection, while port 443 is required. Publish only the native proxy ports needed by the protocols you use. After startup, open `https://<host-ip>`, complete the initialization wizard, and sign in as `admin` with the password entered during setup. A self-signed certificate is generated on first start.

docker run -d --name webterminal --restart unless-stopped \
  -p 443:443 -p 80:80 \
  -p 2222:2222 -p 3389:3389 \
  -p 13306:13306 -p 15432:15432 -p 11433:11433 -p 11521:11521 \
  -p 16379:16379 -p 37017:37017 \
  -v webterminal-data:/data \
  webterminal/webterminal:1.0

The expected first result is an HTTPS service that redirects port 80 to port 443 and presents the initialization wizard. The native proxy listeners do not start until initialization completes. The README says that `443` carries web-side functionality, while `2222`, `3389`, and the database ports are native-client proxies. The example publishes more ports than are required for a small installation. Removing unused mappings reduces exposed surface and avoids confusion about which endpoints are intended for browser access and which are for clients such as `ssh`, `mstsc`, `mysql`, or `navicat`.

The persistent volume is not optional in the documented deployment model. It contains SQLite, configuration, TLS certificates, the SSH host key, session recordings, and logs. The README says that archiving this volume is the backup procedure. This is a simple upgrade path, but it also makes the volume the central state boundary for the installation.

Host Identity, License Limits, and Upgrade Boundaries

Linux installations that use online trial registration must expose two host identity files. The README says to mount `/host/machine-id` and `/host/product_uuid` as read-only paths. These files are used for online trial registration and license binding, not as ordinary application data.

  -v /etc/machine-id:/host/machine-id:ro \
  -v /sys/class/dmi/id/product_uuid:/host/product_uuid:ro

The license behavior has operational consequences. A default installation is Community edition, with 50 restricted-protocol assets, five concurrent restricted sessions, one replica, and one gateway. SSH-type assets are not limited by that Community restriction. A 15-day online trial is described for Enterprise features when the Linux identity mounts are available. Docker Desktop on macOS or Windows, and hosts without a stable fingerprint, use an offline request-code and license-file flow instead. Commercial Enterprise licenses can specify asset count, session concurrency, replicas, and gateways.

On expiry or a limit breach, the README says security-policy features become read-only while auditing keeps working. That behavior should be tested against the organization's requirements, especially if a loss of policy-edit capability is unacceptable during renewal. The README also states that Enterprise licenses are bound to the installation. A replacement host, changed fingerprint, or rebuilt environment may therefore require a new licensing operation, although the exact transfer procedure is not documented.

For upgrades, pull a new image tag and recreate the container. The README says data carries over. The repository was not archived, and its last push was on 2026-10-15. Separately, the README states that the Python/Django source in this repository is no longer maintained, so the source tree and the recommended 1.0 image should not be treated as the same maintenance surface.

Webterminal Limitations and the Django Compose Mismatch

The main limitation is the gap between the repository layout and the documented product. The source tree contains Python/Django components, a Dockerfile based on Python 3.9.2, `requirements.txt`, `manage.py`, and a compose file using `webterminal/webterminal:beta`, Redis, and guacamole/guacd:0.9.14. The README instead recommends a different 1.0 deployment centered on a Go backend, React frontend, SQLite, and one all-in-one image. A developer who starts from the repository's Dockerfile will not be following the documented 1.0 quick start.

The single-node 1.0 design also has a clear boundary. SQLite and in-memory fallback remove external dependencies for a single-node installation, but the documentation does not describe a horizontal scaling procedure, database migration path, or external Redis requirement for a multi-replica deployment. Enterprise licensing mentions replicas, yet the architecture details needed to operate them are not in the README. The community limits also mean that a large RDP, VNC, or database estate may exceed the default restricted-protocol allowance.

A real alternative is to use separate native access tooling for each protocol and rely on the host system's SSH keys, network controls, and database permissions. That approach avoids a centralized Webterminal deployment, but it also does not provide Webterminal's documented unified authorization model, browser workspace, session recording, command filtering, SQL filtering, or replay history. Another alternative is the repository's earlier Django implementation, but the README labels that implementation legacy and no longer maintained, so it offers less attractive upgrade expectations than the recommended image.

Operational Checks for a Webterminal Evaluation

A first evaluation should begin with the console endpoint and the initialization wizard, then verify one SSH asset and one audit record before adding databases or remote desktops. The README says that proxy ports begin listening only after initialization, which gives a concrete readiness check: open the HTTPS console, complete the wizard, then confirm that only the intended published proxy ports accept connections. The port list is concrete: 2222 for native SSH or SFTP, 3389 for native RDP, 13306 for MySQL, 15432 for PostgreSQL, 11433 for SQL Server, 11521 for Oracle, 16379 for Redis, and 37017 for MongoDB.

If Docker publishes a container port on a different host port, the README gives a specific correction. Declare the public endpoint using `BASTION_PUBLIC_HOST` or `BASTION_SSH_PROXY_PORT`, and it gives `BASTION_SSH_PROXY_PORT=12222` as the example for mapping host port 12222 to container port 2222. Without this setting, generated `wterm://` URLs can point to the wrong endpoint. That check is more useful than assuming that the container port and the host port are identical.

Before operating the service beyond a trial, inspect the Community limits, confirm whether SSH-type assets match the intended estate, and review the license renewal path. Also back up the named volume rather than only the container filesystem. For the older Python source, review `README_LEGACY.md` before changing dependencies or deployment commands. The repository's `requirements.txt` and Dockerfile describe that legacy path, while the current README explicitly directs production consideration toward the 1.0 image.

Editorial conclusion

Administrators who need browser-based or native-client access through a single audit gateway should evaluate the Webterminal 1.0 image, especially when a single-node SQLite deployment is acceptable. Organizations needing the older Python/Django application, horizontal scale, or unrestricted Community-edition capacity should verify edition limits, gateway requirements, and persistent storage before adopting it. The first project-specific checks are the native proxy ports, the `/data` backup path, and whether the required protocols fit the Community or Enterprise license.

Frequently asked questions

Official sources

1. jimmy201602/webterminal on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases