Version 2.0.0-3 Alpha | Installation Guide | Update Guide | Troubleshooting
A user-friendly web interface for managing your Puppet infrastructure. Think of it as a control center for all your servers - you can see what's happening, fix problems, and make changes from one place.
OpenVox GUI is like a dashboard for your car, but for your servers. If you use Puppet to manage your servers (and if you don't know what Puppet is, think of it as software that keeps all your servers configured correctly), then OpenVox GUI gives you a visual way to:
- See what's happening - Which servers are healthy, which ones have problems
- Find and fix issues - Click through to see exactly what went wrong
- Make changes - Update configurations without typing commands
- Run commands - Execute tasks on multiple servers at once
| Dashboard | Node Details | Orchestration |
|---|---|---|
 |
 |
 |
If you just want to get up and running quickly:
# Clone the repository
git clone https://github.com/cvquesty/openvox-gui.git
cd openvox-gui
# Run the installer (it will ask you questions)
sudo ./install.sh
# Open your web browser and go to:
# https://your-server-name:4567That's it! For detailed installation instructions, see the Installation Guide.
- Installation Guide - Step-by-step guide for new installations
- Update Guide - How to update to newer versions
- LDAP / Active Directory Guide - Configure enterprise authentication
- Troubleshooting - Solutions to common problems
See everything at a glance:
- How many servers are running fine vs having problems
- Recent activity and changes
- System health indicators
- Who's currently using the system
Click on any server to see:
- What changed in the last update
- Any errors or warnings
- Performance metrics (how long things took)
- Complete logs of what happened
Deploy new configurations to your servers:
- One button to update everything
- Choose specific environments to update
- See the results in real-time
- Keep a history of all deployments
Run commands on multiple servers at once:
- Execute shell commands across your fleet
- Run pre-built tasks and plans
- See the output from each server
- Save commonly used commands
Control what software and settings each server gets:
- Set defaults for all servers
- Create groups of servers with similar needs
- Override settings for individual servers
- Preview changes before applying them
Edit your configuration files directly:
- Browse and edit Hiera data files (server settings)
- Edit configuration files with syntax checking
- Automatic backups before changes
- Create and delete files as needed
Manage server certificates (like ID cards for servers):
- View all certificates and their status
- Sign new certificates to allow servers to connect
- Revoke certificates for decommissioned servers
- See certificate details and expiration dates
Search and explore your infrastructure:
- Fact Explorer: Find servers by their properties (OS, memory, etc.)
- Resource Explorer: Search for installed software, services, files
- PQL Console: Run advanced queries (for power users)
Choose how the interface looks:
- Casual Mode: Fun, colorful interface with animations
- Formal Mode: Clean, professional business interface
You need a Linux server with:
- Operating System: Red Hat 8+, CentOS 8+, Ubuntu 20.04+, or similar
- Memory: At least 2GB RAM (4GB recommended)
- Disk Space: 1GB free space
- Python: Version 3.10 or newer (3.11+ recommended)
- Network: Access to your PuppetServer and PuppetDB
The installer will set up:
- A web server running on port 4567 (configurable)
- A systemd service that starts automatically
- All necessary Python packages in a virtual environment
- A local database for storing settings
- Log files in
/opt/openvox-gui/logs
After installation:
- URL:
https://your-server:4567 - Username:
admin - Password: Check the file
/opt/openvox-gui/config/.credentials
Important: Change the default password immediately after your first login!
# Check if it's running
sudo systemctl status openvox-gui
# Stop the service
sudo systemctl stop openvox-gui
# Start the service
sudo systemctl start openvox-gui
# Restart (after making changes)
sudo systemctl restart openvox-gui# See recent log entries
sudo journalctl -u openvox-gui -n 50
# Watch logs in real-time (press Ctrl+C to stop)
sudo journalctl -u openvox-gui -f# Add a new user
cd /opt/openvox-gui
sudo ./scripts/manage_user.py add newuser --role operator
# Change a password
sudo ./scripts/manage_user.py passwd username
# Delete a user
sudo ./scripts/manage_user.py delete username
# List all users
sudo ./scripts/manage_user.py listThis is a major release introducing enterprise authentication:
- Split authentication: Authenticate users against LDAP (OpenLDAP, 389 DS, Red Hat Directory Server, or Active Directory) while managing roles locally
- Per-user auth source: Each user can be individually set to authenticate via LDAP or local password — configurable when creating users and changeable at any time
- Auto-provisioning: New LDAP users are created automatically on first login with roles derived from LDAP group membership
- Group-to-role mapping: Map LDAP groups to Admin, Operator, and Viewer roles
- Quick presets: One-click configuration templates for OpenLDAP, 389 DS / Red Hat DS, and Active Directory
- Connection testing: Test LDAP connectivity with diagnostic feedback before saving
- Backward compatible: Local accounts continue to work for service accounts and break-glass access
- LDAP/AD configuration has been extracted to its own dedicated Auth Settings tab in the Settings page
- Settings tabs are now: Application Settings → Services → User Manager → Auth Settings
- Add User form now includes an Authentication Source selector (LDAP / Local) — defaults to LDAP
- Password field only shown when creating local users
- New "Change auth source" action button per user in the user table
- Source column shows colored badges indicating local vs LDAP authentication
The application version is defined in a single file (VERSION) at the repository root. All backend, frontend, installer, and documentation references read from this file automatically — there is no version string to maintain anywhere else.
- 1.4.8: Fixed Run Puppet button (uses
bolt command runinstead of missing task) - 1.4.7: Resolved all Dependabot security alerts; upgraded Python 3.9 → 3.11
- 1.4.6: Vite security update (4.x → 5.4.21)
- 1.4.5: Ghost user prevention (username whitespace stripping)
- 1.4.4: Initial centralized version management
- 1.4.3: User deletion bug fix; comprehensive security headers
For a complete list of changes, see the Changelog.
- Check the Troubleshooting Guide: TROUBLESHOOTING.md has solutions to common problems
- Look at the Logs: Run
sudo journalctl -u openvox-gui -n 100to see recent errors - Check Your Network: Make sure you can reach PuppetServer and PuppetDB from this server
- File an Issue: Visit GitHub Issues to report bugs
- GitHub: https://github.com/cvquesty/openvox-gui
- Discussions: Use GitHub Discussions for questions and ideas
- Contributing: Pull requests welcome! See CONTRIBUTING.md
This project is licensed under the Apache 2.0 License. This means you can:
- Use it for free (even commercially)
- Modify it to suit your needs
- Distribute it to others
- Just keep the license notice intact
See the LICENSE file for the legal details.
Built with love for the Puppet community. Special thanks to:
- The Vox Pupuli community for maintaining Puppet modules
- All contributors who have submitted bugs, suggestions, and code
- You, for using OpenVox GUI!
Ready to get started? Head over to the Installation Guide for step-by-step instructions!