Skip to main content
Every cloud service in your Xloud environment runs inside a Docker container. Before deployment, container images must be available on every target server. The Images tool manages pulling, extracting, storing, and distributing container images — a critical step for both online and air-gapped (offline) deployments.
Prerequisites
  • Bootstrap completed with all dependency groups passing
  • Docker installed and running on all target nodes
  • Network connectivity to the internet (online mode) or a .tar.gz image archive file (offline mode)

​
Overview Tab

The Overview tab provides a real-time status dashboard for Docker and the local registry without modifying anything on the system.

Docker Engine

Running status, installed Docker version, and total number of locally cached images on the current server.

Local Registry

Registry container (docker-registry:4000) operational status and total stored image count. The registry serves images to all cluster nodes over the internal network.

Registry Controls

Action buttons to Deploy, Start, and Stop the local registry container. Deploy creates the container for the first time; Start and Stop manage its lifecycle afterward.
The local registry runs as a Docker container listening on port 4000. It is accessible to all cluster nodes at docker-registry:4000 — no TLS required for internal communication.

​
Getting Images

Container images can be loaded from two sources depending on your network environment. After loading images into Docker, push them to the local registry so all cluster nodes can access them.
Use this tab to load container images from offline archives or pull them from an online registry. The tab provides two sub-tabs: Extract for offline deployments and Pull for online deployments.

​
Extract (Offline)

Use Extract when your servers have no internet access or when deploying in air-gapped environments. Images can be loaded from two sources:
Load images directly from a USB storage device connected to the deployment server. This is the primary method for air-gapped data centers where images are delivered on physical media.

Connect USB Storage

Connect the USB storage device containing the image archive to the deployment server. The tool automatically detects connected USB storage devices and displays them in the USB Storage Detection section.

Select Archive

Browse the detected USB device and select the .tar.gz image archive file. The tool displays the archive filename and size for confirmation.

Copy to Server

Set the Destination path (default: /var/lib/xavs/images) and click Copy to Server to transfer the archive from the USB device to local server storage. This ensures extraction runs from local disk for maximum performance.
Copying from USB to local storage first avoids slow extraction speeds caused by USB transfer rates. The default destination has sufficient space for full release archives.

Extract and Load Images

After the copy completes, click Extract & Load Images to decompress the archive and load all container images into the local Docker daemon.
After extraction completes from either source, click Push to Local Registry to distribute all loaded images to docker-registry:4000. This makes images available to every node in the cluster.

​
Pull (Online)

Use Pull when the deployment node has internet access and can reach the Xloud cloud registry.

Verify Connectivity

Confirm that the deployment node can reach the Xloud container registry over HTTPS. The tool tests connectivity automatically and displays the result.

Pull Images

Click Pull to download all required container images from the configured image catalog. Each image is downloaded with its full layer chain and stored in the local Docker daemon.

Push to Local Registry

After pulling completes, push all images to the local registry so cluster nodes pull from the internal network instead of the internet during deployment.
A local registry makes image pulls instant and deterministic across the cluster. Without it, multiple nodes pulling simultaneously from the internet is slow and unreliable — especially during initial deployment when 50+ images are needed.

​
Registry Management

The local Docker registry is the central image distribution point for your cluster. All nodes pull container images from this registry during deployment and scaling operations.
Creates and starts the docker-registry container for the first time. The registry listens on port 4000 and stores images in a persistent Docker volume.
Lifecycle controls for the registry container. Stop halts the registry; Start resumes it. Stored images persist across restarts in the backing volume.
Displays the complete catalog of images stored in the registry, including all available tags per image. Use this view to verify that all required service images are present before running deployment.
Shows disk space consumed by the registry volume. Large environments with multiple image versions can consume significant storage — monitor usage and clean up unused tags periodically.
Removes old or unused image tags from the registry to reclaim disk space. Exercise caution — deleting an image that a running container depends on prevents that container from restarting.
The local registry serves images to your entire cluster. If it goes down, new containers cannot start during maintenance, scaling operations, or node recovery. Keep the registry running at all times in production.

​
Docker Configuration

The Images tool provides an editor for /etc/docker/daemon.json — the Docker daemon configuration file. Changes here affect how Docker pulls, stores, and logs container images.
SettingPurposeDefault
Insecure RegistriesAllow Docker to pull from docker-registry:4000 over HTTP (non-TLS)docker-registry:4000
Registry MirrorsConfigure Docker Hub mirror URLs for faster or cached pullsNone
Storage DriverSet the filesystem driver for image layer storageoverlay2
Logging ConfigurationConfigure container log rotation to prevent disk exhaustionJSON file with rotation
The most common deployment issue is Docker refusing to pull from the local registry because docker-registry:4000 is not listed as an insecure registry. Verify this setting on every node before running deployment.
Changes to the Docker daemon configuration require a Docker service restart to take effect. Restarting Docker stops all running containers briefly — schedule configuration changes during maintenance windows on production clusters.

​
Validation

After loading images and configuring the registry, verify readiness before proceeding to deployment.

Verify Registry Status

The Overview tab shows the local registry with a green running status. Confirm the stored image count matches the expected number for your release version.

Confirm Image Availability

Browse the registry catalog and verify that all core service images are present — including compute, networking, identity, storage, and dashboard images.

Test Pull from Another Node

From a compute or storage node, verify that Docker can pull an image from the local registry:
Test registry pull from a cluster node
docker pull docker-registry:4000/xloud/nova-compute:2025.1
A successful pull confirms that the registry is accessible from across the cluster.
Registry running, all images loaded, and cross-node pulls verified — images are ready for deployment.

​
Troubleshooting

Cause: The local registry is not listed as an insecure registry in the Docker daemon configuration.Resolution: Open the Docker Configuration section in the Images tool and add docker-registry:4000 to the insecure registries list. Restart the Docker daemon after saving the change. Repeat on every node in the cluster.
Cause: The .tar.gz archive was corrupted during transfer.Resolution: Re-download or re-transfer the archive file and verify its integrity using the checksum provided with the release. Retry extraction after replacing the corrupted file.
Cause: Port 4000 is already in use by another process, or the Docker volume is corrupted.Resolution: Check for port conflicts with ss -tlnp | grep 4000. If no conflicts exist, remove and redeploy the registry container to recreate the volume from scratch.

​
Next Steps

Operations

Deploy cloud services across the cluster using the loaded container images

Configuration

Review and adjust cloud service configuration before deployment