GetHomepage Integration Guide

Overview

PatchMon provides a seamless integration with GetHomepage (formerly Homepage), allowing you to display real-time PatchMon statistics in your GetHomepage dashboard. This integration uses authenticated API endpoints to securely fetch and display your patch management data.

Features

By default, the GetHomepage widget displays:

Total Hosts - Number of active monitored hosts
Hosts Needing Updates - Hosts with outdated packages
Security Updates - Number of security-related updates available

Additional Available Data

The API provides additional metrics that you can display by customizing the widget mappings:

Up-to-Date Hosts - Hosts with no pending updates
Total Outdated Packages - Aggregate count of packages needing updates
Total Repositories - Number of active repositories
Recent Updates (24h) - Update activity in the last 24 hours
Hosts with Security Updates - Number of hosts requiring security patches
OS Distribution - Breakdown of operating systems across hosts (returned in API but requires custom formatting)

Prerequisites

PatchMon instance running and accessible
GetHomepage installed and configured
Network access from GetHomepage to PatchMon
HTTPS recommended (but HTTP works with fallback clipboard)

Setup Instructions

Step 1: Create an API Key in PatchMon

Log in to PatchMon as an administrator
Navigate to Settings → Integrations
Click on the GetHomepage tab
Click "New API Key" button
Fill in the token details:
- Token Name: A descriptive name (e.g., "GetHomepage Widget")
- Allowed IP Addresses (Optional): Restrict access to specific IPs
- Expiration Date (Optional): Set an expiration if needed
Click "Create Token"

Step 2: Save Your Credentials

After creating the token, you'll see a success modal with:

Token Key: Your API username
Token Secret: Your API password (shown only once!)
Base64 Encoded Credentials: Pre-encoded for convenience
Complete Widget Configuration: Ready-to-use YAML

⚠️ Important: Save the token secret immediately. You won't be able to view it again!

Step 3: Configure GetHomepage

Method A: Copy Complete Configuration (Recommended)

In the PatchMon success modal, click "Copy Config" button
Open your GetHomepage services.yml file
Paste the copied configuration
Save the file
Restart GetHomepage

The default configuration displays 3 key metrics:

- PatchMon:
    href: http://your-patchmon-url:3000
    description: PatchMon Statistics
    icon: http://your-patchmon-url:3000/assets/favicon.svg
    widget:
      type: customapi
      url: http://your-patchmon-url:3000/api/v1/gethomepage/stats
      headers:
        Authorization: Basic <base64_encoded_credentials>
      mappings:
        - field: total_hosts
          label: Total Hosts
        - field: hosts_needing_updates
          label: Needs Updates
        - field: security_updates
          label: Security Updates

Note: You can add more fields to the mappings section. See Configuration Options below for all available fields.

Method B: Manual Configuration

If you need to manually create the base64 credentials:

Encode your credentials:

echo -n "YOUR_API_KEY:YOUR_API_SECRET" | base64

Create the widget configuration in services.yml:

- PatchMon:
    href: http://your-patchmon-url:3000
    description: PatchMon Statistics
    icon: http://your-patchmon-url:3000/assets/favicon.svg
    widget:
      type: customapi
      url: http://your-patchmon-url:3000/api/v1/gethomepage/stats
      headers:
        Authorization: Basic <your_base64_credentials>
      mappings:
        - field: total_hosts
          label: Total Hosts
        - field: hosts_needing_updates
          label: Needs Updates
        - field: security_updates
          label: Security Updates

Restart GetHomepage:

docker restart gethomepage
# or
systemctl restart gethomepage

Configuration Options

You can customize which statistics to display by adding or removing fields in the mappings section. The API provides 8 numeric metrics you can choose from.

How to Customize Mappings

Locate the mappings: section in your GetHomepage services.yml
Add or remove field entries - each entry has two parts:
- field: - The metric name from the API (see table below)
- label: - How it appears in GetHomepage (customize as you like)
You can display up to ~6-8 metrics before the widget becomes crowded
Save and restart GetHomepage to see changes

