kolonilinus/gacs-panel repository overview

⁠GenieACS Panel

Modern web dashboard for GenieACS TR-069 management. Built upon solusidigitalnet/genieacspanelapi:V1.7.0 with PostgreSQL database backend.

⁠Quick Start

⁠Prerequisites

• Docker & Docker Compose
• GenieACS server running and accessible

⁠Installation

1. Create a folder named gacs-panel.
2. Inside that folder, create a file named docker-compose.yml with the following content:

# ============================================
# GACS PANEL - CONFIGURATION
# ============================================
# Edit ONLY the values in this section, then run: docker compose up -d
#
# ⚠️  IMPORTANT: If you change credentials AFTER first run,
#     you must remove the volume first: docker compose down -v
# ============================================

x-db-config: &db-config
  DB_USER: &db_user gacs_admin # <-- EDIT: Database username
  DB_PASSWORD: &db_pass gacs_secret # <-- EDIT: Database password  
  DB_NAME: &db_name genieacs_panel # <-- EDIT: Database name

x-jwt-config: &jwt-config
  JWT_SECRET: change-this-secret-key # <-- EDIT: Change to a strong random string
  JWT_EXPIRES_IN: 1h # <-- EDIT: Token expiry (e.g., 1h, 30m, 1d)
  REFRESH_TOKEN_EXPIRES_IN: 7d # <-- EDIT: Refresh token expiry

# ============================================
# DO NOT EDIT BELOW THIS LINE
# ============================================

services:
  postgres:
    image: postgres:16-alpine
    container_name: genieacs-panel-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: *db_user
      POSTGRES_PASSWORD: *db_pass
      POSTGRES_DB: *db_name
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}" ]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    image: kolonilinus/gacs-panel:latest
    container_name: genieacs-panel-api
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "1997:1997"
    environment:
      NODE_ENV: production
      PORT: 1997
      DB_HOST: postgres
      DB_PORT: 5432
      DB_NAME: *db_name
      DB_USER: *db_user
      DB_PASSWORD: *db_pass
      DATABASE_URL: postgresql://gacs_admin:gacs_secret@postgres:5432/genieacs_panel # <-- EDIT: Must match credentials above
      <<: *jwt-config
    extra_hosts:
      - "host.docker.internal:host-gateway"

volumes:
  postgres_data:

1. Open a terminal in that folder and run:

docker-compose up -d

1. Access the dashboard at http://localhost:1977⁠

⁠Access

• Web Interface: http://localhost:1977⁠
• API Base URL: http://localhost:1977/api⁠

⁠Default Credentials

Role : admin
Username: admin
Password: mimin1234

Role : user / read only
Username: user
Password: user1234

⚠️ Important: Change the default password immediately after first login.

⁠Features

⁠Core Capabilities

• 📊 Real-time device monitoring and management
• 🔧 Remote configuration of TR-069 devices
• 📡 WiFi security configuration management
• 🗺️ Network topology mapping (ODC, ODP, ONT)
• 👥 Multi-vendor device support (Huawei, ZTE, FiberHome, Nokia)
• 📈 RX Power monitoring and thresholds
• 🔄 Automated device provisioning

⁠Recent Modifications

• ✅ Database Migration: Migrated from SQLite to PostgreSQL for improved performance and scalability
• ✅ Updated Credentials: Default admin credentials changed for security
• ✅ Enhanced Vendor Management: Added comprehensive vendor configuration support
• ✅ WiFi Security Config: Complete WiFi security parameter mapping for multiple device types
• ✅ Network Mapping: Added serialnumber field support for node tracking

⁠Environment Variables

⁠App Container

⁠PostgreSQL Container

⁠Configuration

⁠GenieACS Connection

Configure the GenieACS server URL in the application settings:

1. Navigate to Settings page
2. Update GenieACS URL field
3. Format: http://<genieacs-host>:7557/devices
4. Click Save Settings

⁠Vendor Management

The system supports multiple ONT vendors with pre-configured parameters:

