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

> Learn how to set up Project NOMA.D. for offline use. This self-contained Docker stack runs AI models, Wikipedia archives, and more entirely on localhost after initial installation.

- Repository: [Crosstalk Solutions/project-nomad](https://github.com/Crosstalk-Solutions/project-nomad)
- Tags: how-to-guide
- Published: 2026-03-16

---

**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`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/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`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/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:

```bash
sudo -v

```

This confirms elevation rights without proceeding to installation.

## The Installation Process (Internet Required)

The installation script [`install/install_nomad.sh`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/install/install_nomad.sh) handles dependency verification, Docker installation, and service initialization. This is the only phase requiring network access.

Run the installer:

```bash
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`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/management_compose.yaml).
- **Content Seeding** – Executes `_runPreinstallActions__KiwixServe` from [`docker_service.ts`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/docker_service.ts) to download `wikipedia_en_100_mini_2025-06.zim` into the storage directory.

After completion, verify the containers are running:

```bash
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:

```bash
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:**

```bash
sudo bash install/stop_nomad.sh

```

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

**Start all services:**

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/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`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/start_nomad.sh) and [`stop_nomad.sh`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/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`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/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`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/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.