LWS

Open source · MIT License · v1.4.3

Manage Proxmox VE and LXC containers from one command line

LWS (Linux Web Services) creates, scales, snapshots and migrates LXC containers on one or more Proxmox VE hosts, and deploys Docker applications inside them. It works over SSH from your machine, as a CLI or as a REST API with a small web UI.

Get started CLI reference 
# Install from a checkout
git clone https://github.com/fabriziosalmi/lws.git
cd lws && pip install -r requirements.txt
cp config.yaml.example config.yaml   # then add your Proxmox hosts
alias lws="python3 $PWD/lws.py"

# Create three containers from a template on the host
lws lxc run --size small --count 3 \
  --image-id local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst

From host to application

The same tool covers the Proxmox host, the LXC container on it and the Docker application inside the container.

  1. Proxmox hosts

    List hosts, check their status, manage templates, backups and firewall security groups.

    lws px list

  2. LXC containers

    Create, start, stop, resize, snapshot, clone and migrate containers.

    lws lxc run --image-id <template> --size small

  3. Docker applications

    Install Docker in a container and deploy a Compose file into it.

    lws app deploy install <id> --compose-file app.yml

Example: one container running a Compose application

# 1. Create an LXC container with the nesting feature Docker needs
#    (prints the assigned instance ID)
lws lxc run --size lws-web --hostname web --features nesting=1 \
  --image-id local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst

# 2. Install Docker in it (replace 100 with the ID from step 1)
lws app setup 100

# 3. Deploy an existing docker-compose.yml into it
lws app deploy install 100 --compose-file ./docker-compose.yml

What it does

  • Several Proxmox hosts

    Group hosts into regions and availability zones in config.yaml and target any of them with --region and --az.

  • Container lifecycle

    Create containers from predefined sizes, then start, stop, reboot, clone, migrate and terminate them.

  • Snapshots and backups

    Take and remove snapshots, create and restore container backups, and back up host configuration.

  • Firewall security groups

    Create Proxmox firewall security groups, add rules, and attach them to containers.

  • Resource checks and scaling

    lxc scale-check suggests CPU, memory and disk allocations from thresholds in config.yaml; lxc scale applies the values you choose. Both run only when you call them.

  • Docker inside LXC

    Install Docker in a container, run images, deploy Compose files, read logs and update running apps.

  • REST API and web UI

    A Flask API covers most CLI commands, with an API key, Swagger documentation and a minimal web UI.

  • Safe retries and timeouts

    A failed SSH connection is retried; a command that already ran is never repeated. Long operations get up to an hour, configurable.

Quick start

Python 3.10 or later, sshpass, and SSH access to a Proxmox VE host.

  1. Install

    git clone https://github.com/fabriziosalmi/lws.git
cd lws && pip install -r requirements.txt

  2. Configure

    cp config.yaml.example config.yaml
# Set the host, user and ssh_password of each Proxmox host

  3. Create a container

    python3 lws.py px templates
python3 lws.py lxc run --size small \
  --image-id local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst

Read the full getting started guide

Documentation

Guides

Reference and help