# WebVirtCloud for Browser-Based KVM Management

> WebVirtCloud gives administrators and delegated users a Django interface for managing KVM domains, storage, networks, consoles, and libvirt resources. It supports multi-host administration, but its documented scope is limited to QEMU/KVM and its licensing remains unspecified.

**retspen/webvirtcloud** — WebVirtCloud is virtualization web interface for admins and users

- Repository: https://github.com/retspen/webvirtcloud
- Stars: 1,879 · Forks: 399
- Language: JavaScript
- License: not declared
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/retspen-webvirtcloud

## WebVirtCloud's KVM Administration Scope

WebVirtCloud addresses the gap between direct libvirt administration and browser access for people who should not manage the hypervisor host itself. Its documented audience includes administrators and ordinary users. Administrators can connect the interface to multiple QEMU/KVM hypervisors, while role-based permissions can delegate selected virtual machines to users. This is delegation of management functions, not a general endpoint security product and not a replacement for host-level operating system administration.

The project focuses on KVM. Its listed management coverage includes creating, deleting, and updating QEMU/KVM instances, viewing real-time hypervisor and instance statistics, managing storage pools and volumes, and handling networks and interfaces. A user can reach a guest through a browser-based noVNC or SPICE console. The interface also exposes cloud-init datasource support, SSH public-key and root-password operations for instances, authentication, two-factor authentication with OTP, and a REST API documented through OpenAPI 3.0 with Swagger and ReDoc.

That feature set makes WebVirtCloud most relevant to a virtualization team that has standardized on libvirt and needs a control panel shared by staff or tenant-like users. A single administrator working from the command line may gain little from the additional Django application, database, reverse proxy, and process supervision involved in running it. Likewise, the documented KVM restriction rules out an immediate fit for environments centered on VMware, Xen, or Hyper-V.

## Libvirt, Django, and Browser Console Data Flow

The repository layout separates the Django interface into application areas such as `accounts/`, `computes/`, `instances/`, `interfaces/`, `networks/`, `storages/`, `virtsecrets/`, and `console/`. The README identifies libvirt as the management layer for hypervisors, domains, networks, storage, and related resources. The application is therefore not implementing a virtualization stack of its own. It presents and authorizes operations against libvirt resources.

User actions pass through the web interface to libvirt-backed management functions. The project also includes a `console/` directory and separate `novncd` service definitions in the Supervisor examples. The documented browser consoles are noVNC and SPICE, with the Docker deployment publishing port 6080 for noVNC access. This separation matters operationally: the panel can be served through Nginx while the console process and guest-facing graphics path have their own service boundary.

Authentication and permissions are part of the application layer. The feature list includes user authorization, authentication, OTP-based two-factor authentication, and actions that modify root credentials or install an SSH public key inside an instance. Those capabilities carry real host-integration consequences. The README does not document granular permission matrices, credential rotation procedures, audit-log retention, or the exact transport security configuration used for every deployment path. The existence of OpenAPI documentation confirms an API surface, but the README does not describe its authentication flow or rate limits.

## Docker Compose as the First WebVirtCloud Deployment

The quickest documented starting point is Docker Compose. It builds the repository's `Dockerfile`, publishes the panel on port 80 and noVNC on port 6080, and persists both runtime data and compute-node SSH keys. Clone the repository and start the defined services with:

```bash
git clone https://github.com/retspen/webvirtcloud
cd webvirtcloud

docker compose up -d
```

The repository defines the service as `webvirtcloud`, uses the image name `webvirtcloud:latest`, and sets `restart: unless-stopped`. After startup, the README directs the user to `http://<server-ip>` for the panel and port 6080 for the noVNC console. Replace `<server-ip>` with the address of the deployment host. Do not infer that either endpoint is suitable for public exposure without checking the reverse proxy, authentication, and network requirements in the chosen environment.

The Compose file creates two named volumes. `webvirtcloud-data` maps to `/srv/webvirtcloud/data` for the persistent SQLite database and runtime data. `webvirtcloud-ssh` maps to `/var/www/.ssh` for SSH keys used by compute-node authentication. Losing either volume means losing the corresponding local state or credentials, so backups need to cover both. The service environment sets `TZ=UTC`; `SECRET_KEY` and `CSRF_TRUSTED_ORIGINS` are optional commented settings. If `SECRET_KEY` is unset, the Compose file states that it is generated at first launch. The exact first-launch account creation process is not documented in the README, so installation should not be treated as complete merely because both ports answer.

## Native Installation Constraints on Ubuntu, RHEL, and SUSE

A native installation requires more platform work because WebVirtCloud depends on Python bindings and libraries associated with libvirt, XML processing, LDAP, cryptography, and guest filesystem access. The README identifies Python 3.10 through 3.12 with Django 4.2 LTS. Its platform sections are not uniform: Ubuntu and Debian use `apt-get`, RHEL-family systems use `dnf`, and openSUSE and SLES use `zypper`. That variation is a real upgrade cost, since dependency commands, Supervisor paths, service names, and security settings differ by distribution.

For Debian and Ubuntu, the documented sequence installs system prerequisites, clones the repository into `/srv/webvirtcloud`, creates `webvirtcloud/settings.py` from `webvirtcloud/settings.py.template`, generates `SECRET_KEY`, and installs Python dependencies from `conf/requirements.txt`. The key configuration step is:

