GenieACS Container

Production-ready Docker containers and deployment tools for GenieACS, an open-source TR-069 ACS.

Table of Contents

• Features
• Quick Start
• Deployment Methods
  • Docker Compose
  • Kubernetes with Helm
• Configuration
• Ports
• Volumes
• Environment Variables
• Maintainers
• Contributing
• GenieACS Ecosystem
• Related ISP Tools
• License

Features

• 🐳 Production-ready Docker images for GenieACS v1.2.16.0
• ☸️ Official Helm chart for Kubernetes deployments
• 🔄 Automated chart releases via GitHub Actions
• 🔒 Security best practices (non-root user, security contexts, etc.)
• 📊 Health checks and monitoring support
• 📦 Multi-architecture support (amd64, arm64)

Quick Start

Docker Compose

The fastest way to get started:

docker compose up -d

This will start:

• GenieACS (ports 7547, 7557, 7567, 3000)
• MongoDB (internal port 27017)

Access the GenieACS UI at: http://localhost:3000

Docker Run

docker run -d \
  --name genieacs \
  -p 7547:7547 \
  -p 7557:7557 \
  -p 7567:7567 \
  -p 3000:3000 \
  -e GENIEACS_MONGODB_CONNECTION_URL=mongodb://your-mongo-host/genieacs \
  -e GENIEACS_UI_JWT_SECRET=your-secret-here \
  drumsergio/genieacs:1.2.16.0

Deployment Methods

Docker Compose

The included docker-compose.yml provides a complete stack with GenieACS and MongoDB:

# Start all services
docker compose up -d

# View logs
docker compose logs -f genieacs

# Stop all services
docker compose down

# Stop and remove volumes
docker compose down -v

Optional Services:

• genieacs-sim: Testing simulator (use --profile testing)
• genieacs-mcp: MCP Server (use --profile mcp)

Kubernetes with Helm

Using the Official Chart Repository

Add the chart repository:

helm repo add genieacs https://geiserx.github.io/genieacs-container
helm repo update

Install GenieACS:

helm install genieacs genieacs/genieacs \
  --namespace genieacs \
  --create-namespace \
  --set env.GENIEACS_UI_JWT_SECRET=your-secret-here

This deploys GenieACS with a MongoDB instance included by default (no auth). For production with MongoDB auth:

helm install genieacs genieacs/genieacs \
  --namespace genieacs \
  --create-namespace \
  --set mongodb.auth.enabled=true \
  --set mongodb.auth.rootPassword=your-secure-password \
  --set env.GENIEACS_UI_JWT_SECRET=your-secret-here

To use an external MongoDB (connection string inline):

helm install genieacs genieacs/genieacs \
  --namespace genieacs \
  --create-namespace \
  --set mongodb.enabled=false \
  --set externalMongodb.url=mongodb://your-mongo-host/genieacs

To use an external MongoDB with the connection string sourced from a Kubernetes Secret (recommended for production — keeps credentials out of values files and out of the pod spec):

kubectl create secret generic genieacs-mongodb \
  --namespace genieacs \
  --from-literal=connectionString="mongodb+srv://user:pass@cluster.example.net/genieacs?retryWrites=true"

helm install genieacs genieacs/genieacs \
  --namespace genieacs \
  --create-namespace \
  --set mongodb.enabled=false \
  --set externalMongodb.existingSecret=genieacs-mongodb

This pattern integrates with External Secrets Operator, Sealed Secrets, Vault, and operators that write connection details to a Kubernetes Secret (MongoDB Atlas Operator, MongoDB Controllers for Kubernetes (MCK), the Percona Operator).

Production note: The bundled Bitnami MongoDB subchart is intended for development and evaluation only. For production deployments, run MongoDB separately — managed (MongoDB Atlas), operator-managed (MCK, Percona Operator for MongoDB), or self-hosted — and point the chart at it using externalMongodb.existingSecret.

Using Helmfile

See the examples directory for a complete Helmfile deployment example:

helmfile -f examples/helmfile.yaml apply

Chart Configuration

Key configuration options in values.yaml:

image:
  repository: drumsergio/genieacs
  tag: "1.2.16.0"

replicaCount: 1

ingress:
  enabled: false
  className: ""  # e.g. "nginx", "traefik"

