Air-gapped installation
ProxCenter can be installed and upgraded on a host that has no internet access, from a bundle that ships every container image it needs. The bundle is produced for each release: Enterprise customers download it from their account on proxcenter.io, partners from the partner portal, Community users from the GitHub release.
The installer loads images locally and runs database schema migrations from those images. It sets PROXCENTER_OFFLINE=true to disable public update checks, the GitHub badge, automatic catalog refresh and portal connection/check-in. License signatures are verified locally. Offline mode only stops ProxCenter's own update, catalog and portal calls; integrations you configure still contact their endpoints, see external dependencies.
The bundle installs a single-node ProxCenter. On Enterprise, that node can then be converted to a 3-node high-availability control plane (Settings > High Availability) without any internet access: the bundle also carries the HA images, see High-availability control plane.
Quick Path
Before you start
- On the isolated host: Linux with systemd, Docker Engine 24+ and the Compose plugin installed from your own package mirror, 5 GB free under
/var/lib/dockerand 2 GB of RAM, see Prerequisites on the isolated host. - An approved channel to move files to the isolated host (removable media, data diode, file transfer gateway), see Step 3: Transfer.
- For Enterprise, an active subscription to download the bundle, see Step 1: Get the bundle.
Install
- On a connected machine, download the bundle of your edition and its
.tar.gz.sha256file, see Step 1: Get the bundle. - Check it with
sha256sum -c, see Step 2: Verify the download. - Move the bundle and its checksum to the isolated host and check it again, see Step 3: Transfer.
- Extract it, check
SHA256SUMS, runsudo ./install-airgap.sh install(with--licenseonly if you already hold an issued key file), then openhttp://your-server-ip:3000and create the administrator account, see Step 4: Install. Limit initial access to the intended administrator and configure verified HTTPS before opening the service to users. - For Enterprise, license the instance with a request file, see Offline licensing.
Check the result
sudo docker compose psin the installation directory (/opt/proxcenterby default) shows the services healthy, see Check the installation.- You can sign in. For Enterprise, Settings > License shows the edition, expiry, node allowance and add-ons you expect.
What the bundle contains
proxcenter-<edition>-<version>.tar.gz extracts to one directory:
| File | Purpose |
|---|---|
install-airgap.sh | The installer. install, upgrade and load run from this directory. |
docker-compose.yml | The Compose file of that release. |
images.tar | Images required by the edition's Compose file: frontend and PostgreSQL; Enterprise also includes orchestrator, PDF renderer and the four HA control-plane images: proxcenter-patroni, proxcenter-keepalived, etcd and haproxy. |
manifest.json | Edition, version, image names and digests. |
SHA256SUMS | Checksums of the files above, verified before anything is loaded. |
README.txt | The commands below. |
Enterprise bundles weigh about 530 MB (HA images included), Community bundles about 380 MB. Loading the Enterprise images needs roughly 3 GB more under Docker's data directory.
Prerequisites on the isolated host
| Requirement | Details |
|---|---|
| Operating system | Linux with systemd (Debian 12+, Ubuntu 22.04+, RHEL 9 family) |
| Docker | Docker Engine 24+ and the Compose plugin (docker compose version works) and the Docker daemon running, installed from your own package mirror. The air-gapped installer never installs Docker. |
| Disk | 5 GB free under /var/lib/docker, plus the database growth |
| RAM | 2 GB minimum |
| Ports | TCP 3000 (web interface); Enterprise also publishes UDP 6343 (sFlow collector) |
| Network | Reachability to your Proxmox nodes on port 8006 (PVE) and 8007 (PBS) |
| Tools | bash, tar, gzip and coreutils, including sha256sum. openssl is optional; secret generation falls back to /dev/urandom. |
Step 1: Get the bundle
- Enterprise
- Partners
- Community
Log in to proxcenter.io/account, open Air-gapped, and download the version you need. An active subscription is required. From a jump host without a browser, your install token works as a bearer token:
curl -fL -H "Authorization: Bearer YOUR_INSTALL_TOKEN" \
-o proxcenter-enterprise-1.4.12.tar.gz \
"https://proxcenter.io/api/v1/install/bundle?version=1.4.12"
Use version=latest for the newest bundle. The download resumes with curl -C -.
Log in to proxcenter.io/partner, open Air-gapped, and download the bundle for your customer. A signed reseller agreement is required. From a jump host, the customer's install token or one of your NFR install tokens works as the bearer token in the curl command of the Enterprise tab.
Download proxcenter-community-<version>.tar.gz from the GitHub release.
Download the matching .tar.gz.sha256 file as well. The installation token only authorizes the Enterprise bundle download. The license of an air-gapped instance is tied to that instance: you get it after installation through offline licensing.
Prepare a Community bundle on a connected host
Enterprise customers download the ready-made bundle of Step 1. To prepare a Community bundle yourself, use the release's script on a connected host with Docker Engine, the Compose plugin and curl:
curl -fL -o install-airgap.sh \
https://raw.githubusercontent.com/adminsyspro/proxcenter-ui/v1.4.12/install-airgap.sh
bash install-airgap.sh bundle \
--edition community \
--version 1.4.12 \
--output ./dist
The script resolves the release's Compose images, pulls and saves them, then produces the archive and its checksum in dist/. --no-pull packages images already present in the connected host's Docker daemon; every required image must already be loaded.
Step 2: Verify the download
On the connected side, before the transfer:
sha256sum -c proxcenter-enterprise-1.4.12.tar.gz.sha256
The SHA-256 is also shown on the Air-gapped page of your account.
Step 3: Transfer
Move the bundle, its checksum and any instance-bound license file to the isolated host by your approved channel (removable media, data diode, file transfer gateway). Verify the archive checksum again after transfer. Obtain checksums through the trusted release/portal channel; a checksum detects corruption but does not authenticate an untrusted replacement archive and checksum. The installer also verifies the extracted files before loading images.
Step 4: Install
tar xzf proxcenter-enterprise-1.4.12.tar.gz
cd proxcenter-enterprise-1.4.12
sha256sum -c SHA256SUMS
sudo ./install-airgap.sh install --license /path/to/proxcenter-license.key
When the bundle sits on media without an executable bit (a FAT-formatted USB stick, for example), run sudo bash install-airgap.sh install --license /path/to/proxcenter-license.key instead.
Options: --install-dir <dir> (default /opt/proxcenter), --registry <host/namespace> (see Use an internal registry), --health-timeout <seconds>.
The installer:
- checks that Docker and Compose are present and refuses to continue otherwise;
- verifies
SHA256SUMS; - loads the images with
docker load; - writes
/opt/proxcenter/docker-compose.yml,.env(fresh secrets,VERSION,PROXCENTER_OFFLINE=true) and, for Enterprise,config/orchestrator.yaml; - creates the volumes and starts the stack;
- waits for the web interface, and for the orchestrator on Enterprise.
Then open http://your-server-ip:3000 and create the administrator account, as in the standard installation. Limit initial access to the intended administrator and configure verified HTTPS before opening the service to users. --license takes the path to a signed .key file; the installer copies it into the orchestrator's data volume before first start. The orchestrator verifies and imports it; a file that fails signature verification does not activate the instance. Without --license, load the issued file later in Settings > License. Community: omit --license; the installer warns and ignores it for that edition.
Offline licensing
For a new Enterprise instance without an issued file:
- In Settings > License, click Server without Internet access?, then Download the license request. An already licensed instance also offers Generate a license request.
- Transfer the request file to a connected machine and submit it through your proxcenter.io account or reseller partner.
- Transfer the returned license key file to the isolated environment.
- Open I have a license key, paste the complete contents of the returned file into License key, then click Activate License. Check the edition, expiry, node allowance and required add-ons in Settings > License.


