Offline deployment

Offline deployment is used when Qarvix needs to run in a closed mesh: at an industrial site, an internal data center, a customer's isolated network, or an environment where permanent internet access is prohibited.

This format takes more preparation than a cloud scenario. Infrastructure, activation, updates, backups, diagnostics, and the process for delivering packages all need to be agreed on in advance.

In short

• An offline mesh needs to have every required component inside the closed network.
• Dependencies, images, and packages are prepared ahead of time.
• License activation and renewal need to work without permanent internet.
• Updates go through a portable package on a set schedule.
• Backups and recovery need to be tested before production.
• Diagnostics need to be possible without external services.

When you need an offline scenario

Offline deployment fits when:

• the site has no internet access;
• internet is prohibited by security policy;
• the mesh sits on an industrial or technological network;
• data needs to be stored locally;
• an external cloud service can't be used;
• updates need to follow an agreed schedule;
• contractor access is strictly controlled within the perimeter.

If internet access exists but is unstable, a dedicated or hybrid option might be enough. That needs to be evaluated separately.

What's part of the mesh

The composition depends on the chosen architecture, but you typically need to plan for:

• a server or virtual machine for Qarvix;
• a database;
• a web interface;
• a control plane for agent WSS sessions;
• a WireGuard hub;
• storage for configurations and logs;
• backups;
• availability monitoring;
• a way to deliver updates;
• a license activation procedure.

If the mesh has several network zones, decide in advance where users open the web interface from, where agents connect from, and where WireGuard traffic runs.

Infrastructure requirements

Before installation, clarify:

• available servers or virtual machines;
• the OS and update policy;
• available ports;
• firewall rules;
• DNS inside the mesh;
• NTP or another time source;
• storage for the database and backups;
• log requirements;
• who has administrative access;
• how files are transferred into the closed mesh.

Time on the servers matters especially. Clock errors can break TLS, tokens, signatures, and log accuracy.

Preparing packages

For an offline install, a portable bundle is prepared ahead of time.

It may include:

• the Qarvix distribution;
• container images or packages;
• database migrations;
• the agent for supported platforms;
• installation instructions;
• a license file or activation package;
• checksums;
• release notes;
• rollback instructions.

Before transferring it into the closed mesh, the package should be tested in an environment with similar restrictions.

Installation

General order:

1. Prepare a server or virtual machine.
2. Configure the network, DNS, time, and firewall.
3. Install base components.
4. Deploy Qarvix.
5. Apply migrations.
6. Activate the license.
7. Create an administrator.
8. Create the first organization and network.
9. Connect a test device.
10. Check logs, reports, and backups.

Before connecting production sites, run a backup-recovery test.

Offline activation

If the mesh has no internet access, license activation needs to follow a separate procedure.

Agree on:

• what data is provided to issue the license;
• how the license is transferred into the closed mesh;
• who's allowed to perform activation;
• how the expiry is checked;
• how renewal is performed;
• what to do when replacing a server;
• how the license backup is stored.

These steps are best written into an operational runbook, not left as a verbal agreement.

Updates

In an offline mesh, updates usually go through a controlled package transfer.

Recommended order:

1. Check the release notes.
2. Confirm compatibility with the current version.
3. Take a backup.
4. Test the package on a test bench.
5. Agree on a maintenance window.
6. Transfer the package into the closed mesh.
7. Perform the update.
8. Check the web interface, WSS, WireGuard, logs, and reports.
9. Record the result.

Critical meshes need a rollback plan.

Backups

Backups need to cover:

• the database;
• configurations;
• license data;
• user and role settings;
• logs, if needed for investigations;
• files required for recovery.

Check not just that a backup exists, but that it can be restored.

A minimal check:

• create a backup;
• deploy it on a test server;
• log in to the dashboard;
• check organizations, networks, and devices;
• check logs;
• confirm the version matches expectations.

Diagnostics in a closed mesh

In an offline environment, you can't rely on external checks, cloud logs, or a vendor's remote access.

Prepare in advance:

• local logs;
• WSS check commands;
• WireGuard check commands;
• a DNS and time check;
• a port check;
• diagnostic data export;
• a procedure for sending logs out, if that's allowed;
• people responsible on the customer's side.

If remote support isn't possible, the operations team needs a clear self-diagnosis checklist.

Security

Offline doesn't automatically mean secure. A closed mesh still requires access management.

Check:

• who administers Qarvix;
• who has access to the server;
• where backups are stored;
• how roles are granted;
• whether 2FA is on for administrators;
• how contractor access is revoked;
• who transfers updates;
• how package integrity is verified.

It matters especially to separate access to the Qarvix dashboard from access to the server infrastructure.

Implementation checklist

• Infrastructure is prepared.
• DNS and time work inside the mesh.
• Ports and the firewall are agreed.
• The install package has been verified.
• The license is activated.
• The first organization has been created.
• A test network has been created.
• A test device is connected.
• The agent's WSS session establishes.
• WireGuard traffic passes through.
• Logs and reports are available.
• Backups are configured and tested.
• The update procedure is documented.
• Those responsible are assigned.

Common issues

The agent doesn't connect to the server

Check DNS, the route to the control plane, TLS, the device's clock, the firewall, and the reachability of the WSS endpoint inside the closed mesh.

WireGuard doesn't come up

Check UDP access, keys, hub settings, the network's CIDR, the firewall, and subnet overlap.

The license doesn't activate

Check whether the correct license file is being used, whether it matches the mesh the license was issued for, and whether a separate offline procedure is needed.

No devices show up after an update

Check migrations, database state, application version, server logs, and agent compatibility.

There's a backup, but recovery hasn't been tested

That backup can't be considered reliable. Run a test recovery before a production launch.

Related sections

• Licensing - offline activation and renewal terms.
• Diagnostics and common issues - checks for WSS, WireGuard, and routes.
• Logs and reports - operational oversight of a closed mesh.
• Users, roles, and SSO - administrator and contractor access.