> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Crosstalk-Solutions/project-nomad/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/getting-started/installation) 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
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).
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/management_compose.yaml -o docker-compose.yml
```
Open the file and replace all `replaceme` placeholder values with real values. See the [environment variables reference](#environment-variables) below for details on each required variable.
```bash theme={null}
docker compose up -d
```
Docker pulls any missing images and starts all services in the background.
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
```
Install N.O.M.A.D. using the one-line installer.
Configure capabilities and download content after installation.