OpenPolyConf

Self-hosted provisioning platform for Polycom VVX IP phones.

OpenPolyConf replaces manual phone configuration with a web UI that generates Polycom XML config files on demand, manages SIP credentials, BLF/speed-dial keys, and integrates with GenieACS for TR-069 remote management — all in a single Docker Compose stack.

v0.1 — Early Release. Core provisioning, multi-tenant management, and TR-069 integration are stable. See Changelog for what's included.

AI Disclosure: This project was built with the assistance of Claude Code (Anthropic). The architecture, feature decisions, and domain knowledge are the author's; the implementation was co-written with AI. Review the code accordingly before deploying in production.

---

Dashboard	Phone Editor
BLF & Soft Key Editor	Templates
Firmware Management	Firmware Upload
Setup Guide	Tenant Management

---

Features

• HTTP Provisioning — Phones pull their config from /polycom/{tenant-slug}/{mac}.cfg on every reboot. No manual file editing.
• Multi-tenant — Separate tenants, users, and phone pools. GlobalAdmin, TenantAdmin, and Technician roles.
• Visual Soft Key Editor — Click to configure on-hook, off-hook, and in-call soft keys per phone model (VVX 250, 410 supported; 350/450/501/601 in progress).
• BLF & Speed Dials — Drag-and-drop BLF key assignment, speed dial management.
• TR-069 / GenieACS — Reboot phones, push firmware, view live device parameters, summon phones for immediate config pickup.
• Config Versioning — Every provisioning render is stored. Diff between versions, roll back instantly.
• Firmware Management — Upload .ota files through the UI; phones auto-update via softwareUpgrade.* XML parameters.
• Template Inheritance — Define a base template, override per-tenant or per-phone. Up to 5 levels deep.
• Jinja2 Templates — All Polycom XML is rendered from editable Jinja2 templates. Edit live without rebuilding.
• Backup & Restore — One-click full backup (Postgres dump + firmware + config). Restore from the UI.
• Audit Log — Every provisioning event, config change, and ACS action is recorded.

Supported Phone Models

Model	HTTP Provisioning	Soft Key Editor	BLF
VVX 250	✅	✅	✅
VVX 350	✅	—	✅
VVX 410	✅	✅	✅
VVX 450	✅	—	✅
VVX 501	✅	—	✅
VVX 601	✅	—	✅

Tested on Polycom UC Software 5.9.x.

---

Quick Start

Requirements: Docker 24+ and Docker Compose v2 (Linux recommended).

git clone https://github.com/yourusername/openpolyconf.git
cd openpolyconf
make install

That's it. make install runs the interactive setup wizard, builds all images, starts every service, and seeds the database. At the end it prints your login URL.

If you prefer manual control:

make setup        # generate .env with all secrets
make build        # build Docker images
make up           # start all services
make init         # run migrations + seed database

Open http://<your-server> and log in with the admin email/password you set during make setup.

---

Architecture

Browser / Phones
      │
   nginx :80/:443
      ├─► /api/*          →  FastAPI backend (Python 3.12)
      ├─► /polycom/*      →  Provisioning endpoints (no auth)
      ├─► /cwmp           →  GenieACS CWMP :7547  (TR-069)
      ├─► /acs-ui/        →  GenieACS UI
      └─► /               →  React + Vite frontend
             │
             ├─ PostgreSQL 16   (phones, users, tenants, revisions)
             └─ MongoDB 7       (GenieACS device store)

Persistent data lives in ./data/ (bind-mounted, not Docker volumes) so backups are a simple tar of that directory.

---

Phone Setup

HTTP Provisioning (Option 66 / Manual):

Set the phone's provisioning server to:

http://<your-server>/polycom/<tenant-slug>

Username: polycom · Password: shown in the Setup Guide page.

The phone downloads 000000000000.cfg on first boot, which redirects it to its MAC-specific config file automatically.

TR-069 (optional, enables remote reboot, firmware push, live param reads):

ACS URL: http://<your-server>/cwmp

Credentials are shown in the app under Setup Guide.

---

Documentation

Guide	Description
Installation	Full install walkthrough, TLS, firewall
Multi-tenant	Tenant setup, roles, isolation
Firmware	Uploading and pushing firmware to phones
Backup & Restore	Manual and scheduled backups
Troubleshooting	Phone not provisioning, SIP issues, ACS
Deployment	Production checklist, Let's Encrypt

---

Contributing

Pull requests are welcome. Open an issue first for anything beyond a small bug fix. See CONTRIBUTING.md.

---

Changelog

v0.1 (2026-06)

• Initial public release
• Multi-tenant HTTP provisioning for VVX 250/350/410/450/501/601
• Visual soft key editor for VVX 250 and 410
• BLF drag-and-drop editor
• GenieACS TR-069 integration (reboot, summon, firmware push, param view)
• Config versioning, diff, and rollback
• Firmware upload and auto-update via provisioning XML
• Full backup and restore
• Audit log

---

License

OpenPolyConf is open-source software licensed under the GNU General Public License v3.0.

For commercial/proprietary licensing, contact mataruso@gmail.com.

Copyright © 2025-2026 Paul Mataruso

---

AI Disclosure

This project was built with the assistance of Claude Code by Anthropic. The author designed the architecture, defined requirements, made all product and technical decisions, and owns the domain knowledge (Polycom VVX provisioning, GenieACS TR-069, multi-tenant SaaS). AI was used as a coding assistant throughout development.

If you find bugs or unexpected behavior, please open an issue.