# NetAlertX and Docker Compose

> [!WARNING]
> ⚠️ **Important:** The documentation has been recently updated and some instructions may have changed.  
> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container.  
> These docs reflect the latest development version and may differ from the production image.

Great care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system.Good care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system. 

> [!NOTE] 
> The container needs to run in `network_mode:"host"` to access Layer 2 networking such as arp, nmap and others. Due to lack of support for this feature, Windows host is not a supported operating system. 

## Baseline Docker Compose

There is one baseline for NetAlertX. That's the default security-enabled official distribution. 

```yaml
services:
  netalertx:
  #use an environmental variable to set host networking mode if needed
    container_name: netalertx                       # The name when you docker contiainer ls
    image: ghcr.io/jokob-sk/netalertx-dev:latest
    network_mode: ${NETALERTX_NETWORK_MODE:-host}   # Use host networking for ARP scanning and other services

    read_only: true                                 # Make the container filesystem read-only
    cap_drop:                                       # Drop all capabilities for enhanced security
      - ALL
    cap_add:                                        # Add only the necessary capabilities
      - NET_ADMIN                                   # Required for ARP scanning
      - NET_RAW                                     # Required for raw socket operations
      - NET_BIND_SERVICE                            # Required to bind to privileged ports (nbtscan)

    volumes:
      - type: volume                                # Persistent Docker-managed named volume for config + database
        source: netalertx_data
        target: /data                               # `/data/config` and `/data/db` live inside this mount
        read_only: false

    # Example custom local folder called /home/user/netalertx_data
    # - type: bind
    #   source: /home/user/netalertx_data
    #   target: /data
    #   read_only: false
    # ... or use the alternative format
    # - /home/user/netalertx_data:/data:rw

      - type: bind                                  # Bind mount for timezone consistency
        source: /etc/localtime                      # Alternatively add environment TZ: America/New York
        target: /etc/localtime
        read_only: true

      # Mount your DHCP server file into NetAlertX for a plugin to access
      # - path/on/host/to/dhcp.file:/resources/dhcp.file

    # tmpfs mount consolidates writable state for a read-only container and improves performance
    # uid=20211 and gid=20211 is the netalertx user inside the container
    # mode=1700 grants rwx------ permissions to the netalertx user only
    tmpfs:
      # Comment out to retain logs between container restarts - this has a server performance impact.
      - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"

      # Retain logs - comment out tmpfs /tmp if you want to retain logs between container restarts
      # Please note if you remove the /tmp mount, you must create and maintain sub-folder mounts.
      # - /path/on/host/log:/tmp/log
      # - "/tmp/api:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
      # - "/tmp/nginx:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
      # - "/tmp/run:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"

    environment:
      LISTEN_ADDR: ${LISTEN_ADDR:-0.0.0.0}                   # Listen for connections on all interfaces
      PORT: ${PORT:-20211}                                   # Application port
      GRAPHQL_PORT: ${GRAPHQL_PORT:-20212}                   # GraphQL API port (passed into APP_CONF_OVERRIDE at runtime)
  #    NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0}                 # 0=kill all services and restart if any dies. 1 keeps running dead services.

    # Resource limits to prevent resource exhaustion
    mem_limit: 2048m            # Maximum memory usage
    mem_reservation: 1024m      # Soft memory limit
    cpu_shares: 512             # Relative CPU weight for CPU contention scenarios
    pids_limit: 512             # Limit the number of processes/threads to prevent fork bombs
    logging:
      driver: "json-file"       # Use JSON file logging driver
      options:
        max-size: "10m"         # Rotate log files after they reach 10MB
        max-file: "3"           # Keep a maximum of 3 log files

    # Always restart the container unless explicitly stopped
    restart: unless-stopped

volumes:                        # Persistent volume for configuration and database storage
  netalertx_data:
```

Run or re-run it:

```sh
docker compose up --force-recreate
```

### Customize with Environmental Variables

You can override the default settings by passing environmental variables to the `docker compose up` command.

**Example using a single variable:**

This command runs NetAlertX on port 8080 instead of the default 20211.