Available Fields

Field	Description	Default
`total_hosts`	Total number of active hosts	✅ Yes
`hosts_needing_updates`	Hosts with outdated packages	✅ Yes
`security_updates`	Number of security updates available	✅ Yes
`up_to_date_hosts`	Hosts with no pending updates	❌ No
`total_outdated_packages`	Total outdated packages across all hosts	❌ No
`hosts_with_security_updates`	Hosts requiring security updates	❌ No
`total_repos`	Number of active repositories	❌ No
`recent_updates_24h`	Successful updates in last 24 hours	❌ No
`top_os_1_count`	Count of most common OS (e.g., "Ubuntu: 20")	❌ No
`top_os_2_count`	Count of 2nd most common OS	❌ No
`top_os_3_count`	Count of 3rd most common OS	❌ No

Note: Fields marked with ❌ are available but not included in the default configuration. Add them to your mappings section to display them.

OS Distribution: The API also returns top_os_1_name, top_os_2_name, and top_os_3_name (strings like "Ubuntu", "Debian", "Rocky Linux"). However, GetHomepage widgets display these awkwardly. It's better to use just the count fields with custom labels that include the OS name (see examples below).

Quick Start: Adding a Metric

Example: Add "Recent Updates (24h)" to your widget

Before (Default - 3 metrics):

mappings:
  - field: total_hosts
    label: Total Hosts
  - field: hosts_needing_updates
    label: Needs Updates
  - field: security_updates
    label: Security Updates

After (Custom - 4 metrics):

mappings:
  - field: total_hosts
    label: Total Hosts
  - field: hosts_needing_updates
    label: Needs Updates
  - field: security_updates
    label: Security Updates
  - field: recent_updates_24h        # ← Added this line
    label: Updated (24h)              # ← And this line

You can add any combination of the 8 available fields. Just ensure the field: name matches exactly as shown in the table above.

Advanced Mapping Examples

Example: Security-Focused Widget

Shows security-critical metrics only:

widget:
  type: customapi
  url: http://your-patchmon-url:3000/api/v1/gethomepage/stats
  headers:
    Authorization: Basic <credentials>
  mappings:
    - field: security_updates
      label: Security Patches
    - field: hosts_with_security_updates
      label: Hosts at Risk
    - field: hosts_needing_updates
      label: Total Pending

Example: Repository Management Widget

Focus on repository and host counts:

widget:
  type: customapi
  url: http://your-patchmon-url:3000/api/v1/gethomepage/stats
  headers:
    Authorization: Basic <credentials>
  mappings:
    - field: total_repos
      label: Repositories
    - field: total_hosts
      label: Managed Hosts
    - field: up_to_date_hosts
      label: Up-to-Date

Example: Activity Monitoring Widget

Track recent update activity:

widget:
  type: customapi
  url: http://your-patchmon-url:3000/api/v1/gethomepage/stats
  headers:
    Authorization: Basic <credentials>
  mappings:
    - field: recent_updates_24h
      label: Updated (24h)
    - field: hosts_needing_updates
      label: Pending Updates
    - field: up_to_date_hosts
      label: Fully Patched

Example: Package-Focused Widget

Monitor outdated packages:

widget:
  type: customapi
  url: http://your-patchmon-url:3000/api/v1/gethomepage/stats
  headers:
    Authorization: Basic <credentials>
  mappings:
    - field: total_outdated_packages
      label: Outdated Packages
    - field: security_updates
      label: Security Updates
    - field: hosts_needing_updates
      label: Affected Hosts

Example: OS Distribution Widget

Show your infrastructure breakdown by operating system:

widget:
  type: customapi
  url: http://your-patchmon-url:3000/api/v1/gethomepage/stats
  headers:
    Authorization: Basic <credentials>
  mappings:
    - field: total_hosts
      label: Total Hosts
    - field: top_os_1_count
      label: Ubuntu Hosts        # Customize these labels based on your actual OS mix
    - field: top_os_2_count
      label: Debian Hosts
    - field: top_os_3_count
      label: Rocky Linux Hosts