The request binds the license to this server's identity. Preserve that identity and the deployment secrets in backups. Portal pairing requires connectivity and is a separate activation path; it does not replace the offline request/file exchange. PROXCENTER_OFFLINE=true disables portal connection/check-in while retaining local license validation.
Check the installation
From the installation directory, run:
sudo docker compose ps
sudo docker compose logs --tail=100 frontend
The frontend and PostgreSQL should become healthy; Enterprise also starts the orchestrator and WeasyPrint. If a service is unhealthy, inspect that service's logs before continuing. Sign in, verify the license, then add a TLS-verified PVE/PBS connection and confirm inventory. For Enterprise PDF reporting, generate and download a report to check the renderer.

The supplied Compose file publishes TCP port 3000 on all host interfaces; the Enterprise file also publishes UDP 6343 for the sFlow collector. For a same-host reverse proxy, bind the web port to 127.0.0.1:3000:3000 and expose the HTTPS proxy instead; keep that change across upgrades, which replace docker-compose.yml. Protect .env, license files, configuration and backups as sensitive deployment material. See the production deployment guidance.
If the first install fails
Every message is also written to /opt/proxcenter/install-airgap.log.
The install fails before the containers start
Cause. A bad license file or a docker load error, for example.
Fix. The installer has already removed the files and the volumes it created for this run. Fix the cause, then simply run install again.
The install fails after the containers started
Cause. A health-check timeout on a slow first boot, for example.
Fix. The configuration is kept. Fix the cause, then restart with:
cd /opt/proxcenter && sudo docker compose up -d
A second install run is refused
Cause. /opt/proxcenter/.env exists, or a postgres_data volume from a previous installation exists.
Fix. To start over after a failed first install, remove the stack and its volumes:
The following reset destroys all ProxCenter database and application data. Use it only to restart a failed or disposable installation that holds nothing you need.
cd /opt/proxcenter
sudo docker compose down
sudo docker volume rm postgres_data proxcenter_data orchestrator_data
Then delete /opt/proxcenter. For Community, omit orchestrator_data from the volume command. The Docker daemon must be running (sudo systemctl start docker).
Upgrade
Download the bundle of the newer version, transfer it, then from its extracted directory:
sudo ./install-airgap.sh upgrade
This command updates an existing PostgreSQL-based, single-node installation of the same edition; it does not migrate a v1.3 SQLite deployment. Follow Upgrade to v1.4 for that cutover.
Before upgrading, retain .env, the Compose file and any overrides, config/orchestrator.yaml, mounted certificates/secrets and consistent backups of postgres_data, proxcenter_data and, for Enterprise, orchestrator_data. These files include credentials and instance identity; protect the backups accordingly. Record custom mounts and CA settings because the upgrade replaces the main Compose file.
When PostgreSQL is running, the script takes a compressed pg_dump into /opt/proxcenter/backups/, backs up docker-compose.yml, loads the new images, updates VERSION in .env while retaining secrets, and restarts the stack. Check that the dump was actually created: the script warns and skips it when PostgreSQL is stopped. --skip-db-backup also skips the dump; use it only with a verified independent backup and recovery plan. Pass --install-dir <dir> again for a custom directory, and --health-timeout <seconds> for a slow host. If the installed VERSION already equals the bundle's, the script refuses another upgrade; investigate a failed restart with docker compose ps and logs, then retry docker compose up -d from the installation directory.
The previous images stay loaded on the host for rollback. Keep them until the new version has been accepted and the rollback plan has been retired; database restoration and service recovery still take time. Remove only the images you no longer need afterward.
Roll back
The upgrade prints the exact rollback sequence twice, with the real values filled in: once before it restarts the stack (so the commands are in the transcript even if that restart fails) and again at the end. For an Enterprise install:
cd /opt/proxcenter && sudo docker compose stop frontend orchestrator
sudo docker compose exec -T postgres psql -U proxcenter -d proxcenter -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
sudo sh -c 'gunzip -c /opt/proxcenter/backups/pre-upgrade-1.4.10-<timestamp>.sql.gz | docker compose exec -T postgres psql -U proxcenter -d proxcenter'
sudo sed -i 's/^VERSION=.*/VERSION=1.4.10/' /opt/proxcenter/.env
sudo cp /opt/proxcenter/docker-compose.yml.bak.<timestamp> /opt/proxcenter/docker-compose.yml
sudo docker compose up -d
Community: stop frontend only, there is no orchestrator container to stop.
The dump uses pg_dump --clean --if-exists. The schema reset and restore replace the current database with the pre-upgrade copy and discard changes made afterward. Stop application writers first, verify the selected backup and previous images/configuration, and use the actual database user/name if customized. Do not run the schema reset without a verified restorable dump. The installer prints those database lines only when it took a dump; their absence does not establish that downgrading against the newer schema is safe. If no dump was taken, use your independent backup or verify schema compatibility before any downgrade. Preserve application files and orchestrator data separately from this database rollback.
Use an internal registry
Large sites keep every image in a private registry (Harbor, Nexus, Artifactory). Log the host in to it, then:
sudo ./install-airgap.sh install --registry harbor.internal/proxcenter --license /path/to/proxcenter-license.key
The installer retags every image of the bundle into harbor.internal/proxcenter/… (the high-availability images included), pushes them, and writes REGISTRY= and POSTGRES_IMAGE= to .env so Compose pulls from there. Later upgrades push the new images to the same registry automatically.
High-availability control plane
Enterprise. An air-gapped single-node installation can be converted to a 3-node high-availability control plane from Settings > High Availability, like a connected one. The general requirements (three hosts, VIP, firewall matrix, secrets) are in HA Prerequisites; only the way the images reach the nodes changes. Nothing contacts ghcr.io or any public registry.
The wizard's Network step has an Image source choice. Nothing has to be edited by hand in any .env:
| Image source | Where each node gets the images |
|---|---|
| Automatic (default) | Detected from node 1's installation: the internal registry when it was installed with install --registry, otherwise the images loaded from the bundle |
| Internet (ghcr.io) | Pulled from ghcr.io, for connected sites |
| Private registry | Pulled from your registry by every node. You type the registry (harbor.internal/proxcenter), and optionally a user, a password or token, and the certificate of the authority that signed the registry |
| Air-gapped, images loaded on each node | From each node's local Docker image store: node 1 from install, nodes 2 and 3 from load |
The choice is saved with the HA configuration, and the conversion writes the matching REGISTRY to the .env of the three nodes.

