A comprehensive Prometheus development environment designed for local development and testing, featuring multiple deployment options, authentication support, and monitoring capabilities.

1. Development Environment Only: This Prometheus deployment is designed specifically for development and testing purposes. It is NOT intended for production use. For production deployments, please refer to the official Prometheus documentation and implement appropriate security hardening, high availability, and monitoring practices.

2. AI-Assisted Development: This project was developed with the assistance of AI tools, specifically Cursor and Claude AI. While every effort has been made to ensure code quality and security, please review and test thoroughly before using in your environment.

• Multiple Deployment Options: Node Exporter, PCP Exporter, or custom configurations
• Authentication Support: Basic Auth, Bearer Tokens, and API Tokens via Nginx reverse proxy
• Security Focused: Centralized credential management for safe development practices
• Easy Management: Comprehensive scripts for starting, stopping, and monitoring
• Flexible Configuration: Support for custom Prometheus builds and configurations
• Cross-Platform: Works with both Podman and Docker
• Monitoring Tools: Pre-configured exporters and sample queries

• Requirements
• Quick Start
• Installation
• Configuration
• Usage
• Architecture
• Security
• Troubleshooting
• Contributing
• License

• Container Runtime: Podman 3.0+ or Docker 20.10+
• Compose Tool: podman-compose or docker-compose
• Operating System: Linux, macOS, or Windows with WSL2
• Memory: Minimum 2GB RAM available
• Disk Space: At least 1GB free space

Optional:

• Python 3.8+ (for advanced authentication testing)
• htpasswd (for generating authentication files)

1. Clone the repository:

   git clone https://github.com/Avilir/prom-dev.git
   cd prom-dev

2. Start Prometheus (no authentication):

   ./scripts/start.sh

3. Access Prometheus:

   • Open http://localhost:9090 in your browser
   • Metrics available at http://localhost:9100/metrics (Node Exporter)

4. Check status:

   ./scripts/status.sh

5. Stop environment:

   ./scripts/stop.sh

For detailed installation instructions, see INSTALL.md.

1. Install container runtime:

   # Fedora/RHEL/CentOS
   sudo dnf install podman podman-compose
   
   # Ubuntu/Debian
   sudo apt install podman podman-compose
   
   # macOS
   brew install podman podman-compose

2. Verify installation:

   podman --version
   podman-compose --version

3. Configure firewall (if needed):

   ./scripts/firewall-setup.sh

1. Create credentials file:

   cp configs/credentials.env.example configs/credentials.env

2. Generate secure passwords:

   # Generate a secure password
   openssl rand -base64 32

3. Edit credentials:

   vim configs/credentials.env
   # Replace all CHANGE_ME values

4. Secure the file:

   chmod 600 configs/credentials.env

5. Start with authentication:

   ./scripts/start.sh --auth

• Node Exporter (default): System metrics collection
• PCP Exporter: Performance Co-Pilot integration
• Custom Build: Use your own Prometheus image
• Authentication: Nginx reverse proxy with multiple auth methods

# Default (Node Exporter, no auth)
./scripts/start.sh

# With authentication
./scripts/start.sh --auth

# Specific configuration
./scripts/start.sh --config node-exporter

# Check status
./scripts/status.sh

# View logs
./scripts/logs.sh prometheus-dev
./scripts/logs.sh node-exporter

# Run comprehensive tests (connectivity, auth, data collection)
./scripts/test.sh

# Advanced Python-based testing (optional)
./scripts/test-advanced.py

When authentication is enabled:

• Port 9090: Basic Auth + Bearer Token + API Token
• Port 9091: Bearer Token only
• Port 9092: API Token only

The queries/ directory contains example PromQL queries:

• basic.promql: Essential queries for getting started
• advanced.promql: Complex aggregations and calculations
• performance-testing.promql: Load testing queries

For detailed architecture information, see ARCHITECTURE.md.

1. Prometheus Server: Core time-series database
2. Exporters: Node Exporter or PCP for metrics collection
3. Nginx Proxy: Optional authentication layer
4. Scripts: Management and automation tools

prom-dev/
├── auth/                 # Authentication configuration
├── configs/             # Configuration files
├── docs/                # Documentation and examples
├── prometheus/          # Prometheus configurations
├── queries/             # Sample PromQL queries
├── scripts/             # Management scripts
│   └── lib/            # Shared script libraries
└── compose files        # Various deployment options

For security policies and reporting, see SECURITY.md.

1. Never commit credentials to version control
2. Use strong passwords (32+ characters)
3. Rotate credentials regularly
4. Limit network exposure using firewall rules
5. Enable authentication for production use

All credentials are centralized in configs/credentials.env:

• Basic authentication users and passwords
• Bearer tokens for API access
• API tokens for custom authentication

1. Port already in use:

   # Find process using port 9090
   sudo lsof -i :9090
   # Or change the port in compose files

2. Authentication failures:

   # Check credentials are loaded
   source scripts/test-credentials.sh
   # Verify htpasswd file exists
   ls -la auth/.htpasswd

3. Container startup issues:

   # Check logs
   ./scripts/logs.sh prometheus-dev
   # Verify compose file
   podman-compose -f podman-compose.yml config

1. Check the logs: ./scripts/logs.sh <container-name>
2. Run status check: ./scripts/status.sh
3. Enable verbose mode in scripts
4. Open an issue on GitHub

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

This project is licensed under the MIT License - see LICENSE for details.

• Prometheus - The monitoring system
• Node Exporter - Hardware and OS metrics
• Nginx - Authentication proxy
• Podman - Container runtime

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md for reporting vulnerabilities

Made with ❤️ by Avi Layani.
Developed with assistance from Cursor and Claude AI