WebX11 Development Container

Isolated Debian environment for WebX11 development and testing using qcow2 disk image with chroot.

System Overview

Image: 20GB qcow2 disk (compressed to ~732MB)
Base System: Debian Bookworm
Web Stack: Nginx + PHP-FPM 8.2
Mount Point: /mnt/webx11-chroot

Files

Path	Description
`/tmp/webx11-dev.img`	Raw disk image (for mounting)
`/var/lib/libvirt/images/webx11-dev.qcow2`	Compressed qcow2 backup
`/usr/local/bin/chroot-webx11.sh`	Helper script

Quick Start

# Using the CLI tool (recommended)
sudo /usr/local/bin/webx11.sh start
sudo /usr/local/bin/webx11.sh full

# Or use the old script
sudo /usr/local/bin/chroot-webx11.sh start

# Start container (mounts + starts services)
sudo /usr/local/bin/chroot-webx11.sh start

# Access web server
curl http://localhost:8082

# Enter chroot shell
sudo /usr/local/bin/chroot-webx11.sh shell

# Stop services
sudo /usr/local/bin/chroot-webx11.sh stop

# Restart services
sudo /usr/local/bin/chroot-webx11.sh restart

Commands

start

Mounts the disk image and starts Nginx + PHP-FPM services.

stop

Stops services inside chroot.

shell

Opens a bash shell inside the chroot environment.

restart

Restarts all services.

Configuration

Nginx Port: 8082
Config: /mnt/webx11-chroot/etc/nginx/sites-available/webx11
Web Root: /mnt/webx11-chroot/var/www
PHP-FPM Socket: /mnt/webx11-chroot/run/php/php8.2-fpm.sock

Web Content

Web files are located at: /mnt/webx11-chroot/var/www/

To update content:

# Stop container
sudo chroot-webx11.sh stop

# Copy new content
sudo cp -r /var/www/webx11.duckdns.org/* /mnt/webx11-chroot/var/www/
sudo chown -R www-data:www-data /mnt/webx11-chroot/var/www

# Start container
sudo chroot-webx11.sh start

Snapshots

Create a backup snapshot:

sudo qemu-img convert -f raw -O qcow2 /tmp/webx11-dev.img /var/lib/libvirt/images/webx11-dev-$(date +%Y%m%d).qcow2

List snapshots:

ls -lh /var/lib/libvirt/images/webx11-dev-*.qcow2

Download

Download the pre-built container image (283MB compressed):

One-Line Install (Root)

curl -sL https://webx11.duckdns.org/docs/webx11-install.sh | sudo bash

One-Line QEMU (No Root)

curl -sL https://webx11.duckdns.org/docs/webx11-qemu.sh | bash -s -- 2G 2

Or download separately:

Archive: /docs/webx11-container.tar.xz (283MB)
Install Script (root): /docs/webx11-install.sh
QEMU Launcher (no root): /docs/webx11-qemu.sh
CLI Tool: /docs/webx11.sh

Manual Install

# Download files
curl -O https://webx11.duckdns.org/docs/webx11-container.tar.xz
curl -O https://webx11.duckdns.org/docs/webx11-install.sh
chmod +x webx11-install.sh

# Run installer
sudo ./webx11-install.sh

# Access dev server
curl http://localhost:8082

API Modes

The container supports two API modes:

Shared Mode (Default)

API requests from the container are proxied to the host server. This allows testing frontend changes while using the host's APIs.

Static files: Container serves your web content
APIs: Proxied to host (10.0.2.2)
Image size: 283MB

Isolated Mode

Container runs with no API access - static files only. Good for offline testing.

Static files: Container serves your web content
APIs: Disabled
Can install local APIs: Yes (see below)

Switch to Isolated mode:

sudo /usr/local/bin/webx11-isolated.sh

Run with QEMU (No Root)

Run the container without root using QEMU emulation:

Requirements

sudo apt-get install qemu-system-x86

One-Line

curl -sL https://webx11.duckdns.org/docs/webx11-qemu.sh | bash -s -- 2G 2

Manual

# Download archive
curl -O https://webx11.duckdns.org/docs/webx11-container.tar.xz

# Download launcher
curl -O https://webx11.duckdns.org/docs/webx11-qemu.sh
chmod +x webx11-qemu.sh

# Run (2GB RAM, 2 cores)
./webx11-qemu.sh 2G 2

# Access dev server
curl http://localhost:8082

Options

# 4GB RAM, 4 cores
./webx11-qemu.sh 4G 4

# 1GB RAM, 1 core (minimal)
./webx11-qemu.sh 1G 1

Create Image from Scratch

If you want to create your own image:

# Install required packages
sudo apt-get update
sudo apt-get install -y debootstrap qemu-utils guestfs-tools xz-utils

# Create 20GB sparse image
dd if=/dev/zero of=/tmp/webx11-dev.img bs=1M count=1 seek=20000

# Partition and format
sudo fdisk /tmp/webx11-dev.img << 'EOF'
n
p
1

t
83
w
EOF

# Setup loop device
LOOP=$(sudo losetup -f)
sudo losetup $LOOP /tmp/webx11-dev.img
sudo partprobe $LOOP
sudo mkfs.ext4 -F ${LOOP}p1

# Mount and install Debian
sudo mount ${LOOP}p1 /mnt/webx11-chroot
sudo debootstrap bookworm /mnt/webx11-chroot https://deb.debian.org/debian

# Install nginx + PHP-FPM
sudo chroot /mnt/webx11-chroot apt-get update
sudo chroot /mnt/webx11-chroot apt-get install -y nginx php8.2-fpm

# Copy your web files
sudo cp -r /var/www/* /mnt/webx11-chroot/var/www/

# Configure nginx (see Configuration section above)

# Unmount
sudo umount /mnt/webx11-chroot
sudo losetup -d $LOOP

# Convert to qcow2 (more compact)
qemu-img convert -f raw -O qcow2 -c /tmp/webx11-dev.img /tmp/webx11-dev.qcow2

# Compress with xz for distribution
xz -9 /tmp/webx11-dev.qcow2

Troubleshooting

Port already in use

Edit nginx config and change port:

sudo sed -i 's/listen 8082/listen <PORT>/' /mnt/webx11-chroot/etc/nginx/sites-available/webx11
sudo cp /mnt/webx11-chroot/etc/nginx/sites-available/webx11 /mnt/webx11-chroot/etc/nginx/sites-enabled/webx11

Mount fails

Check for existing mounts:

mountpoint /mnt/webx11-chroot
sudo umount /mnt/webx11-chroot

Services won't start

Check logs inside chroot:

sudo chroot-webx11.sh shell
tail -f /var/log/nginx/error.log

CLI Tool

Use the webx11.sh CLI tool to manage the container:

# CLI Commands
sudo /usr/local/bin/webx11.sh start          # Start container
sudo /usr/local/bin/webx11.sh stop           # Stop container
sudo /usr/local/bin/webx11.sh restart        # Restart container
sudo /usr/local/bin/webx11.sh status         # Container status
sudo /usr/local/bin/webx11.sh tunnel start   # Start tunnel
sudo /usr/local/bin/webx11.sh tunnel stop    # Stop tunnel
sudo /usr/local/bin/webx11.sh isolated       # Switch to Isolated mode
sudo /usr/local/bin/webx11.sh shared        # Switch to Shared mode
sudo /usr/local/bin/webx11.sh full          # Full status
sudo /usr/local/bin/webx11.sh menu           # Interactive menu

Requirements

Linux with loop device support
debootstrap
qemu-img (from qemu-utils)
root/sudo access