Prerequisites on the three nodes
- Docker Engine 24+ and the Compose plugin on nodes 2 and 3 as well, installed from your own package mirror, with the daemon running. Nothing else is installed on them beforehand.
- Root SSH from node 1 to nodes 2 and 3, as the HA wizard already requires.
- Node 1 installed from the bundle with
install-airgap.sh install, as described above.
Air-gapped without an internal registry
Every node must hold the seven images locally. Node 1 already has them from install.
-
Copy the same bundle to nodes 2 and 3 and extract it there:
tar xzf proxcenter-enterprise-<version>.tar.gzcd proxcenter-enterprise-<version> -
On nodes 2 and 3, load the images:
sudo ./install-airgap.sh loadloadverifiesSHA256SUMSand runsdocker load, nothing more: no files written under/opt/proxcenter, no container started. Its log is/var/log/proxcenter-airgap-load.log. -
On node 1, open Settings > High Availability and run the wizard. Its validation step checks each node with
docker image inspect. When an image is missing, the check names the node and the image and tells you to runloadthere.

Private registry
The conversion has every node pull the seven images from your registry, using its prefix (${REGISTRY}) in the generated HA Compose file. install --registry already pushed them all, the HA images included; if node 1 was installed another way, push the seven images of the bundle to the registry first.
On Harbor, create the project (for example proxcenter, private or public) before install-airgap.sh install --registry harbor.internal/proxcenter, which pushes into it, and give the conversion a robot account of that project with the pull permission only: robot names such as robot$proxcenter+ha are accepted as they are.
-
Credentials. Type the registry user and password (or token) in the wizard: they are used once to log every node in, and never stored. Left empty, the wizard reuses node 1's
docker loginfor that host, read from/root/.docker/config.json; a credential helper (credsStoreorcredHelpers) is not supported for this fallback. -
Private certificate authority. Paste the authority's PEM certificate in the wizard, and it is installed as
/etc/docker/certs.d/<registry host>/ca.crton the three nodes. Left empty, the wizard copies node 1's/etc/docker/certs.d/<registry host>/directory, if any, to nodes 2 and 3. -
If the registry is served over plain HTTP, add it to
insecure-registriesin/etc/docker/daemon.jsonon all three nodes and restart Docker there, before starting the wizard. The wizard does not change the Docker daemon configuration. -
On node 1, open Settings > High Availability and run the wizard. Its validation step checks that every image can be fetched from every node.
Validation step
The wizard's validation step lists the pre-flight checks node by node (images available, inter-node ports, ports free, VIP interface) and the cluster-wide checks, each with its remediation message. Any failed check blocks the deployment; fix the cause and run the validation again.
Upgrade an air-gapped cluster
install-airgap.sh upgrade is for single-node installations: it refuses on a converted node (one where /opt/proxcenter/docker-compose.ha.yml exists). To upgrade the cluster:
-
Transfer the new bundle to the three nodes and run
sudo ./install-airgap.sh loadfrom it on each one. With an internal registry, also push the new images to it withdocker taganddocker push, under the same prefix asREGISTRY. -
Set
VERSIONto the new version in/opt/proxcenter/.envon each node, then recreate the stack one node at a time, always naming the HA Compose file:cd /opt/proxcentersudo docker compose -p proxcenter -f docker-compose.ha.yml up -dWait until the node is healthy again before moving to the next one.
A cluster converted before v1.4.9 also needs the edits described in Upgrading a cluster deployed before v1.4.9.
Features that need an internal mirror
Core installation uses the supplied images. Features that contact external systems need reachable internal services, mirrored artifacts or a separate approved connectivity path; offline mode does not supply those dependencies.
| Feature | What it fetches | On an air-gapped site |
|---|---|---|
| Version check, GitHub badge | api.github.com | Disabled by PROXCENTER_OFFLINE=true |
| Cloud image catalog (Infrastructure > Templates) | Catalog JSON, then image URLs from each distribution | Automatic refresh disabled; use TEMPLATE_CATALOG_URL for an internal JSON mirror and the manual catalog refresh, or use Custom images with internal image URLs. Mirror the image files as well as the catalog. |
| Maps (Topology, vDC datacenters) | OpenStreetMap tiles | Set a custom tile server in Settings > Appearance (the "Map basemap" section); the map explains the situation until then |
| CVE scanner (Enterprise) | Debian Security Tracker JSON, Debian Sources.gz indexes | CVE_FEED_URL= and CVE_DEBIAN_MIRROR= in .env, pointed at internal mirrors |
| Node updates (rolling updates) | Proxmox and Debian apt repositories, from the nodes | The nodes need an apt mirror; ProxCenter only drives apt on them |
| Migrations from VMware, Hyper-V, XCP-ng | On the Proxmox node: virt-v2v, nbdkit, guestfs-tools, ovmf from apt; virtio-win.iso; the NTFS compression plugin; mingw32-srvany; for VMware warm mode, the OpenVDDK kit | Install the apt packages from your mirror, including the non-free nbdkit VDDK plugin; drop virtio-win.iso at /usr/share/virtio-win/virtio-win.iso on the node; for warm mode, copy the OpenVDDK kit to /root/ on a Proxmox VE 9 node and click Prepare (see A node without internet access). |
| High-availability control plane (Settings > High Availability) | ghcr.io from the three nodes: login, image manifests, pulls | Supported: the images come from the bundle loaded on each node, or from your internal registry, see High-availability control plane |
| AI assistant and AI report analysis | The configured model provider | Use an approved internal provider, such as Ollama reachable from both frontend and orchestrator. |
| Country flags | flagcdn.com | Cosmetic; the flags show as blank |
| Email notifications | Your SMTP relay | Unchanged |
| Web fonts | Google Fonts (fonts.googleapis.com), requested by the browser on every page | Cosmetic: the browser falls back to system fonts; no setting needed |