Pro Tip: First test the endpoint with curl to see what your actual top 3 operating systems are, then customize the labels accordingly. The API returns the OS names in top_os_1_name, top_os_2_name, and top_os_3_name.

Custom Icon

By default, the widget uses PatchMon's favicon. You can customize it:

# Use PatchMon's dark logo
icon: http://your-patchmon-url:3000/assets/logo_dark.png

# Use PatchMon's light logo
icon: http://your-patchmon-url:3000/assets/logo_light.png

# Use GetHomepage's built-in icons
icon: server

# Use a local icon in GetHomepage
icon: /icons/patchmon.png

API Endpoint Details

Endpoint

GET /api/v1/gethomepage/stats

Authentication

Type: HTTP Basic Authentication
Format: Authorization: Basic <base64(key:secret)>

Response Format

The endpoint returns JSON with the following structure:

{
  "total_hosts": 42,
  "total_outdated_packages": 156,
  "total_repos": 12,
  "hosts_needing_updates": 15,
  "up_to_date_hosts": 27,
  "security_updates": 23,
  "hosts_with_security_updates": 8,
  "recent_updates_24h": 34,
  "os_distribution": [
    { "name": "Ubuntu", "count": 20 },
    { "name": "Debian", "count": 12 },
    { "name": "Rocky Linux", "count": 10 }
  ],
  "top_os_1_name": "Ubuntu",
  "top_os_1_count": 20,
  "top_os_2_name": "Debian",
  "top_os_2_count": 12,
  "top_os_3_name": "Rocky Linux",
  "top_os_3_count": 10,
  "last_updated": "2025-10-11T12:34:56.789Z"
}

All Available Metrics Explained

All numeric fields can be used in GetHomepage mappings:

Field	Type	Description	Use Case
`total_hosts`	Number	Total active hosts in PatchMon	Overall infrastructure size
`hosts_needing_updates`	Number	Hosts with at least one outdated package	Hosts requiring attention
`up_to_date_hosts`	Number	Hosts with zero outdated packages	Compliant/healthy hosts
`security_updates`	Number	Total security updates available across all hosts	Critical patches needed
`hosts_with_security_updates`	Number	Hosts requiring security patches	High-risk hosts
`total_outdated_packages`	Number	Sum of all outdated packages	Total patching workload
`total_repos`	Number	Active repositories being monitored	Repository coverage
`recent_updates_24h`	Number	Successful updates in last 24 hours	Recent patching activity
`top_os_1_name`	String	Name of most common OS	OS breakdown
`top_os_1_count`	Number	Count of most common OS	OS breakdown
`top_os_2_name`	String	Name of 2nd most common OS	OS breakdown
`top_os_2_count`	Number	Count of 2nd most common OS	OS breakdown
`top_os_3_name`	String	Name of 3rd most common OS	OS breakdown
`top_os_3_count`	Number	Count of 3rd most common OS	OS breakdown
`os_distribution`	Array	Full breakdown of OS types (for advanced use)	Infrastructure composition
`last_updated`	String (ISO 8601)	Timestamp of when stats were generated	Data freshness

Note: The API provides top 3 OS distribution data as flat fields (top_os_*) that can be easily displayed in GetHomepage widgets. The full os_distribution array is also available for custom integrations.

Health Check Endpoint

GET /api/v1/gethomepage/health

Returns basic health status and API key name.

Managing API Keys

View Existing Keys

Go to Settings → Integrations → GetHomepage
View all created API keys with:
- Token name
- Creation date
- Last used timestamp
- Active/Inactive status
- Expiration date (if set)

Disable/Enable Keys

Click the "Disable" or "Enable" button on any API key to toggle its status.

Delete Keys

Click the trash icon to permanently delete an API key. This action cannot be undone.

