drumsergio/genieacs repository overview

⁠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:[email protected]/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).

⁠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

⁠Volumes

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

⁠Environment Variables

⁠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:

⁠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.