From 078e9512a039ccbd1a190fb66bfc0c81a6c52e63 Mon Sep 17 00:00:00 2001 From: Arshpreet Singh Sandhu <146720154+ArshSSandhu@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:06:26 -0400 Subject: [PATCH 1/2] Document air-gapped installation process for Manager Added detailed instructions for air-gapped installation of the Manager container on Proxmox, including steps for downloading, transferring, and configuring the OCI image. --- .../docs/admins/installation.md | 217 ++++++++++++++++++ 1 file changed, 217 insertions(+) diff --git a/mie-opensource-landing/docs/admins/installation.md b/mie-opensource-landing/docs/admins/installation.md index 0e518900..3cde120d 100644 --- a/mie-opensource-landing/docs/admins/installation.md +++ b/mie-opensource-landing/docs/admins/installation.md @@ -16,6 +16,223 @@ The following instructions make several assumptions for clarity. You may have to 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 + +| System | Address | Purpose | +|---|---|---| +| Proxmox node (`pve01`) | `10.100.0.2/16` | Proxmox host | +| Manager container | `10.100.0.3/16` | MIE Manager | +| Staging laptop | `10.100.0.50/16` | Downloads and transfers OCI images | + +The isolated network was not connected to an upstream router or DHCP server. + +!!! warning "Keep the Network Isolated" + Manager provides DHCP for workloads. Do not connect this network to another network that already provides DHCP unless the network design has been reviewed. + +### 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: + +```bash +skopeo copy \ + docker://ghcr.io/mieweb/opensource-server/manager:latest \ + oci-archive:manager_latest.tar +``` + +This creates: + +```text +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: + +```bash +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: + +```bash +pvesm list local --content vztmpl +``` + +The output should include: + +```text +local:vztmpl/manager_latest.tar +``` + +### 3. Create the Manager Container + +Create the Manager container from the transferred OCI archive: + +```bash +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 +``` + +!!! note "Container Storage" + The tested Proxmox installation used `local-lvm` for the container root filesystem because the default `local` storage was configured for templates, ISOs, backups, and imports but did not support container root filesystems. + + Use a Proxmox storage target that supports `rootdir` on your installation. + +!!! note "No Gateway" + No gateway was configured on the Manager container because the tested network was fully isolated. + +### 4. Start and Verify the Manager Container + +Start the Manager: + +```bash +pct start 100 +``` + +Verify its status: + +```bash +pct status 100 +``` + +Verify its network configuration: + +```bash +pct exec 100 -- ip -br addr +``` + +The Manager should have its configured static address. In the tested environment: + +```text +10.100.0.3/16 +``` + +Verify connectivity from the Proxmox host: + +```bash +ping 10.100.0.3 +``` + +### 5. Access Manager + +In the tested air-gapped installation, the Manager application was reachable directly on port `3000`: + +```text +http://10.100.0.3:3000 +``` + +Register the first administrator account. + +!!! warning "First Account" + The first account registered is automatically approved with administrator privileges. Register the intended administrator account first. + +!!! todo "HTTPS Bootstrap" + The tested `manager:latest` image exposed the application on port `3000`, while the standard installation documentation expects HTTPS on port `443`. + + Verify the intended bootstrap behavior and update this section once the HTTPS path is confirmed. + +### 6. Configure the First Site + +Create a site using settings appropriate for the isolated network. + +The tested configuration used: + +```text +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. + +!!! warning "Current Air-Gapped DHCP Limitation" + Manager currently requires gateway and DNS forwarder values before the agent applies its dnsmasq configuration. + + This prevents DHCP from operating normally when those values are intentionally absent on an isolated network. + + This is tracked in [#455](https://github.com/mieweb/opensource-server/issues/455). + + Gateway and DNS values should be treated as optional for a fully isolated deployment once this issue is resolved. + +### 7. Import the Proxmox Node + +In Manager, select **Import Nodes** and enter the Proxmox API information. + +For the tested environment: + +```text +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. + +!!! warning "TLS Verification" + TLS verification was disabled only because the isolated test node used the default self-signed Proxmox certificate. + + TLS verification should remain enabled when the Proxmox API has a trusted certificate. + +### 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: + +```bash +skopeo copy \ + docker://ghcr.io/mieweb/opensource-server/base:latest \ + oci-archive:base_latest.tar +``` + +Transfer it to Proxmox: + +```bash +scp base_latest.tar \ + root@10.100.0.2:/var/lib/vz/template/cache/ +``` + +Verify it: + +```bash +pvesm list local --content vztmpl +``` + +The transferred OCI archive was successfully usable directly by Proxmox during testing. + +!!! todo "Manager Workload Creation from Local Images" + Manager's built-in workload flow currently attempts to contact GHCR for image metadata before checking for a locally available OCI image. + + As a result, selecting a built-in template such as Debian 13 can time out in a fully air-gapped environment even when the OCI archive has already been transferred to Proxmox. + + Support for using locally cached OCI images without registry access is tracked in [#454](https://github.com/mieweb/opensource-server/issues/454). + + ## Installation Steps ### 1. Pull the OCI Image From b7949f57c11ea3d71ab0f6f689718b2dd6c4b9e2 Mon Sep 17 00:00:00 2001 From: Arshpreet Singh Sandhu <146720154+ArshSSandhu@users.noreply.github.com> Date: Fri, 21 Aug 2026 11:18:32 -0400 Subject: [PATCH 2/2] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- mie-opensource-landing/docs/admins/installation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mie-opensource-landing/docs/admins/installation.md b/mie-opensource-landing/docs/admins/installation.md index 3cde120d..f7664b7e 100644 --- a/mie-opensource-landing/docs/admins/installation.md +++ b/mie-opensource-landing/docs/admins/installation.md @@ -147,10 +147,10 @@ Register the first administrator account. !!! warning "First Account" The first account registered is automatically approved with administrator privileges. Register the intended administrator account first. -!!! todo "HTTPS Bootstrap" - The tested `manager:latest` image exposed the application on port `3000`, while the standard installation documentation expects HTTPS on port `443`. +!!! warning "HTTPS bootstrap" + In the tested environment, `manager:latest` exposed the UI on `http://10.100.0.3:3000` (HTTP), not HTTPS on `:443` as described in the standard installation steps. - Verify the intended bootstrap behavior and update this section once the HTTPS path is confirmed. + If your image exposes HTTPS on `:443`, access the UI via `https://:443` instead and keep TLS verification enabled when using a trusted certificate. ### 6. Configure the First Site