• FiberHome - X_FH parameter prefix
• Huawei - X_HW parameter prefix
• ZTE CT-COM - X_CT-COM parameter prefix
• ZTE X_CU - X_CU parameter prefix
• ZTE X_ZTE-COM - X_ZTE-COM parameter prefix
• ZTE CMCC - X_CMCC parameter prefix
• Nokia - X_ALU-COM parameter prefix

⁠Architecture

┌─────────────────┐
│   Web Browser   │
└────────┬────────┘
         │ HTTP :1977
         ▼
┌─────────────────┐
│   gacs-panel    │ Node.js Application
│   (Express.js)  │ Port 1997 (internal)
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌──────┐  ┌──────────┐
│ Postgres│  │ GenieACS │
│  :5432  │  │  :7557   │
└──────┘  └──────────┘

⁠Changelog

⁠Version 2.0.0 (2026-01-09)

⁠Major Changes

• Database Migration: Complete migration from SQLite to PostgreSQL
  • Improved performance and scalability
  • Better concurrent access handling
  • Enhanced data integrity with foreign keys

⁠Database Schema Updates

• Added vendor management tables with complete parameter mapping
• Added WiFi security configuration with SSID-specific paths
• Added mapping nodes/edges for network topology
• Added serialnumber column to mapping_nodes table
• Fixed column naming consistency (is_active for vendors)

⁠Bug Fixes

• Fixed vendor status display (enabled/disabled mapping)
• Fixed WiFi Security Config blank page issue
• Fixed ODC/ODP node creation failures
• Fixed router definition errors in multiple endpoint files
• Fixed missing dotenv imports
• Fixed vendor update operations

⁠Security

• Updated default admin credentials
• Enhanced authentication middleware
• Improved session management

⁠Data Migration

• Migrated 7 vendor configurations from SQLite
• Migrated 7 WiFi security configurations
• Migrated 13 application settings
• Migrated virtual parameter paths

⁠Development

⁠Project Structure

gacs-panel/
├── server.js              # Main application server
├── db.js                  # PostgreSQL connection pool
├── docker-compose.yml     # Docker services configuration
├── public/                # Frontend static files
├── vendor-management.js   # Vendor CRUD operations
├── wifi-security-config.js# WiFi security configs
├── mapping-data.js        # Network topology management
└── [route-files].js       # Various API endpoints

⁠Running in Development

# Start with logs
docker-compose up

# Rebuild after code changes
docker-compose up --build

# Stop services
docker-compose down

# Stop and remove volumes (reset database)
docker-compose down -v

⁠Troubleshooting

⁠Cannot connect to GenieACS

• Verify GenieACS server is running
• Check GenieACS URL in settings
• Ensure network connectivity between containers
• For Docker: use container name instead of localhost

⁠Database connection errors

• Verify PostgreSQL container is running: docker-compose ps
• Check database credentials in environment variables
• Ensure PostgreSQL container is healthy: docker-compose logs postgres

⁠Vendor/WiFi Config showing blank

• Check browser console for errors (F12)
• Verify authentication token is valid
• Clear browser cache and cookies
• Check API response in Network tab

⁠Database Preservation (Reinstall/Update)

⚠️ CRITICAL: Preserving Your Data

When updating the container (e.g., pulling a new image version) or reinstalling, it is crucial to preserve your database volume.

⁠How to Update Safely

Run the following commands. This stops the containers but keeps the volumes:

# 1. Stop containers (Preseves data)
docker-compose down

# 2. Pull latest images
docker-compose pull

# 3. Start containers
docker-compose up -d

⁠❌ DANGER: Data Loss Risk

NEVER run docker-compose down -v unless you explicitly want to delete your entire database and configuration. The -v flag removes volumes.

⁠Backing up the Database

To create a backup of your PostgreSQL database:

docker exec -t genieacs-panel-db pg_dumpall -c -U gacs_admin > dump_$(date +%Y-%m-%d).sql

⁠Restoring the Database

To restore from a backup:

cat dump_YYYY-MM-DD.sql | docker exec -i genieacs-panel-db psql -U gacs_admin -d genieacs_panel

⁠License

MIT

⁠Support

For issues and questions, please refer to the original project documentation or create an issue in the repository.