TechSetupGuides
Intermediatedockerofflineaikiwixollamasurvivaleducation

Project N.O.M.A.D. - Offline Survival Computer Setup

Set up Project N.O.M.A.D. (Node for Offline Media, Archives, and Data) - a self-contained offline-first knowledge and education server with AI, Wikipedia, maps, and more.

  1. Step 1

    About Project N.O.M.A.D.

    Project N.O.M.A.D. (Node for Offline Media, Archives, and Data) is a self-contained offline survival computer packed with critical tools, knowledge, and AI to keep you informed and empowered anytime, anywhere. It's a management UI (Command Center) that orchestrates containerized tools via Docker.

    Key Features:

    • AI Chat with Knowledge Base (Ollama + Qdrant RAG)
    • Information Library (Kiwix - offline Wikipedia, medical references, ebooks)
    • Education Platform (Kolibri - Khan Academy with progress tracking)
    • Offline Maps (ProtoMaps with downloadable regional maps)
    • Data Tools (CyberChef for encryption, encoding, analysis)
    • Notes (FlatNotes local note-taking)
    • System Benchmark with community leaderboard
    ## Tech Stack Overview

### Backend (Admin Server)
- **Framework**: AdonisJS (TypeScript) v6.19
- **Database**: MySQL 8.0
- **Cache/Queues**: Redis 7 (BullMQ for job processing)
- **Frontend Integration**: Inertia.js with React 19 + TailwindCSS 4
- **Docker**: Docker Engine with Dockerode for container management

### Integrated Services
- **Ollama**: Local LLM inference
- **Qdrant**: Vector database for RAG semantic search
- **Kiwix**: Offline ZIM file browser (Wikipedia, Wikimed)
- **Kolibri**: Education platform
- **ProtoMaps**: Offline mapping
- **CyberChef**: Data analysis tool
- **FlatNotes**: Markdown note-taking

### Infrastructure
- Docker Compose for orchestration
- Alpine-based containers
- Host volume mounting for data persistence
  2. Step 2

    Check System Requirements

    Before installation, verify your system meets the requirements:

    Minimum Specs (barebones installation):

    • Processor: 2 GHz dual-core or better
    • RAM: 4GB system memory
    • Storage: At least 5 GB free disk space
    • OS: Debian-based (Ubuntu recommended)
    • Internet: Required only during initial installation

    Optimal Specs (for AI/LLM features):

    • Processor: AMD Ryzen 7 or Intel Core i7 or better
    • RAM: 32 GB system memory
    • Graphics: NVIDIA RTX 3060 or AMD equivalent (for GPU-accelerated LLMs)
    • Storage: At least 250 GB free disk space (SSD recommended)

    Note: N.O.M.A.D. is designed to be hardware-agnostic and runs on Debian-based systems with Docker.

    # Check OS (must be Debian-based)
cat /etc/os-release

# Check available RAM
free -h

# Check available disk space
df -h /

# Check if Docker is installed
docker --version
docker compose version
  3. Step 3

    Quick Install (Debian-based OS)

    The fastest way to install Project N.O.M.A.D. is using the official installation script. This is completely terminal-based — all tools are accessed through the browser (no desktop environment needed).

    Note: This requires sudo/root privileges and an active internet connection for the initial download.

    # Update package list and install curl
sudo apt-get update && \
sudo apt-get install -y curl

# Download and run the install script
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh \
  -o install_nomad.sh

# Run the installer (sudo required)
sudo bash install_nomad.sh
  4. Step 4

    Access the Command Center

    After installation completes, access the N.O.M.A.D. Command Center by opening a web browser and navigating to:

    • Local access: http://localhost:8080
    • Network access: http://DEVICE_IP:8080 (replace DEVICE_IP with your machine's IP address)

    The Command Center is your management UI for installing, configuring, and updating all included tools and services.

    # Find your device's IP address
hostname -I | awk '{print $1}'
  5. Step 5

    Run First-Time Setup Wizard

    On first access, N.O.M.A.D. presents a setup wizard that guides you through:

    1. AI Assistant Configuration - Set up Ollama for local LLM inference (or configure OpenAI-compatible API)
    2. Content Selection - Choose ZIM files to download (Wikipedia, medical references, survival guides)
    3. Education Content - Select Khan Academy courses and educational materials
    4. Maps - Configure regional maps to download
    5. Service Configuration - Enable/disable additional tools

    The wizard presents curated content collections based on use cases (survival, education, general reference, etc.).

    ⚠ Heads up: The setup wizard requires an internet connection to download initial content. After setup, everything works completely offline.
  6. Step 6

    Advanced Installation (Manual Docker Compose)

    For more control over the installation, you can use the Docker Compose template directly. This is recommended for advanced users who need customization.

    Steps:

    1. Download the management_compose.yaml template
    2. Replace environment variable placeholders (APP_KEY, URL, passwords)
    3. Save as docker-compose.yml
    4. Run docker compose up -d
    # Download and customize the compose file
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/management_compose.yaml \
  -o docker-compose.yml

# IMPORTANT: Edit docker-compose.yml to replace:
# - APP_KEY=replaceme (must be 16+ chars)
# - URL=replaceme (set to http://localhost:8080)
# - Passwords marked as ***

