jhmmt/pvmss repository overview

⁠Proxmox VM Self-Service (PVMSS)

PVMSS is a lightweight, self-service web portal for Proxmox Virtual Environment (PVE). It allows users to create and manage virtual machines (VMs) without needing direct access to the Proxmox web UI. The application is designed to be simple, fast, and easy to deploy as a Docker container.

⚠️ This application is currently in development and has limits, which are listed at the end of this document.

⚠️ Only PVE 9.x and superior are supported. PVE 8 and less are not supported because of many breaking changes of roles since PVE 9.

⁠Features

⁠For users

• Create VM: Create a new virtual machine with customizable resources (CPU, RAM, storage, networks, use cloud-init templates).
• VM console access: noVNC console to access to your virtual machines.
• VM management: Start, stop, restart, and delete virtual machines, resize its resources (CPU, RAM, disks, network cards).
• VM search: Find virtual machines by VMID, tag or name.
• VM details: View VM information including status, description, uptime, CPU, memory, disk usage, and network configuration. You can also modify their resources.
• Profile management: View own VM, reset password.
• Multi-language: The interface is available in English and French.
• User documentation: How-to use the PVMSS application and some tips for your VMs.

⁠For administrators

• App information: Get some information about PVMSS application
• Node management: Configure and manage Proxmox nodes available in your cluster for VM deployment (can be a standalone host too).
• User pool management: Add or remove users (only which are created by PVMSS app).
• Tag management: Create and manage tags for VM organisation (only which are created by PVMSS app).
• ISO management: Configure available ISO images for VM installation (cannot upload, just a list of every ISO from every parsed storages).
• Network configuration: Manage available network bridges (VMBRs) for VM networking.
• Cloud-init templates: Create cloud-init templates for VM installation.
• Storage management: Configure storage locations for VM disks.
• Resource limits: Set CPU, RAM, and disk limits for VM creation, and their quantities (with hard limits).
• Documentation: Built-in user documentation accessible from the admin panel.

⁠Getting started

Follow these instructions to get PVMSS running locally using Docker.

⁠Prerequisites

• Docker⁠
• Docker Compose⁠

⁠Create the settings.json file

Before starting the container, you have to create a file, which is the needed configuration for PVMSS to work. An example of the settings.json file is in the folder backend. Create the file, set its rights and copy/paste the content.

Create the file touch settings.json and use your prefer editor to past this content in the file settings.json:

{
    "tags": [
        "pvmss"
    ],
    "isos": [],
    "vmbrs": [],
    "cloudinit_sftp": {
      "enabled": true,
      "host": "your-proxmox-ip-or-hostname",
      "port": 22,
      "username": "pvmss-snippets",
      "privateKeyPath": "/app/pvmss_snippets_ed25519",
      "snippetBaseDir": "/snippets"
    },
    "max_network_cards": 1,
    "max_disk_per_vm": 1,
    "enabled_storages": [],
    "limits": {
        "nodes": {},
        "vm": {
            "cores": {
                "max": 2,
                "min": 1
            },
            "disk": {
                "max": 12,
                "min": 6
            },
            "ram": {
                "max": 4,
                "min": 1
            },
            "sockets": {
                "max": 1,
                "min": 1
            }
        }
    }
}

Save the file, and do the chmod 600 settings.json.

⁠Specific configuration for Cloud-init

As an administrator, you can configure the cloud-init snippets for your users. To do it, you have to create a user inside your Proxmox cluster and create an SSH key pair. More information is provided in the cloud-init⁠ documentation.

⁠Configure environment variables

You can use the provided example file env.example to create your own .env file. Or, you can modify the example file directly.

Settings:

