Advanced Installation

Deploy Project N.O.M.A.D. manually using Docker Compose for full control over configuration.

The advanced installation method gives you direct control over the Docker Compose configuration before starting any services. It is intended for users who are comfortable with Docker and want to customize port mappings, storage paths, environment variables, or other settings before the first run.

This method requires familiarity with Docker and Docker Compose. If you are setting up N.O.M.A.D. for the first time and do not have Docker experience, use the one-line installer instead.

Overview

Project N.O.M.A.D.’s management stack is defined in a single Docker Compose file. You download this template, fill in the required environment variables, and start the stack with docker compose up -d.

Steps

1. Download the Compose template

   Copy the management_compose.yaml template to your machine and rename it to docker-compose.yml (or keep the original name — Docker Compose accepts both).

   curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/management_compose.yaml -o docker-compose.yml
   
2. Set the required environment variables

   Open the file and replace all replaceme placeholder values with real values. See the environment variables reference below for details on each required variable.

3. Start the stack

   docker compose up -d
   

   Docker pulls any missing images and starts all services in the background.

4. Open the Command Center

   Once the stack is healthy, open a browser and navigate to the URL you set in the URL environment variable — typically:

   http://localhost:8080
   

Environment variables

The following variables must be set before starting the stack. The admin service will fail to start if any replaceme values remain.

Variable	Required	Description
APP_KEY	Yes	Application secret key. Must be at least 16 characters. Used for encryption and session signing.
URL	Yes	The URL you will use to access the Command Center (e.g. http://localhost:8080 or http://192.168.1.x:8080).
DB_PASSWORD	Yes	Password the admin service uses to connect to MySQL. Must match MYSQL_PASSWORD.
MYSQL_PASSWORD	Yes	Password for the nomad_user MySQL account. Must match DB_PASSWORD in the admin service.
MYSQL_ROOT_PASSWORD	Yes	Root password for the MySQL instance. Not used by the application directly, but required by the MySQL image.

DB_PASSWORD and MYSQL_PASSWORD must be identical. If they differ, the admin service will be unable to connect to the database.

Optional environment variables

These variables have sensible defaults and do not need to be changed for most deployments:

Variable	Default	Description
PORT	8080	Port the admin server listens on inside the container. Do not change this — adjust the host port mapping instead (e.g. "9090:8080").
HOST	0.0.0.0	Interface the admin server listens on inside the container. Leave as-is.
LOG_LEVEL	info	Logging verbosity. Options: trace, debug, info, warn, error, fatal.
NODE_ENV	production	Runtime environment. Leave as production for normal deployments.
NOMAD_STORAGE_PATH	/opt/project-nomad/storage	Absolute path on the host where N.O.M.A.D. stores content (ZIM files, maps, AI models). Override this if you want to store data on a different disk or path.
INTERNET_STATUS_TEST_URL	https://1.1.1.1/cdn-cgi/trace	URL used to check internet connectivity. Override if Cloudflare is not reachable from your network.
NOMAD_API_URL	(internal default)	URL of the N.O.M.A.D. external API. Only override if directed to by support.
DB_HOST	mysql	Hostname of the MySQL database service.
DB_PORT	3306	Port of the MySQL database service.
DB_DATABASE	nomad	Name of the database.
DB_USER	nomad_user	Database user.
REDIS_HOST	redis	Hostname of the Redis service.
REDIS_PORT	6379	Port of the Redis service.

Services

The Compose stack starts the following services:

Service	Container name	Description
admin	nomad_admin	The Command Center — the main management UI and API.
dozzle	nomad_dozzle	Optional log viewer for monitoring container output. Accessible at port 9999. Remove this service if you do not need it.
mysql	nomad_mysql	MySQL 8.0 database used by the admin service.
redis	nomad_redis	Redis cache and session store used by the admin service.
updater	nomad_updater	Lightweight sidecar that enables in-UI updates for the Command Center.
disk-collector	nomad_disk_collector	Collects disk usage data from the host and makes it visible in the Command Center UI.

Port mappings

Port	Service	Description
8080	admin	Command Center web interface
9999	dozzle	Container log viewer (optional)

To change which host port the Command Center is accessible on, update the port mapping in the admin service — for example, "9090:8080" makes it accessible on port 9090.

MySQL and Redis ports are not exposed to the host by default. Both services are only reachable by other containers within the project-nomad Docker network. This is intentional — do not add host port mappings for these services unless you have a specific reason to do so.

Volume mounts

Mount	Service	Description
/opt/project-nomad/storage	admin, disk-collector	Persistent storage for all N.O.M.A.D. content and application data.
/var/run/docker.sock	admin, dozzle, updater	Grants the container access to the host Docker daemon for managing other containers.
/opt/project-nomad/mysql	mysql	Persists MySQL data on the host so it survives container removal or updates.
/opt/project-nomad/redis	redis	Persists Redis data on the host so it survives container removal or updates.
/opt/project-nomad	updater	Writable access to the install directory so the updater can modify the Compose file when performing updates.

Compose file reference

The full template is available at:

https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/management_compose.yaml

Installation

Install N.O.M.A.D. using the one-line installer.

Easy Setup Wizard

Configure capabilities and download content after installation.