Upload 22 files

README.md

@@ -1,11 +1,158 @@
+# Production-Ready GenieACS Single-Container Deployment for Hugging Face
+
+This repository contains a complete, production-ready configuration for deploying a self-contained **GenieACS** server on Hugging Face Spaces (using a Docker Space).
+
+GenieACS is a high-performance TR-069 Auto Configuration Server (ACS) designed to manage customer-premises equipment (CPE).
+
+## Architecture Overview
+
+Since Hugging Face Spaces expose only a single web port (**7860**) to the public, this container uses a multi-layered service architecture coordinated by **Supervisor** and reverse-proxied by **Nginx**:
+
+```
+Public Traffic (HTTPS) ---> [ Hugging Face SSL Proxy ]
+                                    |
+                                    | Port 7860 (HTTP)
+                                    v
+                            [ Nginx Reverse Proxy ]
+            ________________________|________________________
+           |            |           |            |           |
+     / (UI UI-API)   /api/       /files/       /cwmp       /healthz
+           |            |           |            |           |
+           v            v           v            v           v
+       [ UI ]         [ NBI ]      [ FS ]      [ CWMP ]   [ Health ]
+      Port 3000     Port 7557    Port 7567   Port 7547    200 'OK'
+           \____________|___________|____________/
+                        |
+                        v
+                 [ MongoDB 8.0 ]
+                 Port 27017 (Auth Enabled)
+```
+
+### Components In Container
+1. **Nginx (7860)**: Performs path-based routing, terminates WebSocket connections, manages connection timeouts, handles Gzip compression, and applies security headers.
+2. **MongoDB Community Edition (27017)**: Local database engine configured with WiredTiger, auth-enabled, and tuned to restrict memory consumption.
+3. **GenieACS CWMP (7547)**: Receives TR-069 device Inform messages and coordinates download/upload workflows.
+4. **GenieACS NBI (7557)**: Northbound Interface (JSON API) used to configure settings and query device states.
+5. **GenieACS FS (7567)**: File server for holding and distributing firmware updates, configurations, and scripts.
+6. **GenieACS UI (3000)**: Web-based administrative user interface.
+7. **Supervisor Orchestrator**: Starts services, orders dependencies (waiting on MongoDB), handles log rotation, and monitors health.
+8. **Health Monitor Daemon**: Loops every 30 seconds to verify all endpoints. If any service crashes, it automatically heals by restarting it via `supervisorctl`.
+9. **Hugging Face Hub Integration**: Periodically uploads compressed `mongodump` database archives to a private Hugging Face Dataset.
+
+---
+
+## Exposed Ports & Routing
+
+All external requests arrive through port `7860`. Nginx maps the public endpoints to internal ports as follows:
+
+| External Path | Internal Port | Service Description |
+|---|---|---|
+| `/` | `3000` | GenieACS Administrative Web UI |
+| `/api/` | `7557` | GenieACS Northbound API (NBI) |
+| `/files/` | `7567` | GenieACS File Server (FS) |
+| `/cwmp` | `7547` | GenieACS Device Connection Engine (CWMP) |
+| `/healthz` | (Static Nginx) | Simple health validation endpoint |
+
+---
+
+## Environment Variables
+
+The container is configured entirely using environment variables. When deploying to Hugging Face, configure these in the Space's **Settings > Variables and Secrets**.
+
+### Core Settings
+* `ADMIN_USERNAME`: Web UI administrator username (managed inside GenieACS database).
+* `ADMIN_PASSWORD`: Web UI administrator password.
+* `LOG_LEVEL`: GenieACS logging level (`info`, `warn`, `error`, `debug`). Defaults to `info`.
+* `TZ`: System timezone (e.g., `UTC` or `America/New_York`).
+
+### Database Settings
+* `MONGODB_URI`: Connection string for an *external* MongoDB instance (optional). If left blank, the container automatically spawns its own internal MongoDB on port 27017.
+* `GENIEACS_UI_JWT_SECRET`: Secret key for signing Web UI session tokens. If not provided, the entrypoint generates a secure random secret on first boot and persists it inside `/data/genieacs_jwt.secret`.
+
+### Hugging Face Backup & Restore
+* `HF_TOKEN`: Hugging Face API write access token. Required to run backups or restores on boot.
+* `HF_DATASET`: Target Hugging Face private dataset repo (e.g., `username/genieacs-backups`).
+* `BACKUP_INTERVAL`: Number of seconds between automated backups. Defaults to `86400` (24 hours).
+* `BACKUP_RETENTION`: Number of recent backup archives to retain both locally and in the Hugging Face Dataset. Defaults to `5`.
+
+---
+
+## Deployment to Hugging Face Spaces
+
+1. Create a new **Space** on Hugging Face.
+2. Select **Docker** as the Space type.
+3. Choose the **Blank** template.
+4. Set the Space visibility to **Private** or **Public** (Note: A private Space is recommended if managing sensitive device credentials).
+5. Open the Space's **Settings** and add your variables:
+   * Create a private Dataset on Hugging Face (e.g., `yourusername/genieacs-backups`).
+   * Set `HF_TOKEN` as a **Secret** containing your Hugging Face API write token.
+   * Set `HF_DATASET` to `yourusername/genieacs-backups`.
+6. Push this repository's code to the Space's Git repository. Hugging Face will automatically compile the Dockerfile and start the container.
+
+---
+
+## Backup & Restore Workflow
+
+### Automated Backups
+Backups run on a cron-like schedule inside the Supervisor wrapper. The script does the following:
+1. Triggers `mongodump` to extract the database state into a compressed archive.
+2. Packages it into a `.tar.gz` named `mongo_YYYYMMDD_HHMMSS.tar.gz`.
+3. Calls python `hf_helper.py` using `huggingface_hub` to upload the file to your private Hugging Face Dataset.
+4. Triggers retention cleanups to remove older backups on both local storage and Hugging Face.
+
+### Manual Backup
+To trigger an immediate backup, access the container shell or run:
+```bash
+/app/backup.sh
+```
+
+### Automated Restore on Boot
+When a fresh container starts, if `HF_TOKEN` and `HF_DATASET` are set, the entrypoint script automatically:
+1. Lists all backups in the dataset.
+2. Downloads the latest backup archive.
+3. Restores it using `mongorestore --drop`.
+4. Restarts all services to load the restored state.
+
+### Manual Restore
+To restore to a specific backup, pass the filename as an argument:
+```bash
+/app/restore.sh mongo_20260712_063000.tar.gz
+```
+If you omit the filename, it will find and download the latest available backup.
+
 ---