Security Features

IP Restrictions: Limit API key usage to specific IP addresses
Expiration Dates: Set automatic expiration for temporary access
Last Used Tracking: Monitor when keys are being used
One-Time Secret Display: Token secrets are only shown once at creation

Troubleshooting

Error: "Missing or invalid authorization header"

Cause: GetHomepage isn't sending the Authorization header correctly.

Solution:

Verify the headers: section is properly indented in services.yml
Ensure base64 credentials are correctly encoded
Check for extra spaces or line breaks in the configuration
Verify you're using type: customapi (not another widget type)

Error: "Invalid API key"

Cause: The API key doesn't exist or was deleted.

Solution:

Verify the API key exists in PatchMon (Settings → Integrations)
Create a new API key if needed
Update GetHomepage configuration with new credentials

Error: "API key is disabled"

Cause: The API key has been disabled in PatchMon.

Solution:

Go to Settings → Integrations → GetHomepage
Click "Enable" on the API key

Error: "API key has expired"

Cause: The API key has passed its expiration date.

Solution:

Create a new API key without expiration
Or create a new key with a future expiration date
Update GetHomepage configuration

Error: "IP address not allowed"

Cause: GetHomepage's IP address is not in the allowed list.

Solution:

Check GetHomepage's IP address
Update the API key's allowed IP ranges in PatchMon
Or remove IP restrictions if not needed

Checklist:

GetHomepage can reach PatchMon URL (test with curl)
API key is active and not expired
Base64 credentials are correct
services.yml syntax is valid YAML
GetHomepage has been restarted after config changes
Check GetHomepage logs for error messages

Testing the API Endpoint

Test the endpoint manually to see all available metrics:

# Step 1: Encode your credentials
echo -n "your_key:your_secret" | base64
# Output: eW91cl9rZXk6eW91cl9zZWNyZXQ=

# Step 2: Test the endpoint with your credentials
curl -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  http://your-patchmon-url:3000/api/v1/gethomepage/stats

Expected response: JSON with all 8 core metrics plus OS distribution:

{
  "total_hosts": 42,
  "hosts_needing_updates": 15,
  "security_updates": 23,
  "up_to_date_hosts": 27,
  "total_outdated_packages": 156,
  "hosts_with_security_updates": 8,
  "total_repos": 12,
  "recent_updates_24h": 34,
  "top_os_1_name": "Ubuntu",
  "top_os_1_count": 20,
  "top_os_2_name": "Debian",
  "top_os_2_count": 12,
  "top_os_3_name": "Rocky Linux",
  "top_os_3_count": 10,
  "os_distribution": [...],
  "last_updated": "2025-10-11T12:34:56.789Z"
}

Any of these numeric fields (including top_os_*_count) can be used in your GetHomepage mappings!

To find out what your top 3 operating systems are, look for the top_os_1_name, top_os_2_name, and top_os_3_name values in the response.

Pretty Print for Easy Reading

Use jq to format the output nicely:

curl -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  http://your-patchmon-url:3000/api/v1/gethomepage/stats | jq

This makes it easier to see what metrics your instance provides.

How to Display Your OS Distribution

Step 1: Discover your top operating systems

Run the curl command and look for these fields:

curl -s -H "Authorization: Basic YOUR_BASE64_CREDENTIALS" \
  http://your-patchmon-url:3000/api/v1/gethomepage/stats | jq '{top_os_1_name, top_os_1_count, top_os_2_name, top_os_2_count, top_os_3_name, top_os_3_count}'

Example output:

{
  "top_os_1_name": "Ubuntu",
  "top_os_1_count": 35,
  "top_os_2_name": "Debian",
  "top_os_2_count": 18,
  "top_os_3_name": "Rocky Linux",
  "top_os_3_count": 12
}

Step 2: Add to your GetHomepage widget

Use the count fields (top_os_*_count) and label them with your actual OS names:

