NetAlertX/install/production-filesystem

NetAlertX Production Container Filesystem

This document describes the filesystem structure of the NetAlertX production Docker container. This setup focuses on security by separating application code, configuration, and runtime data.

Directory Structure

/app - Main Application Directory

The core application location where NetAlertX runs. This directory contains only the application code in production. Configuration, database files, and logs now live in dedicated /data and /tmp mounts to keep the runtime read-only and auditable.

The core application location. Contains:

• Source code directories (back, front, server) copied in read-only mode
• Service orchestration scripts under /services
• No persistent data or logs—those are redirected to /data and /tmp

/data - Persistent Configuration and Database

Writable volume that stores administrator-managed settings and database state. The entrypoint ensures directories are owned by the netalertx user (UID 20211).

Contains:

• /data/config - persisted settings such as app.conf
• /data/db - SQLite database files (e.g., app.db)
• Optional host bind mounts for backups or external sync

/build - Build-Time Scripts

Temporary directory used during Docker image building to prepare the container environment. Scripts in this directory run during the build process to set up the system before it's locked down for production use. This ensures the container is properly configured before runtime.

Temporary directory used during Docker image building:

• Scripts run at the end of the build process
• Deleted after build to reduce image size
• Only exists during container creation

/opt/venv/lib/python3.12/site-packages/aiofreebox - Certificate Storage

Contains SSL certificates required for secure communication with Freebox OS devices. The aiofreebox Python package uses these certificates to authenticate and establish encrypted connections when integrating with Freebox routers for network device discovery.

Contains certificates for the aiofreebox package, which communicates with Freebox OS devices.

/services - Service Management

Contains all scripts and configurations for running NetAlertX services. This directory holds the complete service orchestration layer that manages the container's runtime behavior, including startup scripts, configuration files, and utility tools for system maintenance and monitoring.

Contains all scripts and configurations for running NetAlertX services:

/services/config - Service Configurations

Configuration files for each service that runs in the container. These files define how services like the web server, task scheduler, and Python backend operate, including security settings, resource limits, and integration parameters.

Configuration files for each service:

• crond/ - Task scheduler settings
• nginx/ - Web server configuration
• php/ - PHP interpreter settings
  • php-fpm.d/ - Additional PHP configurations
• python/ - Python backend launch parameters

/services/scripts - System Scripts and Utilities

Pre-startup checks and specialized maintenance tools. Files named check-* are intended to verify system functions at startup and correct issues or warn users as needed. Additional scripts perform various update tasks and provide integration capabilities with external systems.

Pre-startup checks and specialized maintenance tools:

• check-cap.sh - Verifies container permissions for network tools
• check-first-run-config.sh - Sets up initial configuration
• check-first-run-db.sh - Prepares database on first run
• check-permissions.sh - Validates file and directory permissions
• check-ramdisk.sh - Checks temporary storage setup
• check-root.sh - Confirms proper user privileges
• check-storage.sh - Ensures storage directories exist
• update_vendors.sh - Updates MAC address vendor database
• checkmk/ - Checkmk monitoring integration scripts
• db_cleanup/ - Database maintenance and cleanup tools
• db_empty/ - Database reset utilities
• list-ports.sh - Network port enumeration script
• opnsense_leases/ - OPNsense DHCP lease integration tools

/tmp - Ephemeral Runtime Data

All writable runtime data is consolidated under /tmp, which is mounted as tmpfs by default for speed and automatic cleanup on restart.

• /tmp/log - Application, PHP, and plugin logs (bind mount to persist between restarts)
• /tmp/api - Cached API responses for the UI (configurable via NETALERTX_API environment variable)
• /tmp/nginx/active-config - Optional override directory for nginx configuration
• /tmp/run - Runtime socket and temp directories for nginx and PHP (client_body, proxy, php.sock, etc.)

Service Control Scripts

Scripts that start and manage the core services required for NetAlertX operation. These scripts handle the initialization of the web server, application server, task scheduler, and backend processing components that work together to provide network monitoring functionality.

• start-backend.sh - Launches Python backend service
• start-crond.sh - Starts task scheduler
• start-nginx.sh - Starts web server
• start-php-fpm.sh - Starts PHP processor
• healthcheck.sh - Container health verification
• cron_script.sh - Scheduled task definitions

/entrypoint.sh - Container Startup Script

The main orchestration script that runs when the container starts. It coordinates the entire container initialization process, from pre-startup validation through service startup and ongoing monitoring, ensuring NetAlertX operates reliably in production environments.

The main script that runs when the container starts:

• Runs all pre-startup checks from /services/scripts
• Creates necessary directories and files
• Starts all required services (crond, PHP-FPM, nginx, Python backend)
• Monitors services and handles failures
• Ensures clean shutdown on container stop

Security Considerations

• Application code is read-only to prevent modifications
• Services run with minimal required permissions
• Configurations are separated from code
• Pre-startup checks verify system integrity
• Runtime data is isolated in dedicated directories
• Container exits immediately if any service fails (enables restart policies)