How to Set Up Project N.O.M.A.D. for Offline Use

Project N.O.M.A.D. operates as a self-contained Docker stack that requires an Internet connection only during the initial installation; after running the installer, all services including AI models, Wikipedia archives, and the management UI run entirely offline on localhost.

Project N.O.M.A.D. (Node for Offline Media, Archives, and Data) is an open-source offline media server designed to function without persistent Internet connectivity. According to the Crosstalk-Solutions/project-nomad repository, the system bundles containerized services like Kiwix-Serve, Ollama, and Qdrant into a single Docker orchestration that you can set up Project N.O.M.A.D. for offline use with just one command.

Understanding the Offline-First Architecture

The system achieves complete offline capability through a containerized architecture where all dependencies are resolved during the initial setup. The key components include:

• Management UI – A React-based front-end served via the Inertia layer that communicates with local API endpoints only.
• Docker Orchestrator – Defined in install/management_compose.yaml, this coordinates containers for Kiwix-Serve, Ollama, Qdrant, Kolibri, and other services.
• Pre-installation Logic – The admin/app/services/docker_service.ts file contains the _runPreinstallActions__KiwixServe method that automatically downloads a minimal Wikipedia ZIM file during setup.
• Persistent Storage – All data lives under /opt/project-nomad/storage, including ZIM files, map tiles, and AI models, ensuring no external calls are needed after initial population.

Once installed, the stack exposes no telemetry endpoints and restricts all HTTP traffic to local interfaces (e.g., UI → API on localhost:8080).

Prerequisites and Initial Setup

Before you begin, ensure your environment meets these requirements:

• A Debian-based Linux distribution (Ubuntu is recommended).
• sudo privileges for the installing user.
• A one-time Internet connection to download the installer and container images.

Verify your permissions:

sudo -v

This confirms elevation rights without proceeding to installation.

The Installation Process (Internet Required)

The installation script install/install_nomad.sh handles dependency verification, Docker installation, and service initialization. This is the only phase requiring network access.

Run the installer:

curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh -o install_nomad.sh
sudo bash install_nomad.sh

The script executes several validation and setup steps:

• Dependency Checks – Functions check_has_sudo and check_is_bash verify environment compatibility.
• Docker Installation – ensure_docker_installed downloads and configures Docker via the official convenience script.
• Image Pulling – Retrieves all service images defined in management_compose.yaml.
• Content Seeding – Executes _runPreinstallActions__KiwixServe from docker_service.ts to download wikipedia_en_100_mini_2025-06.zim into the storage directory.

After completion, verify the containers are running:

docker ps -f "name=^nomad_"

You should see entries for nomad_kiwix, nomad_ollama, nomad_qdrant, and other services.

Access the UI by navigating to:

xdg-open http://localhost:8080

At this point, you can disconnect from the Internet; the system is fully operational in offline mode.

Managing the Stack Without Network Access

When you need to stop or start services without Internet connectivity, use the helper scripts provided in the repository.

Stop all services:

sudo bash install/stop_nomad.sh

This script iterates over docker ps -a to gracefully stop all Nomad containers.

Start all services:

sudo bash install/start_nomad.sh

Similarly, this loops through existing containers and starts them, requiring no external network validation.

Verify offline status via the health endpoint:

curl -s http://localhost:8080/api/health | jq .

A properly isolated instance returns "internetConnected": false.

Adding Content While Offline

Project N.O.M.A.D. supports adding new resources (ZIM files, map tiles, or AI models) after installation through direct filesystem manipulation or the local API.

Method 1: Direct filesystem placement

Copy additional .zim files into the storage directory:

wget -O /opt/project-nomad/storage/zim/wikipedia_en_all_maxi.zim \
     https://download.kiwix.org/zim/wikipedia/wikipedia_en_all_maxi.zim

Note: This wget command requires Internet; however, you can transfer the file via USB, SCP, or any offline method into the same directory.

Method 2: API-triggered rescan

After placing files, trigger a library update:

curl -X POST http://localhost:8080/api/zim/rescan

The system reads directly from /opt/project-nomad/storage, so the Management UI immediately detects new content without external validation.

Summary

• Single-command setup – Run install_nomad.sh once with Internet to bootstrap the entire stack.
• Zero external dependencies post-install – All services communicate via internal Docker networking and local filesystem storage.
• Modular content management – Add ZIM files, maps, and models by copying them to /opt/project-nomad/storage and triggering a rescan.
• Explicit offline verification – The /api/health endpoint confirms when the system detects no Internet connectivity.
• Helper scripts included – start_nomad.sh and stop_nomad.sh provide convenient stack management without Docker expertise.

Frequently Asked Questions

Does Project N.O.M.A.D. require any Internet access after the initial installation?

No. After running install_nomad.sh, all Docker images, AI models, and the initial Wikipedia ZIM file reside locally on disk. The system is specifically architected to serve content from /opt/project-nomad/storage and communicate via localhost:8080, making it fully functional in air-gapped environments.

How do I add new Wikipedia archives or AI models without reconnecting to the Internet?

You can transfer files to the server using physical media (USB drives) or local network methods (SCP, rsync). Place .zim files in /opt/project-nomad/storage/zim and models in their respective subdirectories, then use the Management UI at Settings → ZIM Library to click "Rescan," or POST to /api/zim/rescan. The services read directly from the filesystem, so no Internet is required to index or serve the new content.

What happens if Docker is not installed when I run the installer?

The install_nomad.sh script includes the ensure_docker_installed function, which automatically downloads and installs Docker using the official convenience script from https://get.docker.com. This is the only external network call performed by the installer, and it occurs during the initial setup phase before the system goes offline.

Can I verify that Project N.O.M.A.D. is not making external network calls?

Yes. Query the health endpoint with curl http://localhost:8080/api/health. The JSON response includes an internetConnected field that returns false when the server cannot reach external networks, confirming the offline-first configuration is active.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}