# Start all services
docker compose up -d
    ⚠ Heads up: The APP_KEY must be at least 16 characters or the container will fail to start. Generate one with: openssl rand -base64 32
  7. Step 7

    Using the AI Assistant

    N.O.M.A.D.'s AI Assistant features:

    Local Mode (Ollama):

    • Downloads and runs LLMs directly on your hardware
    • Supports document upload with semantic search (RAG via Qdrant)
    • Model selection via the Command Center UI

    Remote Mode (OpenAI-compatible):

    • Connect to external Ollama server or LM Studio
    • Settings: Navigate to AI Assistant settings in the Command Center

    RAG Features:

    • Upload PDFs, documents, text files
    • Semantic search across uploaded content
    • Citations and source attribution in responses
  8. Step 8

    Information Library (Kiwix)

    Kiwix provides offline access to:

    • Wikipedia (full or topic-specific editions)
    • Wikibooks, Wikinews, Wikiversity
    • Medical references (Merck Manual, etc.)
    • Survival guides and manuals
    • Textbooks and educational content

    The Kiwix interface allows you to:

    • Search across all loaded ZIM files
    • Download new ZIM files from the internet
    • Manage storage and remove content
    • Browse by category
    ## Available ZIM Categories

- Reference (Wikipedia) - English, Spanish, French, etc.
- Education - Khan Academy, Coursera courses
- Medical - First aid, medical dictionaries
- Survival - Bushcraft, emergency preparedness
- Technology - Programming, hardware guides
- Geography - Maps, travel guides
- Literature - Classic books, public domain texts
  9. Step 9

    Offline Maps (ProtoMaps)

    ProtoMaps provides offline mapping functionality:

    • Download regional map tiles for offline use
    • Search locations and places
    • Navigate without internet
    • Vector tile rendering for crisp maps at any zoom level

    Map tiles are stored locally and updated via the Command Center.

    ## Map Features

- **Search**: Find addresses, POIs, landmarks
- **Navigation**: Offline routing (when available)
- **Layers**: Multiple map styles
- **Storage**: Efficient tile caching

## Available Regions

Download maps for your specific region through the Command Center. Map sizes vary by region (typically 100MB - 2GB per region).
  10. Step 10

    Helper Scripts (System Maintenance)

    N.O.M.A.D. installs helper scripts in /opt/project-nomad/ for system administration:

    Start/Stop Services:

    • start_nomad.sh - Start all installed containers
    • stop_nomad.sh - Stop all installed containers

    Updates:

    • update_nomad.sh - Update Command Center containers (NOT installed apps)

    Uninstall:

    • Uninstall script removes entire installation
    # Start all containers
sudo bash /opt/project-nomad/start_nomad.sh

# Stop all containers
sudo bash /opt/project-nomad/stop_nomad.sh

# Update Command Center (docker containers only)
sudo bash /opt/project-nomad/update_nomad.sh
    ⚠ Heads up: The update script only updates N.O.M.A.D. containers, not installed applications like Kiwix or Ollama. Use the Command Center UI for application updates.
  11. Step 11

    Troubleshooting

    Common issues and solutions:

    Container won't start:

    • Check logs: docker logs nomad_admin
    • Verify APP_KEY is 16+ characters
    • Check MySQL and Redis dependencies are healthy

    AI models won't download:

    • Check available disk space: df -h
    • Verify internet connection
    • Check Ollama container logs

    Service not accessible:

    • Check firewall configuration
    • Verify port 8080 is not in use
    • Check Container is running: docker ps
    # View all container logs
docker logs nomad_admin

# Check service health
curl http://localhost:8080/api/health

# Restart a specific service
docker restart nomad_admin
  12. Step 12

    Security Considerations

    Project N.O.M.A.D. is designed for offline use and has no built-in authentication. Consider:

    Local Use (Default):

    • Safe for single-user, offline scenarios
    • No authentication overhead
    • No external exposure

    Network Exposure:

    • Use network-level controls (firewall, VLAN)
    • Do NOT expose directly to the internet
    • Consider self-hosted auth (Nginx basic auth, Authelia)

    Future Authentication:

    • Community-requested feature on roadmap
    • Would enable multi-user/role-based access
    ## Security Best Practices

1. **Keep offline**: N.O.M.A.D. is designed for offline use
2. **Network isolation**: Use separate network if connecting devices
3. **Firewall rules**: Block port 8080 externally
4. **Regular updates**: Update containers via helper scripts

## Authentication Roadmap

Feature request: https://roadmap.projectnomad.us/posts/1/user-authentication-please
  13. Step 13

    Community and Support

    Connect with the N.O.M.A.D. community for help and resources.

    ## Resources

- Website: https://www.projectnomad.us
- Discord: https://discord.com/invite/crosstalksolutions
- Benchmark Leaderboard: https://benchmark.projectnomad.us
- Installation Guide: https://www.projectnomad.us/install
- GitHub: https://github.com/Crosstalk-Solutions/project-nomad

**License:** Apache License 2.0

Feature requests

Sign in to suggest features or vote on existing ones.

No feature requests yet.

Discussion

0 people marked this as worked·Sign in to mark your own.

Sign in to join the discussion.

No comments yet.