mappings:
  - field: total_hosts
    label: Total Hosts
  - field: top_os_1_count
    label: Ubuntu          # Use your actual OS from top_os_1_name
  - field: top_os_2_count
    label: Debian          # Use your actual OS from top_os_2_name
  - field: top_os_3_count
    label: Rocky Linux     # Use your actual OS from top_os_3_name

Step 3: Restart GetHomepage

docker restart gethomepage
# or
systemctl restart gethomepage

Security Best Practices

Use HTTPS: Always use HTTPS in production for encrypted communication
IP Restrictions: Limit API key usage to GetHomepage's IP address
Set Expiration: Use expiration dates for temporary access
Regular Rotation: Rotate API keys periodically
Monitor Usage: Check "Last Used" timestamps for suspicious activity
Unique Keys: Create separate API keys for different GetHomepage instances
Secure Storage: Store GetHomepage services.yml securely with proper permissions

Complete Working Examples

Copy-Paste Ready Configurations

These are complete, working configurations you can copy directly into your services.yml file. Just replace the placeholders with your actual values.

Simple Dashboard Widget (Default)

This is the default configuration generated by PatchMon:

- PatchMon:
    href: https://patchmon.example.com
    description: Patch Management
    icon: https://patchmon.example.com/assets/favicon.svg
    widget:
      type: customapi
      url: https://patchmon.example.com/api/v1/gethomepage/stats
      headers:
        Authorization: Basic dXNlcjpwYXNzd29yZA==
      mappings:
        - field: total_hosts
          label: Total Hosts
        - field: hosts_needing_updates
          label: Needs Updates
        - field: security_updates
          label: Security Updates

Detailed Monitoring Widget (Custom)

This example shows how to display 4 metrics including recent activity:

- PatchMon Production:
    href: https://patchmon.example.com
    description: Production Environment Patches
    icon: https://patchmon.example.com/assets/logo_dark.png
    widget:
      type: customapi
      url: https://patchmon.example.com/api/v1/gethomepage/stats
      headers:
        Authorization: Basic dXNlcjpwYXNzd29yZA==
      mappings:
        - field: total_hosts
          label: Total Servers
        - field: hosts_needing_updates
          label: Needs Patching
        - field: security_updates
          label: Security Patches
        - field: recent_updates_24h
          label: Patched Today

Multiple Environments (Custom)

This example shows different metrics for different environments:

# Production - Focus on security
- PatchMon Prod:
    href: https://patchmon-prod.example.com
    description: Production Patches
    icon: https://patchmon-prod.example.com/assets/favicon.svg
    widget:
      type: customapi
      url: https://patchmon-prod.example.com/api/v1/gethomepage/stats
      headers:
        Authorization: Basic <prod_credentials>
      mappings:
        - field: total_hosts
          label: Hosts
        - field: security_updates
          label: Security
        - field: hosts_needing_updates
          label: Pending

# Development - Focus on package count
- PatchMon Dev:
    href: https://patchmon-dev.example.com
    description: Development Patches
    icon: https://patchmon-dev.example.com/assets/favicon.svg
    widget:
      type: customapi
      url: https://patchmon-dev.example.com/api/v1/gethomepage/stats
      headers:
        Authorization: Basic <dev_credentials>
      mappings:
        - field: total_hosts
          label: Hosts
        - field: total_outdated_packages
          label: Packages
        - field: up_to_date_hosts
          label: Updated

Maximum Information Widget (All 8 Metrics)

This example shows ALL available metrics (may be crowded):

- PatchMon Complete:
    href: https://patchmon.example.com
    description: Complete Statistics
    icon: https://patchmon.example.com/assets/favicon.svg
    widget:
      type: customapi
      url: https://patchmon.example.com/api/v1/gethomepage/stats
      headers:
        Authorization: Basic <credentials>
      mappings:
        - field: total_hosts
          label: Total Hosts
        - field: hosts_needing_updates
          label: Needs Updates
        - field: up_to_date_hosts
          label: Up-to-Date
        - field: security_updates
          label: Security Updates
        - field: hosts_with_security_updates
          label: Security Hosts
        - field: total_outdated_packages
          label: Outdated Packages
        - field: total_repos
          label: Repositories
        - field: recent_updates_24h
          label: Updated (24h)

