OpenVLE
OpenVLE is operated as a Docker Compose stack and includes all required services in a single repository. A single docker compose up -d starts the entire application.
Architecture
The Docker Compose stack consists of the following services:
| Service | Function |
|---|---|
backend | Python/FastAPI — API server, business logic |
frontend | Vue.js/Nginx — Web interface |
worker | RQ Worker — asynchronous background tasks (VM operations, email sending, etc.) |
scheduler | RQ Scheduler — periodic tasks (node info updates, etc.) |
mariadb | MariaDB — relational database for core entities |
mongodb | MongoDB — document database for activities and logs |
redis | Redis — task queue and cache for worker/scheduler |
Prerequisites
- Docker and Docker Compose installed
- Proxmox VE set up (required for VM management)
- An SMTP server for sending emails (have credentials ready)
- Optional: Apache Guacamole for remote desktop access
Installation
Download repository
Download the docker-compose.yml and .env.sample files from the official repository:
mkdir openvle && cd openvle
curl -fsSLO https://raw.githubusercontent.com/inettgmbh/openvle/main/docker-compose.yml
curl -fsSL -o .env https://raw.githubusercontent.com/inettgmbh/openvle/main/backend/.env.sample
curl -fsSL -o frontend.env https://raw.githubusercontent.com/inettgmbh/openvle/main/frontend/.env.sample
Pull Docker images
docker compose pull
Configuration
OpenVLE uses two configuration files at root level: .env for backend, workers, scheduler, and Compose variable interpolation, and frontend.env for the frontend runtime configuration.
Backend (.env)
First, generate secure, random passwords and secrets for all security-relevant variables:
sed -i \
-e "s|AUTH_SECRET = \"\"|AUTH_SECRET = \"$(openssl rand -hex 32)\"|" \
-e "s|SESSION_SECRET_TOKEN = \"\"|SESSION_SECRET_TOKEN = \"$(openssl rand -hex 32)\"|" \
-e "s|MARIADB_PASSWORD = \"project\"|MARIADB_PASSWORD = \"$(openssl rand -hex 16)\"|" \
-e "s|MARIADB_ROOT_PASSWORD = \"root\"|MARIADB_ROOT_PASSWORD = \"$(openssl rand -hex 16)\"|" \
-e "s|MONGODB_PASSWORD = \"project\"|MONGODB_PASSWORD = \"$(openssl rand -hex 16)\"|" \
-e "s|REDIS_PASSWORD = \"password\"|REDIS_PASSWORD = \"$(openssl rand -hex 16)\"|" \
.env
This command replaces the default passwords once with random values. Run it only once — running it again would have no effect since the already-set values would no longer match the defaults. Back up the generated .env afterwards, as the passwords cannot be recovered.
If you prefer not to use the sed command, you must manually set the following variables to secure values: AUTH_SECRET, SESSION_SECRET_TOKEN, MARIADB_PASSWORD, MARIADB_ROOT_PASSWORD, MONGODB_PASSWORD, REDIS_PASSWORD. The default values in the .env.sample are insecure and must not be used in production.
MARIADB_ROOT_PASSWORD is only needed during the initial start — MariaDB adopts the password during its first initialization and stores it in the database. After the first successful start, you can remove the variable from .env and instead store the password in a secure location (e.g., a password manager) in case you need it for maintenance or troubleshooting.
Next, edit .env and set the remaining environment-specific variables:
CORS
| Variable | Description | Example |
|---|---|---|
CORS_ORIGINS | Allowed origins for CORS requests (URL of the frontend) | ["https://openvle.example.com"] |
Proxmox VE — Credentials from the Proxmox VE Integration
| Variable | Description | Example |
|---|---|---|
PVE_HOSTNAME | Hostname and port of the Proxmox server | "proxmox.example.com:8006" |
PVE_USER | Proxmox user | "OpenVLE@pve" |
PVE_TOKEN_NAME | Name of the API token | "prod01" |
PVE_TOKEN_VALUE | Secret value of the API token | "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" |
PVE_FQDN | FQDN of the Proxmox server | "proxmox.example.com:8006" |
PVE_VMS_POOL | Proxmox pool for managed VMs | "OpenVLE-VMs" |
PVE_VM_SUBNET | Subnet for VMs | "10.1.1.0/24" |
Email / SMTP
| Variable | Description | Example |
|---|---|---|
SMTP_HOST | SMTP server | "mail.example.com" |
SMTP_PORT | SMTP port | 465 |
SMTP_METHOD | Connection method | "ssl" |
SMTP_USERNAME | SMTP username | "openvle@example.com" |
SMTP_PASSWORD | SMTP password | "smtp-password" |
SMTP_FROM_MAIL | Sender address | "openvle@example.com" |
SMTP_FROM_NAME | Sender display name | "OpenVLE" |
The variables must be enclosed in quotation marks (" "), otherwise parsing errors will occur at startup.
The table above shows only the required variables. For optional settings (Guacamole, LDAP, OIDC, Moodle, Sentry, etc.) see the Configuration reference.
Frontend (frontend.env)
For the frontend, you only need to set the backend URL:
VITE_BACKEND_URL='https://openvle.example.com/v1'
Additional optional frontend variables (e.g., Sentry) can be found in the Configuration reference.
Start containers
docker compose up -d
Docker automatically creates all necessary directories, initializes the databases, and starts all services.
On the first start, the backend automatically runs the database migration. This may take a few minutes. Wait until all containers reach the healthy status before proceeding.
Network and ports
In the default docker-compose.yml, only two ports are exposed externally:
| Service | Port | Binding |
|---|---|---|
frontend | 80 | 0.0.0.0:80 |
backend | 8000 | 0.0.0.0:8000 |
All other containers (MariaDB, MongoDB, Redis, Worker, Scheduler) communicate exclusively internally via the Docker network and do not expose any ports — and it should stay that way.
When a reverse proxy is used (recommended), the port exposures for frontend and backend in the docker-compose.yml can be removed or restricted to 127.0.0.1, since all external access is then handled centrally through the reverse proxy. Example:
ports:
- 127.0.0.1:80:80 # only locally accessible
- 127.0.0.1:8000:8000
Default administrator
After the first successful start, a default administrator account is automatically created:
| Username | openvle |
| Password | openvle |
Change the default administrator password immediately after the first login. Then create a personal account for each administrator and disable or delete the default account once the individual accounts are set up.
Verification
Check container status
docker ps -a
All 7 containers should have the status Running (healthy).
Check logs
docker logs openvle-backend 2>&1 | head -50
The logs should show no error messages and confirm a successful database connection.
Test API access
Retrieve the system settings via the API:
curl -s https://openvle.example.com/v1/system/settings | head -20
A JSON response with the current settings confirms that the backend and reverse proxy are correctly configured. An empty or erroneous response indicates a configuration problem.
Check web interface
Open https://openvle.example.com in your browser. The login page should be displayed.
Troubleshooting
| Problem | Solution |
|---|---|
| Container does not start | Check the logs using docker logs <container-name>. More information at Logs. |
| Database error on startup | Make sure the MariaDB and MongoDB variables in .env are set correctly. See Configuration reference. |
| Health check fails | Wait a few minutes — the initial database migration may take longer on the first start. |
| Web interface not reachable | Make sure the frontend container is running and the reverse proxy is correctly configured. |
| API calls fail | Check CORS_ORIGINS in .env — it must contain the URL of the frontend. |
| Email sending does not work | Check the SMTP variables in .env and test the connection to the SMTP server. |
| Proxmox connection fails | Check PVE_HOSTNAME, PVE_USER, PVE_TOKEN_NAME, and PVE_TOKEN_VALUE. See Proxmox VE Integration. |