NetAlertX/docs/DOCKER_MAINTENANCE.md

The NetAlertX Container Operator's Guide

Warning

⚠️ Important: The docker-compose has recently changed. Carefully read the Migration guide for detailed instructions.

This guide assumes you are starting with the official docker-compose.yml file provided with the project. We strongly recommend you start with or migrate to this file as your baseline and modify it to suit your specific needs (e.g., changing file paths). While there are many ways to configure NetAlertX, the default file is designed to meet the mandatory security baseline with layer-2 networking capabilities while operating securely and without startup warnings.

This guide provides direct, concise solutions for common NetAlertX administrative tasks. It is structured to help you identify a problem, implement the solution, and understand the details.

Guide Contents

• Using a Local Folder for Configuration
• Migrating from a Local Folder to a Docker Volume
• Applying a Custom Nginx Configuration
• Mounting Additional Files for Plugins

Note

Other relevant resources

• Fixing Permission Issues
• Handling Backups
• Accessing Application Logs

---

Task: Using a Local Folder for Configuration

Problem

You want to edit your app.conf and other configuration files directly from your host machine, instead of using a Docker-managed volume.

Solution

1. Stop the container:

   docker-compose down
   

2. (Optional but Recommended) Back up your data using the method in Part 1.

3. Create a local folder on your host machine (e.g., /data/netalertx_config).

4. Edit docker-compose.yml:

   • Comment out the netalertx_config volume entry.
   • Uncomment and set the path for the "Example custom local folder" bind mount entry.

   ...
       volumes:
         # - type: volume
         #   source: netalertx_config
         #   target: /data/config
         #   read_only: false
   ...
       # Example custom local folder called /data/netalertx_config
       - type: bind
         source: /data/netalertx_config
         target: /data/config
         read_only: false
   ...
   

5. (Optional) Restore your backup.

6. Restart the container:

   docker-compose up -d
   

About This Method

This replaces the Docker-managed volume with a "bind mount." This is a direct mapping between a folder on your host computer (/data/netalertx_config) and a folder inside the container (/data/config), allowing you to edit the files directly.

---

Task: Migrating from a Local Folder to a Docker Volume

Problem

You are currently using a local folder (bind mount) for your configuration (e.g., /data/netalertx_config) and want to switch to the recommended Docker-managed volume (netalertx_config).

Solution

1. Stop the container:

   docker-compose down
   

2. Edit docker-compose.yml:

   • Comment out the bind mount entry for your local folder.
   • Uncomment the netalertx_config volume entry.

   ...
       volumes:
         - type: volume
           source: netalertx_config
           target: /data/config
           read_only: false
   ...
       # Example custom local folder called /data/netalertx_config
       # - type: bind
       #   source: /data/netalertx_config
       #   target: /data/config
       #   read_only: false
   ...
   

3. (Optional) Initialize the volume:

   docker-compose up -d && docker-compose down
   

4. Run the migration command (replace /data/netalertx_config with your actual path):

   docker run --rm -v netalertx_config:/config -v /data/netalertx_config:/local-config alpine \
     sh -c "tar -C /local-config -c . | tar -C /config -x"
   

5. Restart the container:

   docker-compose up -d
   

About This Method

This uses a temporary alpine container that mounts both your source folder (/local-config) and destination volume (/config). The tar ... | tar ... command safely copies all files, including hidden ones, preserving structure.

---

Task: Applying a Custom Nginx Configuration

Problem

You need to override the default Nginx configuration to add features like LDAP, SSO, or custom SSL settings.

Solution

1. Stop the container:

   docker-compose down
   

2. Create your custom config file on your host (e.g., /data/my-netalertx.conf).

3. Edit docker-compose.yml:

   ...
       # Use a custom Enterprise-configured nginx config for ldap or other settings
       - /data/my-netalertx.conf:/tmp/nginx/active-config/netalertx.conf:ro
   ...
   

4. Restart the container:

   docker-compose up -d
   

About This Method

Docker’s bind mount overlays your host file (my-netalertx.conf) on top of the default file inside the container. The container remains read-only, but Nginx reads your file as if it were the default.

---

Task: Mounting Additional Files for Plugins

Problem

A plugin (like DHCPLSS) needs to read a file from your host machine (e.g., /var/lib/dhcp/dhcpd.leases).

Solution

1. Stop the container:

   docker-compose down
   

2. Edit docker-compose.yml and add a new line under the volumes: section:

   ...
       volumes:
   ...
         # Mount for DHCPLSS plugin
         - /var/lib/dhcp/dhcpd.leases:/mnt/dhcpd.leases:ro
   ...
   

3. Restart the container:

   docker-compose up -d
   

4. In the NetAlertX web UI, configure the plugin to read from:

   /mnt/dhcpd.leases
   

About This Method

This maps your host file to a new, read-only (:ro) location inside the container. The plugin can then safely read this file without exposing anything else on your host filesystem.