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 100K 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 -y

Step 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 -d

Now 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.yaml

Step 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.yaml

Don'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 apply

And 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: GenieACS Deployments with Ansible

I would like to show a brief example snippet from my original Ansible playbook from many years ago:

tasks:
  - name: Docker Install
    apt:
      name: docker-ce
    become: yes

  - name: Pull MongoDB
    docker_image:
      name: mongo:jessie

  - name: Deploy MongoDB Container
    docker_container:
      name: mongo
      image: mongo:jessie
      volumes:
        - /data:/data

  - name: Deploy GenieACS Docker Container
    docker_container:
      name: genieacs_base
      image: genieacs_base
      volumes:
        - /opt/genieacs:/opt
      links: mongo

There 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, it's interesting to share, nevertheless.

Conclusion & Next Steps

We have successfully detailed the steps for deploying a working instance of GenieACS via Docker Compose and Kubernetes/Helmfile. 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!