• ADMIN_PASSWORD_HASH: A bcrypt hash of the password for the admin panel. You can generate one using an online tool or a simple script.
• LOG_LEVEL: Set the application log level: INFO or DEBUG (default: INFO).
• PROXMOX_API_TOKEN_NAME: The name of your Proxmox API token for backend operations (e.g., user@pve!token).
• PROXMOX_API_TOKEN_VALUE: The secret value of your API token.
• PROXMOX_URL: The full URL to your Proxmox API endpoint (e.g., https://proxmox.example.com:8006/api2/json).
• PROXMOX_VERIFY_SSL: Set to false if you are using a self-signed certificate on Proxmox (default: false).
• PVMSS_ENV: Set to dev (or development, or developpement) for testing purposes, or prod(or production) in your production environment. In development mode, there will be many logs about the lifecycle of PVMSS app.
• PVMSS_OFFLINE: Set to false in production, and true if you cannot connect to the Proxmox server.
• PVMSS_SETTINGS_PATH: By default, it’s /app/settings.json, you can change the path if needed.
• SESSION_SECRET: Secret key for session encryption (change to a unique random string, like $ openssl rand -hex 32).
• TZ: Europe/Paris.

⁠Create an API token

In order to be able to use PVMSS, you have to create a user inside your Proxmox cluster and its API token.

On Proxmox, go to Datacenter > Permissions > Users. Click on “Add” button, set its username, select the realm Proxmox VE Authentication and type a strong password.

Next, go to Datacenter > Permissions > API Tokens. Click on “Add” button and select the previous created user. Type the API token name, uncheck the case “Privilege Separations”, and get the secret (will be visible only one time).

Finally, go to Datacenter > Permissions, click on the “Add” button and select “User Permissions”. Select the path / and select the previous user created. Choose the role PVEAdmin and click the case “Propagate”. Save it and you are set. Soon, we will restrict rights and paths to be more secure.

⁠Run the container

Create a new file docker-compose.yml with these values:

---
services:
  pvmss:
    image: jhmmt/pvmss:0.3.0
    container_name: pvmss
    restart: unless-stopped
    ports:
      - "50000:50000/tcp"
    # Use either the .env file for environment variables
    # or the environment variables in the docker-compose.yml file.
    # env_file:
    #  - .env
    environment:
      # Proxmox VE settings
      PROXMOX_API_TOKEN_NAME: "tokenName@changeMe!value"
      PROXMOX_API_TOKEN_VALUE: "aaaaaaaa-0000-44aa-1111-aaaaaaaaaaa"
      PROXMOX_URL: "https://ip-or-name:8006/api2/json"
      PROXMOX_VERIFY_SSL: false
      # PVMSS settings
      ADMIN_PASSWORD_HASH: "$2y$10$Ppg7Wl3sNYrmxZmWgcq4reOyznt7AeqMrQucaH4HY.dBrzavhPP1e"
      LOG_LEVEL: "INFO"
      SESSION_SECRET: "changeMeWithSomethingElseUnique"
      PVMSS_ENV: "prod" # Environment: production/prod or development/dev/developpement
      PVMSS_OFFLINE: "false"
      PVMSS_SETTINGS_PATH: "/app/settings.json"
      TZ: "Europe/Paris"
    volumes:
      - ./settings.json:/app/settings.json
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 64M

Start the container:

# Start the container in detached mode
docker compose up -d

Or run the container with docker run:

docker run -d \
  --name pvmss \
  --restart unless-stopped \
  -p 50000:50000 \
  -v $(pwd)/backend/settings.json:/app/settings.json \
  -e ADMIN_PASSWORD_HASH='$2y$10$Ppg7Wl3sNYrmxZmWgcq4reOyznt7AeqMrQucaH4HY.dBrzavhPP1e' \
  -e LOG_LEVEL=INFO \
  -e PROXMOX_API_TOKEN_NAME='tokenName@changeMe!value' \
  -e PROXMOX_API_TOKEN_VALUE="aaaaaaaa-0000-44aa-1111-aaaaaaaaaaa" \
  -e PROXMOX_URL=https://ip-or-name:8006/api2/json \
  -e PROXMOX_VERIFY_SSL=false \
  -e PVMSS_OFFLINE=false \
  -e PVMSS_ENV=prod \
  -e PVMSS_SETTINGS_PATH=/app/settings.json \
  -e SESSION_SECRET="$(openssl rand -hex 32)" \
  -e TZ=Europe/Paris \
  jhmmt/pvmss:0.3.0

The application will be available at http://localhost:50000⁠.

⁠View logs

To see the application logs, simply run:

docker logs -f pvmss

⁠Deployment on Kubernetes

PVMSS can be deployed on Kubernetes using the file pvmss-deployment.yaml. The updated and ready-to-use file is here: pvmss-deployment.yaml⁠.

⁠Architecture

• Backend: A Go application that serves the web interface and communicates with the Proxmox API. It handles all business logic, including authentication, VM operations, template rendering, and console proxy functionality.
• Frontend: Standard HTML, CSS, and minimal JavaScript. It uses the Bulma CSS framework⁠ for a clean and responsive design with integrated noVNC for console access.
• Console access: Built-in noVNC integration with session-based proxy for seamless VM console access.

⁠Limitations

• Development is still in progress
• There are no security tests done, be careful using this app.
• You cannot import your ISO or templates inside PVMSS.

⁠Sources

GitHub⁠

⁠Licence

PVMSS © 2025 by Julien HOMMET is licensed under Creative Commons Attribution-NonCommercial-No Derivatives 4.0 International. To view a copy of this licence, visit https://creativecommons.org/licenses/by-nc-nd/4.0/⁠