diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index b46550a0..817ea4e5 100755 --- a/.devcontainer/Dockerfile +++ b/.devcontainer/Dockerfile @@ -276,7 +276,8 @@ USER root # Install common tools, create user, and set up sudo # Ensure entrypoint scripts stay executable in the devcontainer (avoids 126 errors) -RUN chmod +x /entrypoint.sh /root-entrypoint.sh /entrypoint.d/*.sh || true +RUN chmod +x /entrypoint.sh /root-entrypoint.sh /entrypoint.d/*.sh && \ + chmod +x /entrypoint.d/35-apply-conf-override.sh RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest \ pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 117a18ec..495c4aed 100755 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -48,11 +48,11 @@ "postCreateCommand": { "Install Pip Requirements": "/opt/venv/bin/pip3 install pytest docker debugpy", - "Workspace Instructions": "printf '\n\n๏ฟฝ DevContainer Ready!\n\n๐Ÿ“ To access /tmp folders in the workspace:\n File โ†’ Open Workspace from File โ†’ NetAlertX.code-workspace\n\n๐Ÿ“– See .devcontainer/WORKSPACE.md for details\n\n'" + "Workspace Instructions": "printf '\n\n๏ฟฝ DevContainer Ready! Starting Services...\n\n๐Ÿ“ To access /tmp folders in the workspace:\n File โ†’ Open Workspace from File โ†’ NetAlertX.code-workspace\n\n๐Ÿ“– See .devcontainer/WORKSPACE.md for details\n\n'" }, "postStartCommand": { "Start Environment":"${containerWorkspaceFolder}/.devcontainer/scripts/setup.sh", - "Build test-container":"echo building netalertx-test container in background. check /tmp/build.log for progress. && setsid docker buildx build -t netalertx-test . > /tmp/build.log 2>&1 &" + "Build test-container":"echo To speed up tests, building test container in background... && setsid docker buildx build -t netalertx-test . > /tmp/build.log 2>&1 && echo '๐Ÿงช Unit Test Docker image built: netalertx-test' &" }, "customizations": { "vscode": { diff --git a/.devcontainer/resources/devcontainer-Dockerfile b/.devcontainer/resources/devcontainer-Dockerfile index 8acbcfcc..ec64813b 100755 --- a/.devcontainer/resources/devcontainer-Dockerfile +++ b/.devcontainer/resources/devcontainer-Dockerfile @@ -23,7 +23,8 @@ USER root # Install common tools, create user, and set up sudo # Ensure entrypoint scripts stay executable in the devcontainer (avoids 126 errors) -RUN chmod +x /entrypoint.sh /root-entrypoint.sh /entrypoint.d/*.sh || true +RUN chmod +x /entrypoint.sh /root-entrypoint.sh /entrypoint.d/*.sh && \ + chmod +x /entrypoint.d/35-apply-conf-override.sh RUN apk add --no-cache git nano vim jq php83-pecl-xdebug py3-pip nodejs sudo gpgconf pytest \ pytest-cov zsh alpine-zsh-config shfmt github-cli py3-yaml py3-docker-py docker-cli docker-cli-buildx \ diff --git a/.devcontainer/scripts/setup.sh b/.devcontainer/scripts/setup.sh index cb698b08..f766bd0e 100755 --- a/.devcontainer/scripts/setup.sh +++ b/.devcontainer/scripts/setup.sh @@ -47,6 +47,9 @@ sudo mount -t tmpfs -o size=50m,mode=0777 tmpfs /tmp/nginx 2>/dev/null || true sudo chmod 777 /tmp/log /tmp/api /tmp/run /tmp/nginx +# Create critical subdirectories immediately after tmpfs mount +sudo install -d -m 777 /tmp/run/tmp +sudo install -d -m 777 /tmp/log/plugins sudo rm -rf /entrypoint.d @@ -85,9 +88,7 @@ sudo chmod 777 "${LOG_DB_IS_LOCKED}" sudo pkill -f python3 2>/dev/null || true -sudo chmod 777 "${PY_SITE_PACKAGES}" "${NETALERTX_DATA}" "${NETALERTX_DATA}"/* 2>/dev/null || true - -sudo chmod 005 "${PY_SITE_PACKAGES}" 2>/dev/null || true +sudo chmod -R 777 "${PY_SITE_PACKAGES}" "${NETALERTX_DATA}" 2>/dev/null || true sudo chown -R "${NETALERTX_USER}:${NETALERTX_GROUP}" "${NETALERTX_APP}" date +%s | sudo tee "${NETALERTX_FRONT}/buildtimestamp.txt" >/dev/null diff --git a/install/production-filesystem/README.md b/install/production-filesystem/README.md index 4343b31f..51c6be04 100755 --- a/install/production-filesystem/README.md +++ b/install/production-filesystem/README.md @@ -109,6 +109,44 @@ The main script that runs when the container starts: - Monitors services and handles failures - Ensures clean shutdown on container stop +## Boot Flow + +The container startup process is designed to be robust, secure, and informative. It follows a strict sequence to ensure the environment is correctly prepared before the application starts. + +1. **`root-entrypoint.sh` (Privilege & Permission Management)** + * **Validation:** Verifies that `PUID` and `PGID` environment variables are numeric (security measure). + * **Permission Priming:** If running as root, it attempts to fix ownership of writable volumes (`/data`, `/tmp`) to match the requested `PUID`/`PGID`. This ensures the application can write to its storage even if the host volume permissions are incorrect. + * **Privilege Drop:** Uses `su-exec` to switch to the target user (default `netalertx:20211`) before executing the main entrypoint. + * **Non-Root Support:** If the container is started as a non-root user, this step is skipped, and the operator is responsible for volume permissions. + +2. **`entrypoint.sh` (Orchestration)** + * **Banner:** Displays the NetAlertX logo and version. + * **Pre-Startup Checks:** Executes all scripts in `/entrypoint.d/` to validate the environment (see below). + * **Configuration:** Applies environment variable overrides (e.g., `GRAPHQL_PORT`) to the application configuration. + * **Background Tasks:** Launches `update_vendors.sh` to update the MAC address database without blocking startup. + * **Service Startup:** Launches core services in order: + * `crond` (Scheduler) - *Alpine only* + * `php-fpm` (PHP Processor) + * `nginx` (Web Server) + * `python3` (NetAlertX Backend) + * **Monitoring Loop:** Enters a loop to monitor the health of all started services. If any service fails (and `NETALERTX_DEBUG` is not enabled), the container shuts down to allow the orchestrator (Docker/K8s) to restart it. + +3. **`entrypoint.d` (Sanity Checks & Initialization)** + Scripts in this directory run sequentially to prepare and validate the system. Key checks include: + * **Data Migration:** `05-data-migration.sh` - Handles data structure updates. + * **Capabilities:** `10-capabilities-audit.sh` - Verifies required network capabilities (CAP_NET_RAW, etc.). + * **Mounts:** `15-mounts.py` - Checks for correct volume mounts. + * **First Run:** `20-first-run-config.sh` & `25-first-run-db.sh` - Initializes config and database if missing. + * **Environment:** `30-mandatory-folders.sh` - Ensures required directories exist. + * **Configuration:** `35-apply-conf-override.sh` & `40-writable-config.sh` - Applies config overrides and checks write permissions. + * **Web Server:** `45-nginx-config.sh` - Generates Nginx configuration. + * **User ID:** `60-expected-user-id-match.sh` - Warns if running as an unexpected UID. + * **Network:** `80-host-mode-network.sh` & `99-ports-available.sh` - Checks network mode and port availability. + * **Security:** `90-excessive-capabilities.sh` & `95-appliance-integrity.sh` - Audits for security risks. + +4. **Service Operation** + Once all checks pass and services are started, the container is fully operational. The `entrypoint.sh` script continues to run as PID 1, handling signals (SIGINT/SIGTERM) for graceful shutdown. + ## Security Considerations - Application code is read-only to prevent modifications diff --git a/install/production-filesystem/entrypoint.d/35-apply-conf-override.sh b/install/production-filesystem/entrypoint.d/35-apply-conf-override.sh old mode 100644 new mode 100755 diff --git a/install/production-filesystem/root-entrypoint.sh b/install/production-filesystem/root-entrypoint.sh old mode 100644 new mode 100755