How to Deploy GenieACS
In the summer of 2015, while working at CARTAGO Telecom (formerly Electrónica Martínez) and closing my studies, I stumbled upon TR-069 technology while searching for a worthy university project topic. I didn't know back then, but it would define a significant part of my career. Fast forward to today, GenieACS has become deeply ingrained not only in my professional journey but as a technology I've genuinely come to appreciate and contribute back to.
GenieACS is an open-source implementation of an Auto Configuration Server (ACS) designed to provision and manage TR-069 (or CWMP) compliant devices. Think routers, modems, set-top boxes, or VoIP phones—nearly any modern CPE (Customer Premises Equipment) you can deploy in the Telecom space. In 2015, TR-069 was still challenging, relatively opaque, and GenieACS resources, guides, or tutorials were minimal. This led to my passion and drive: improving the experience of deploying this technology.
Interestingly, TR-069 is a two-way management protocol between customer equipment and an ACS. Unlike simpler provisioning via DHCP66, TR-069 lets you dynamically interact with CPEs, remotely reboot, update firmware, troubleshoot, or configure devices—no more customer downtime for changing a single setting. In this sense, I highly recommend the "TR-069 Crash Course" from the University of New Hampshire—it clarified the foundational mechanisms, message exchanges, and the deep technicalities of TR-069.
Here, I'll share my proven strategies, learned insights, and detailed deployment instructions for GenieACS via Docker Compose and Kubernetes (Helmfile). Let’s dive deep! 🚀
Background: From Installation Guides to DockerHub
Initially, getting GenieACS running on Ubuntu was my first adventure; I was probably the first person to publish working installation instructions on GitHub. Later, at a new engagement, client constraints forced adoption into Red Hat-based systems, historically challenging to run Nodejs-based software—thus, Docker was my savior.
That's when everything started: I created a Docker container that you can now find on DockerHub, which today counts over 240K downloads. My idea was simple yet powerful: abstract away OS limitations and make GenieACS portable. Since then, the community has appreciated Docker as the easy way for GenieACS deployment across different operating systems. I believe sharing knowledge and solutions openly always brings positive returns in community esteem and professional fulfilment. Currently, the source code is available on GitHub here and here.
Deploying GenieACS via Docker Compose
Docker Compose simplifies deployments significantly. Here's how to get started quickly:
Step 1: Install Docker and Docker Compose
Ensure Docker and Docker Compose are installed:
curl -fsSL https://get.docker.com | sh
sudo apt install docker-compose -yStep 2: Start GenieACS services
Create a Docker Compose file (or clone my repository), and run:
services:
mongo:
image: mongo:7.0
restart: always
volumes:
- data_db:/data/db
networks:
- genieacs_network
genieacs:
depends_on:
- 'mongo'
image: drumsergio/genieacs:1.2.13
ports:
- "7547:7547"
- "7557:7557"
- "7567:7567"
- "3000:3000"
volumes:
- opt_volume:/opt
networks:
- genieacs_network
volumes:
data_db: {}
opt_volume: {}
networks:
genieacs_network:Run it in one line:
docker compose up -dNow your GenieACS UI should be reachable via port 3000.
Deploying in Kubernetes via Helmfile
Doing Kubernetes deployments can be slightly different, but once automated (like I did with the Helm and Helmfile setup), it's powerful. Below, I'll share the approach briefly:
Step 1: Add Helm Repos and Secrets
Modify and deploy your secrets beforehand (such as MongoDB access credentials):
kubectl apply -f mongo-secret.yamlStep 2: Have Helmfile Ready
A Helmfile manages deployments declaratively. Your helmfile.yaml should include:
repositories:
- name: bitnami
url: https://charts.bitnami.com/bitnami
- name: genieacs
url: https://geiserx.github.io/genieacs-docker
releases:
- name: mongodb-genieacs
namespace: genieacs
chart: bitnami/mongodb
values:
- mongo.yaml
- name: genieacs
namespace: genieacs
chart: genieacs/genieacs
values:
- genieacs.yamlDon't forget to also fill out mongo.yaml and genieacs.yaml. You can find some default values in the repository.
Step 3: Deploy via Helmfile
Then simply:
helmfile.yaml -i applyAnd that's it. You now should have it running in your Kubernetes cluster. Still, this chart needs a lot more care, and as I'm not using it actively, I just built the foundations where you can continue. I'd be more than happy to receive PRs in this regard.
Extra: Deployment with Ansible
I would like to show a brief example snippet from my original Ansible playbook from many years ago:
---
- hosts: all
remote_user: vagrant
tasks:
- name: Upgrade Debian
apt:
update_cache: yes
upgrade: yes
become: yes
become_user: root
- name: Install general tools
apt:
name:
- wget
- curl
- htop
- aptitude
- python-pip
become: yes
become_user: root
- firewalld:
service: ssh
permanent: true
state: enabled
become: yes
become_user: root
### INSTALLING DOCKER ###
- name: Install prerequisites for Docker
apt:
name:
- apt-transport-https
- ca-certificates
- curl
- gnupg2
- software-properties-common
become: yes
become_user: root
- name: Download Docker GPG key
get_url:
url: https://download.docker.com/linux/debian/gpg
dest: /tmp/docker_gpg
mode: 0755
- name: Add Docker public key
apt_key:
id: 0EBFCD88
file: /tmp/docker_gpg
become: yes
become_user: root
- name: Add Docker repository
apt_repository:
repo: deb [arch=amd64] https://download.docker.com/linux/debian stretch stable
become: yes
become_user: root
- name: Install Docker
apt:
name: docker-ce
become: yes
become_user: root
- name: Install Docker SDK to manage it from ansible
pip:
name: docker-py
become: yes
become_user: root
- name: Log into DockerHub
docker_login:
username: docker
password: docker
email: [email protected]
### DOCKER for MONGODB ###
- name: Pull MongoDB image
docker_image:
name: mongo:jessie
become: yes
become_user: root
- name: Create MongoDB container
docker_container:
name: mongo
image: mongo:jessie
volumes:
- /data:/data
exposed_ports: 27017
become: yes
become_user: root
### DOCKER for GENIEACS_BASE ###
- name: Copy GenieACS_Base Dockerfile
copy:
src: /home/drumsergio/Vagrant/GenieACS_Base.dockerfile
dest: /home/vagrant/GenieACS_Base.dockerfile
owner: root
group: root
become: yes
become_user: root
- name: Create docker image
docker_image:
dockerfile: /home/vagrant/GenieACS_Base.dockerfile
path: /home/vagrant/
name: genieacs_base
become: yes
become_user: root
- name: Create GenieACS_Base container
docker_container:
name: genieacs_base
image: genieacs_base
volumes:
- /opt/genieacs:/opt
exposed_ports:
- 7547
- 7557
- 7567
links: mongo
become: yes
become_user: rootThere is always a way, and I just wanted to show it to you with this playbook. In the end, it all comes to versatility. Although this is more oriented towards building a system and then using base Docker to run GenieACS instead of using Docker Compose, it's still interesting to share to you, in case you're using Ansible.
Conclusion & Next Steps
We have successfully detailed the steps for deploying a working instance of GenieACS via Docker Compose and Kubernetes/Helmfile, with an additional extra in Ansible. By abstracting operating system differences and leveraging Docker and Kubernetes advantages, we've simplified and streamlined the deployment journey significantly.
This post has strictly covered GenieACS deployment. However, deploying GenieACS is just step one. In my next post, I'll dive deeper into the practicalities of operating GenieACS: real-world tasks, firmware management, API automation, troubleshooting practices, and tips drawn from years of experience that significantly helped me overcome challenges in production.
Stay tuned—practical GenieACS insights coming soon!