-title: C4
-emoji: 🌖
-colorFrom: purple
-colorTo: pink
-sdk: docker
-pinned: false
-license: apache-2.0
+
+## Performance Tuning & 500+ Concurrent Devices
+
+This container has been tailored to handle 500+ concurrent TR-069 devices under moderate inform cycles:
+
+* **MongoDB Memory Caps**: Cap WiredTiger cache size to `512MB` in `/app/config/mongodb.conf` to protect against container OOM crashes.
+* **Keepalive optimization**: Nginx keeps TCP connections open (`keepalive_timeout 600s`) to prevent connection handshakes during dense Inform bursts.
+* **Buffering Controls**: Buffered proxies are disabled on `/cwmp` (`proxy_buffering off`) to provide direct, low-latency device streams.
+* **Log Rotation**: Logs are rotated at `10MB` sizes with 3 historical backups per log file, ensuring files never fill up the disk.
+
+---
+
+## Troubleshooting & Verification
+
+### Inspecting logs
+All logs are stored inside `/var/log/supervisor/` and `/app/logs/`.
+* Nginx: `/var/log/supervisor/nginx_stdout.log` / `nginx_stderr.log`
+* MongoDB: `/var/log/supervisor/mongodb_stdout.log`
+* CWMP: `/var/log/supervisor/cwmp_stdout.log`
+* Backups: `/var/log/supervisor/backup_scheduler_stdout.log`
+* Health Check Monitor: `/var/log/supervisor/healthcheck_stdout.log`
+
+### Verifying Service status
+You can run the health check script manually to query all internal ports:
+```bash
+/app/healthcheck.sh
+```
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Security Guidelines
+
+1. **MongoDB Shielding**: MongoDB is bound only to `127.0.0.1`. It cannot be reached from outside the container, and Nginx does not proxy its port.
+2. **Access Control**: On first initialization, secure random credentials are created for administrative database and app users, saving configuration details in `/data/mongodb_secrets.env`.
+3. **Reverse Proxy Security**: Directory listings are disabled, standard server headers are stripped, and strict Content Security Policies (CSP) are configured.

docker-entrypoint.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -e
+set -x
 
 # Hardcoded Default Variables (User only configures HF_TOKEN, ADMIN_PASSWORD, GENIEACS_UI_JWT_SECRET, HF_DATASET, and ADMIN_USERNAME)
 export BACKUP_INTERVAL=86400