```sh
PORT=8080 docker compose up
```

**Example using all available variables:**

This command demonstrates overriding all primary environmental variables: running with host networking, on port 20211, GraphQL on 20212, and listening on all IPs.

```sh
NETALERTX_NETWORK_MODE=host \
LISTEN_ADDR=0.0.0.0 \
PORT=20211 \
GRAPHQL_PORT=20212 \
NETALERTX_DEBUG=0 \
docker compose up
```

## `docker-compose.yaml` Modifications

### Modification 1: Use a Local Folder (Bind Mount)

By default, the baseline compose file uses "named volumes" (`netalertx_config`, `netalertx_db`). **This is the preferred method** because NetAlertX is designed to manage all configuration and database settings directly from its web UI. Named volumes let Docker handle this data cleanly without you needing to manage local file permissions or paths.

However, if you prefer to have direct, file-level access to your configuration for manual editing, a "bind mount" is a simple alternative. This tells Docker to use a specific folder from your computer (the "host") inside the container.

**How to make the change:**

1. Choose a location on your computer. For example, `/home/adam/netalertx-files`.

2. Create the subfolders: `mkdir -p /home/adam/netalertx-files/config` and `mkdir -p /home/adam/netalertx-files/db`.

3. Edit your `docker-compose.yml` and find the `volumes:` section (the one *inside* the `netalertx:` service).

4. Comment out (add a `#` in front) or delete the `type: volume` blocks for `netalertx_config` and `netalertx_db`.

5. Add new lines pointing to your local folders.

**Before (Using Named Volumes - Preferred):**

```yaml
...
    volumes:
      - netalertx_config:/data/config:rw #short-form volume (no /path is a short volume)
      - netalertx_db:/data/db:rw
...
```

**After (Using a Local Folder / Bind Mount):**
Make sure to replace `/home/adam/netalertx-files` with your actual path. The format is `<path_on_your_computer>:<path_inside_container>:<options>`.

```yaml
...
    volumes:
#      - netalertx_config:/data/config:rw
#      - netalertx_db:/data/db:rw
      - /home/adam/netalertx-files/config:/data/config:rw
      - /home/adam/netalertx-files/db:/data/db:rw
...
```

Now, any files created by NetAlertX in `/data/config` will appear in your `/home/adam/netalertx-files/config` folder.

This same method works for mounting other things, like custom plugins or enterprise NGINX files, as shown in the commented-out examples in the baseline file.

## Example Configuration Summaries

Here are the essential modifications for common alternative setups.

### Example 2: External `.env` File for Paths

This method is useful for keeping your paths and other settings separate from your main compose file, making it more portable.

**`docker-compose.yml` changes:**

```yaml
...
services:
  netalertx:
    environment:
      - TZ=${TZ}
      - PORT=${PORT}
      
...
```

**`.env` file contents:**

```sh
TZ=Europe/Paris
PORT=20211
NETALERTX_NETWORK_MODE=host
LISTEN_ADDR=0.0.0.0
PORT=20211
GRAPHQL_PORT=20212
```

Run with: `sudo docker-compose --env-file /path/to/.env up`

### Example 3: Docker Swarm

This is for deploying on a Docker Swarm cluster. The key differences from the baseline are the removal of `network_mode:` from the service, and the addition of `deploy:` and `networks:` blocks at both the service and top-level.

Here are the *only* changes you need to make to the baseline compose file to make it Swarm-compatible.

```yaml
services:
  netalertx:
    ...
    #    network_mode: ${NETALERTX_NETWORK_MODE:-host} # <-- DELETE THIS LINE
    ...

    # 2. ADD a 'networks:' block INSIDE the service to connect to the external host network.
    networks:
      - outside
    # 3. ADD a 'deploy:' block to manage the service as a swarm replica.
    deploy:
      mode: replicated
      replicas: 1
      restart_policy:
        condition: on-failure


# 4. ADD a new top-level 'networks:' block at the end of the file to define 'outside' as the external 'host' network.
networks:
  outside:
    external:
      name: "host"
```