```bash
cp webvirtcloud/settings.py.template webvirtcloud/settings.py
SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(50))')
sed -i "s|^SECRET_KEY = .*|SECRET_KEY = \"${SECRET_KEY}\"|" webvirtcloud/settings.py
```

This writes a generated secret into the local settings file. The file is not shown as a persistent deployment volume in the Compose configuration, and the README does not document secret rotation or backup for a native installation. After configuration, a minimal documented application preparation sequence is:

```bash
python3 -m venv --system-site-packages venv
source venv/bin/activate
pip install -r conf/requirements.txt

python3 manage.py migrate
python3 manage.py collectstatic --noinput
```

The Debian path copies Nginx and Supervisor configurations, changes ownership to `www-data`, and restarts both services. The RHEL path runs Gunicorn and `novncd` as the `nginx` user and includes SELinux and firewall commands. The README's openSUSE and SLES section ends at its Nginx and Supervisor configuration heading, so it does not provide a complete native first-use tutorial for that platform.

## Operational Boundaries and Upgrade Exposure

WebVirtCloud is the wrong tool when a deployment does not use QEMU/KVM, because KVM is the only supported hypervisor stated in the README. It is also unsuitable as a standalone replacement for libvirt host management. Administrators still need working libvirt access, compatible compute hosts, suitable networks, and the storage configuration required by each domain. The interface cannot create infrastructure prerequisites that the operating system and hypervisor do not provide.

Native deployments add several maintenance surfaces: Django application code, Python packages in `conf/requirements.txt`, Nginx, Supervisor or `supervisord`, the noVNC process, libvirt connectivity, and SQLite runtime data. Container deployment reduces host-level configuration work but does not remove application or credential maintenance. The Compose configuration defines an image tag built from the repository, not a dated upstream release. The listed release history contains `v1.0`, dated 2015-10-02, while the repository's last push was on 2026-09-25 and it is not archived. The recent push does not by itself establish a stable upgrade path or compatibility policy.

The license is listed as unknown, and the repository entries do not include a license file. That is a direct adoption blocker for organizations that require an approved software license before deployment. Public GitHub access does not establish permission to copy, modify, or redistribute source. Maintainers or the deploying organization's legal process must identify the applicable terms before deployment. The README also does not document database rollback, version-to-version migration policy, or a supported upgrade command, so an upgrade cannot be treated as routine.

## WebVirtCloud Versus Direct libvirt Administration

The closest documented alternative is direct use of the libvirt API and native host administration tools rather than WebVirtCloud. Direct libvirt management keeps the operating model close to the hypervisor: clients issue API calls to the compute host, and administrators control host configuration outside the application. This avoids adding a Django control plane, delegated web accounts, a SQLite database, Nginx, Supervisor processes, and a separate noVNC service to the management stack.

WebVirtCloud changes the approach by adding an account-based web interface, role-based permissions, delegated virtual-machine operations, browser consoles, OTP support, and OpenAPI documentation. That is useful when several people need scoped access without direct host administration. It also concentrates responsibility in an application whose permissions and operational behavior must be configured and secured correctly. Direct libvirt administration is more appropriate for a small team with established host tooling; WebVirtCloud is more appropriate when browser delegation and a policy-based user layer are explicit requirements.

The project also lists a REST API, but that does not eliminate the decision. A team needing only scripted libvirt calls may prefer the lower layer directly. A team requiring a human-facing management panel can use the REST surface alongside WebVirtCloud rather than building all of the listed interface behavior itself. The README does not provide enough API authentication details to estimate that integration, so the first verification point is the generated OpenAPI documentation in the deployed instance.

## Conclusion

Administrators who already operate QEMU/KVM through libvirt and want a delegated browser interface should adopt WebVirtCloud after checking Python, OS, storage, network, and SSH access requirements. Organizations needing non-KVM hypervisors, documented upgrade procedures, or a clearly identified open source license should not select it yet. Verify first that `docker compose up -d` exposes ports 80 and 6080 on the intended host, then confirm that every planned compute host is reachable with the authentication method required by the deployment.

## FAQ

### Which hypervisors does WebVirtCloud support?

The README states that KVM is currently the supported hypervisor and describes QEMU/KVM instance, storage, network, statistics, and console management.

### How do I install WebVirtCloud with Docker Compose?

Clone the repository, enter its directory, and run `docker compose up -d`. The documented panel URL is `http://<server-ip>`, while noVNC uses port 6080.

### What data does the WebVirtCloud Docker Compose deployment preserve?

The `webvirtcloud-data` volume preserves SQLite database and runtime data under `/srv/webvirtcloud/data`. The `webvirtcloud-ssh` volume preserves SSH keys under `/var/www/.ssh`.

### Does WebVirtCloud have a documented license?

No. The repository information lists the license as unknown, and the top-level repository entries do not identify a license file.

## Sources

- [Issues](https://github.com/retspen/webvirtcloud/issues)
- [README](https://github.com/retspen/webvirtcloud/blob/master/README.md)
- [Releases](https://github.com/retspen/webvirtcloud/releases)
- [retspen/webvirtcloud on GitHub](https://github.com/retspen/webvirtcloud)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/retspen-webvirtcloud