Installation Guide¶

Prerequisites¶

• Proxmox VE 9+ (required for OCI image support)
• Isolated network with no existing DHCP infrastructure
• SSH and web UI access (port 8006) to the Proxmox host

Assumptions¶

The following instructions make several assumptions for clarity. You may have to adapt them for your deployment.

1. You are using the Proxmox default local storage at /var/lib/vz for all operations.
2. You are using the Proxmox default vmbr0 network on the 10.0.0.0/16 subnet. The gateway is at 10.0.0.1 and the Proxmox host is at 10.0.0.2.
3. The Manager container uses container ID 100.
4. The domains example.org and *.example.org have public DNS entries pointing to the firewall in front of this Proxmox cluster.
5. At least one Proxmox node is accessible at https://example.org:8006 with a valid HTTPS certificate.

Air-Gapped Installation¶

The standard installation flow assumes that the Proxmox host can access GitHub Container Registry (GHCR). For an air-gapped deployment, container images must instead be downloaded on an Internet-connected machine and transferred into the isolated Proxmox network.

The following procedure was tested using a single Proxmox node on an isolated network.

Tested Network Layout¶

The isolated network was not connected to an upstream router or DHCP server.

1. Download the Manager OCI Image¶

On an Internet-connected Linux machine, or Windows using WSL, install skopeo and download the Manager image as an OCI archive:

skopeo copy \
  docker://ghcr.io/mieweb/opensource-server/manager:latest \
  oci-archive:manager_latest.tar

This creates:

manager_latest.tar

The Proxmox host itself does not require Internet access for this step.

2. Transfer the Image to Proxmox¶

Connect the staging machine to the isolated Proxmox network.

Transfer the OCI archive into the Proxmox template cache:

scp manager_latest.tar \
  root@10.100.0.2:/var/lib/vz/template/cache/

Adjust the Proxmox address and storage path for your deployment.

Verify that Proxmox recognizes the archive:

pvesm list local --content vztmpl

The output should include:

local:vztmpl/manager_latest.tar

3. Create the Manager Container¶

Create the Manager container from the transferred OCI archive:

pct create 100 local:vztmpl/manager_latest.tar \
  --cores=4 \
  --features=nesting=1 \
  --hostname=manager \
  --memory=8192 \
  --net0=name=eth0,bridge=vmbr0,ip=10.100.0.3/16 \
  --onboot=1 \
  --ostype=debian \
  --rootfs=local-lvm:50

4. Start and Verify the Manager Container¶

Start the Manager:

pct start 100

Verify its status:

pct status 100

Verify its network configuration:

pct exec 100 -- ip -br addr

The Manager should have its configured static address. In the tested environment:

10.100.0.3/16

Verify connectivity from the Proxmox host:

ping 10.100.0.3

5. Access Manager¶

In the tested air-gapped installation, the Manager application was reachable directly on port 3000:

http://10.100.0.3:3000

Register the first administrator account.

6. Configure the First Site¶

Create a site using settings appropriate for the isolated network.

The tested configuration used:

Site Name: MIE Lab
Internal Domain: cluster.mieweb.org
DHCP Range: 10.100.1.1,10.100.254.254
Subnet Mask: 255.255.0.0
External IP: blank

For a truly isolated network, there may be no real gateway or upstream DNS forwarder.

7. Import the Proxmox Node¶

In Manager, select Import Nodes and enter the Proxmox API information.

For the tested environment:

API URL: https://10.100.0.2:8006
Username: root@pam
TLS Verification: disabled for the isolated test environment

Enter the Proxmox root password and select Import.

After import, verify that the Proxmox node appears in Manager.

8. Stage Additional OCI Images¶

Additional workload images can be transferred using the same staging process.

For example, the Debian base image used by the built-in Debian 13 template can be downloaded on the Internet-connected machine:

skopeo copy \
  docker://ghcr.io/mieweb/opensource-server/base:latest \
  oci-archive:base_latest.tar

Transfer it to Proxmox:

scp base_latest.tar \
  root@10.100.0.2:/var/lib/vz/template/cache/

Verify it:

pvesm list local --content vztmpl

The transferred OCI archive was successfully usable directly by Proxmox during testing.

Installation Steps¶

1. Pull the OCI Image¶

Using the Proxmox Web UI or CLI:

skopeo copy docker://ghcr.io/mieweb/opensource-server/manager:latest oci-archive:/var/lib/vz/template/cache/manager_latest.tar

2. Create the Management Container¶

In the Proxmox Web UI or CLI:

pct create 100 local:vztmpl/manager_latest.tar --cores=4 --features=nesting=1 --hostname=manager --memory=8192 --net0=name=eth0,bridge=vmbr0,gw=10.0.0.1,ip=10.0.0.3/16 --onboot=1 --ostype=debian --rootfs=local:50

3. Configure Network Access¶

At your firewall, create the following port-forwards:

4. Start the Container¶

In the Proxmox Web UI or CLI:

pct start 100

5. Initial Account Setup¶

1. Navigate to https://example.org:443.
2. Your web browser will warn about a self-signed certificate. Accept and bypass the warning. If your domain is in HSTS preload lists, you may need to use the IP address rather than the hostname until certificates are configured in a later step.
3. Select the "Register" link and create your account.

6. Configure the First Site¶

Further reading: Sites.

1. Select "New Site".
2. Fill out the information:
   1. Site Name: First Site
   2. Internal Domain: internal.example.org
   3. DHCP Range: 10.0.1.1,10.0.254.254
   4. Subnet Mask: 255.255.0.0
   5. Gateway: 10.0.0.1
   6. DNS Forwarders: 8.8.8.8,1.1.1.1
   7. External IP: your.ext.ernal.ip
3. Select "Create Site".

7. Import Proxmox Nodes¶

Further reading: Nodes.

1. Select "Import Nodes".
2. Fill in the information:
   1. API URL: https://example.org:8006
   2. Username: root@pam
   3. Password: your Proxmox root password
   4. TLS Verification: Enable
3. Select "Import".

8. Configure an External Domain¶

Further reading: External Domains.

1. Select "New External Domain".
2. Fill in the information:
   1. Domain Name: example.org
   2. Default Site: First Site
   3. ACME Email and ACME Directory are currently unused.
   4. Cloudflare API Email and Key are optional unless you are planning to use Cross-Site DNS.
   5. oauth2-proxy URL: optional — the address of an oauth2-proxy process (e.g. http://127.0.0.1:4180) if you want to require authentication for services on this domain (see Authentication).
3. Select "Create External Domain".
4. Refer to SSL Certificate Provisioning to configure an HTTPS certificate.

9. Finalize the Manager Domain¶

1. On the Manager container, select "Edit".
2. Expand the "Services" menu.
3. Select "Add Service".
4. Fill in the information:
   1. Type: HTTP
   2. Internal Port: 3000
   3. External Hostname: manager
   4. External Domain: example.org
   5. Require Auth: false
5. Select "Update Container".