Stage migration dependencies on the Proxmox node
Prepare each target node from your internal mirrors before starting a migration:
- Install
virt-v2v,pv,nbdkit,libnbd-bin(providesnbdcopy),guestfs-toolsandovmf. The package preparation also usesrpm2cpio,cpioandwgetfor the Windows helper. - Place
virtio-win.isoat/usr/share/virtio-win/virtio-win.iso. - Provide the
mingw32-srvanyWindows helper from the Fedoramingw-srvanypackage whenguestfs-toolssupplies neither helper: preflight accepts/usr/share/virt-tools/rhsrvany.exeor/usr/share/virt-tools/pvvxsvc.exe. - For Windows Compact OS guests, install
ntfs-plugin-80000017.soin the node's architecture-specificntfs-3gplugin directory, such as/usr/lib/x86_64-linux-gnu/ntfs-3g/. Register it in libguestfs withzz-ntfs-3g-system-compression.tar.gzunder/usr/lib/<architecture>/guestfs/supermin.d/and rebuild the cached appliance. Building the plugin needsbuild-essential,pkg-config,ntfs-3g-dev,autoconf,automake,libtoolandcurl, plus the mirrored plugin source. - For VMware warm migration, use Proxmox VE 9 with
nbd-clientandnbdkit-plugin-vddkfrom Debiannon-freeon your mirror, and the OpenVDDK kit copied to/root/on the node: Prepare then installs it with the same checksum as a download, see A node without internet access.
Related pages
- Installation for the online installer, the reverse proxy and the production checklist.
- Upgrade to v1.4 for the database changes of that release.