Note: Displaying all 8 metrics may make the widget tall. Choose 3-5 metrics that are most relevant to your needs.

Integration Architecture

┌─────────────────┐
│   GetHomepage   │
│    Dashboard    │
└────────┬────────┘
         │
         │ HTTP(S) Request
         │ Authorization: Basic <base64>
         │
         ▼
┌─────────────────┐
│    PatchMon     │
│   API Server    │
│                 │
│  /api/v1/       │
│  gethomepage/   │
│    stats        │
└────────┬────────┘
         │
         │ Query Database
         │
         ▼
┌─────────────────┐
│   PostgreSQL    │
│    Database     │
│                 │
│  - Hosts        │
│  - Packages     │
│  - Updates      │
│  - Repositories │
└─────────────────┘

Rate Limiting

The GetHomepage integration endpoints are subject to PatchMon's general API rate limiting:

Default: 100 requests per 15 minutes per IP address
GetHomepage typically polls every 60 seconds
This allows for normal operation without hitting limits

Support and Resources

PatchMon Documentation: https://docs.patchmon.net
GetHomepage Documentation: https://gethomepage.dev
PatchMon Discord: https://patchmon.net/discord
GitHub Issues: https://github.com/9technologygroup/patchmon.net/issues

Changelog

Version 1.0.1 (2025-10-11)

Added OS distribution support
New fields: top_os_1_count, top_os_2_count, top_os_3_count for displaying infrastructure OS breakdown
New fields: top_os_1_name, top_os_2_name, top_os_3_name for identifying operating systems
Total of 14 displayable metrics now available

Version 1.0.0 (2025-10-11)

Initial GetHomepage integration release
Basic authentication support
Real-time statistics endpoint
Customizable widget mappings
IP restriction support
API key management UI
8 core metrics available

Questions or issues? Join our Discord community or open a GitHub issue!

Installing PatchMon Server on Docker

Installing PatchMon Server on Ubuntu 24

Installation of the PatchMon Agent

First time setup admin page

Proxmox LXC Auto-Enrollment Guide

GetHomepage Integration Guide

GetHomepage Integration Guide

Overview

Features

Default Widget Display

Additional Available Data

Prerequisites

Setup Instructions

Step 1: Create an API Key in PatchMon

Step 2: Save Your Credentials

Step 3: Configure GetHomepage

Method A: Copy Complete Configuration (Recommended)

Method B: Manual Configuration

Configuration Options

Widget Mappings

How to Customize Mappings

Available Fields

Quick Start: Adding a Metric

Advanced Mapping Examples

Example: Security-Focused Widget

Example: Repository Management Widget

Example: Activity Monitoring Widget

Example: Package-Focused Widget

Example: OS Distribution Widget

Custom Icon

API Endpoint Details

Endpoint

Authentication

Response Format

All Available Metrics Explained

Health Check Endpoint

Managing API Keys

View Existing Keys

Disable/Enable Keys

Delete Keys

Security Features

Troubleshooting

Error: "Missing or invalid authorization header"

Error: "Invalid API key"

Error: "API key is disabled"

Error: "API key has expired"

Error: "IP address not allowed"

Widget Not Showing Data

Testing the API Endpoint

Pretty Print for Easy Reading

How to Display Your OS Distribution

Security Best Practices

Complete Working Examples

Copy-Paste Ready Configurations

Simple Dashboard Widget (Default)

Detailed Monitoring Widget (Custom)

Multiple Environments (Custom)

Maximum Information Widget (All 8 Metrics)

Integration Architecture

Rate Limiting

Support and Resources

Changelog

Version 1.0.1 (2025-10-11)

Version 1.0.0 (2025-10-11)