env:
  GENIEACS_UI_JWT_SECRET: changeme

# Inject env vars from Kubernetes Secrets/ConfigMaps
envFrom: []
# - secretRef:
#     name: genieacs-secrets

# Env vars with valueFrom (e.g. secretKeyRef)
extraEnvVars: []

# Bitnami MongoDB subchart (deployed alongside GenieACS by default)
mongodb:
  enabled: true
  auth:
    enabled: false
  persistence:
    enabled: true
    size: 8Gi

# Used when mongodb.enabled is false (bring your own MongoDB).
# Set either `url` directly, or `existingSecret` + `secretKey` to
# source the connection string from a Kubernetes Secret (recommended
# for production). If both are set, `existingSecret` takes precedence.
externalMongodb:
  url: ""
  existingSecret: ""
  secretKey: "connectionString"

persistence:
  enabled: true
  size: 5Gi

resources:
  limits:
    memory: 4Gi
  requests:
    cpu: 500m
    memory: 2Gi

For complete configuration options, see charts/genieacs/values.yaml.

Configuration

Ports

Port	Service	Description
7547	CWMP	TR-069 ACS port for device communication
7557	NBI	Northbound Interface API
7567	FS	File Server for firmware/configuration files
3000	UI	Web-based user interface

Volumes

• /opt/genieacs/ext: Extension scripts directory
• /var/log/genieacs: Log files directory

Environment Variables

Variable	Description	Default
GENIEACS_MONGODB_CONNECTION_URL	MongoDB connection string	Auto-configured when mongodb.enabled=true
GENIEACS_UI_JWT_SECRET	JWT secret for UI authentication	changeme
GENIEACS_EXT_DIR	Extension scripts directory	/opt/genieacs/ext
GENIEACS_CWMP_ACCESS_LOG_FILE	CWMP access log path	/var/log/genieacs/genieacs-cwmp-access.log
GENIEACS_NBI_ACCESS_LOG_FILE	NBI access log path	/var/log/genieacs/genieacs-nbi-access.log
GENIEACS_FS_ACCESS_LOG_FILE	FS access log path	/var/log/genieacs/genieacs-fs-access.log
GENIEACS_UI_ACCESS_LOG_FILE	UI access log path	/var/log/genieacs/genieacs-ui-access.log
GENIEACS_DEBUG_FILE	Debug log path	/var/log/genieacs/genieacs-debug.yaml

Building the Image

To build the Docker image locally:

docker build -t drumsergio/genieacs:1.2.16.0 .

For multi-architecture builds:

docker buildx build --platform linux/amd64,linux/arm64 \
  -t drumsergio/genieacs:1.2.16.0 \
  -t drumsergio/genieacs:latest \
  --push .

Security Considerations

• The container runs as a non-root user (genieacs)
• Security contexts are configured in the Helm chart
• Default JWT secret should be changed in production
• Use envFrom or extraEnvVars to inject secrets from Kubernetes Secrets instead of hardcoding in values.yaml
• MongoDB authentication should be enabled for production deployments

Troubleshooting

Check Container Logs

docker compose logs genieacs

Verify MongoDB Connection

docker compose exec genieacs ping mongo

Access Container Shell

docker compose exec genieacs /bin/bash

Maintainers

@GeiserX

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

GenieACS-Container follows the Contributor Covenant Code of Conduct.

GenieACS Ecosystem

This image is part of a broader set of tools for working with GenieACS:

Project	Type	Description
genieacs-ansible	Ansible Collection	Dynamic inventory plugin and device management modules
genieacs-mcp	MCP Server	AI-assisted device management via MCP
genieacs-ha	HA Integration	Home Assistant integration for TR-069 monitoring
n8n-nodes-genieacs	n8n Node	Workflow automation for GenieACS
genieacs-services	Service Defs	Systemd/Supervisord service definitions
genieacs-sim-container	Simulator	Docker-based GenieACS simulator for testing

The simulator is also available as an optional Docker Compose profile in this repo (--profile testing).

Related ISP Tools

• router-express — Auto-configure routers and sync databases
• services-isp — Automate common ISP operational tasks
• statix — Real-time ISP network statistics dashboard
• ScriptPoblar — Batch device provisioning and CRM operations

License

This project is licensed under the same license as GenieACS. See LICENSE file for details.