Homepage¶

Modern dashboard for accessing all your self-hosted services.

Overview¶

Homepage is a modern, fully static, fast, secure fully configurable application dashboard with integrations for over 100 services. It provides a beautiful and customizable interface to access all your Changemaker Lite services from a single location.

Features¶

Service Dashboard: Central hub for all your applications
Docker Integration: Automatic service discovery and monitoring
Customizable Layout: Flexible grid-based layout system
Service Widgets: Live status and metrics for services
Quick Search: Fast navigation with built-in search
Bookmarks: Organize frequently used links
Dark/Light Themes: Multiple color schemes available
Responsive Design: Works on desktop and mobile devices

Access¶

Default Port: 3010
URL: http://localhost:3010
Configuration: YAML-based configuration files

Configuration¶

Environment Variables¶

HOMEPAGE_PORT: External port mapping (default: 3010)
PUID: User ID for file permissions (default: 1000)
PGID: Group ID for file permissions (default: 1000)
TZ: Timezone setting (default: Etc/UTC)
HOMEPAGE_ALLOWED_HOSTS: Allowed hosts for the dashboard

Configuration Files¶

Homepage uses YAML configuration files located in ./configs/homepage/:

settings.yaml: Global settings and theme configuration
services.yaml: Service definitions and widgets
bookmarks.yaml: Bookmark categories and links
widgets.yaml: Dashboard widgets configuration
docker.yaml: Docker integration settings

Volumes¶

./configs/homepage:/app/config: Configuration files
./assets/icons:/app/public/icons: Custom service icons
./assets/images:/app/public/images: Background images and assets
/var/run/docker.sock:/var/run/docker.sock: Docker socket for container monitoring

Changemaker Lite Services¶

Homepage is pre-configured with all Changemaker Lite services:

Essential Tools¶

Code Server (Port 8888): VS Code in the browser
Listmonk (Port 9000): Newsletter & mailing list manager
NocoDB (Port 8090): No-code database platform

Content & Documentation¶

MkDocs (Port 4000): Live documentation server
Static Site (Port 4001): Built documentation hosting

Automation & Data¶

n8n (Port 5678): Workflow automation platform
PostgreSQL (Port 5432): Database backends

Customization¶

Adding Custom Services¶

Edit configs/homepage/services.yaml to add new services:

- Custom Category:
    - My Service:
        href: http://localhost:8080
        description: Custom service description
        icon: mdi-application
        widget:
          type: ping
          url: http://localhost:8080

Custom Icons¶

Add custom icons to ./assets/icons/ directory and reference them in services.yaml:

icon: /icons/my-custom-icon.png

Themes and Styling¶

Modify configs/homepage/settings.yaml to customize appearance:

theme: dark  # or light
color: purple  # slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose

Widgets¶

Enable live monitoring widgets in configs/homepage/services.yaml:

- Service Name:
    widget:
      type: docker
      container: container-name
      server: my-docker

Service Monitoring¶

Homepage can display real-time status information for your services:

Docker Integration: Container status and resource usage
HTTP Ping: Service availability monitoring
Custom APIs: Integration with service-specific APIs

Docker Integration¶

Homepage monitors Docker containers automatically when configured:

Ensure Docker socket is mounted (/var/run/docker.sock)
Configure container mappings in docker.yaml
Add widget configurations to services.yaml

Security Considerations¶

Homepage runs with limited privileges
Configuration files should have appropriate permissions
Consider network isolation for production deployments
Use HTTPS for external access
Regularly update the Homepage image

Troubleshooting¶

Common Issues¶

Configuration not loading: Check YAML syntax in configuration files

docker logs homepage-changemaker

Icons not displaying: Verify icon paths and file permissions

ls -la ./assets/icons/

Services not reachable: Verify network connectivity between containers

docker exec homepage-changemaker ping service-name

Widget data not updating: Check Docker socket permissions and container access

docker exec homepage-changemaker ls -la /var/run/docker.sock

Configuration Examples¶

- Code Server:
    href: http://localhost:8888
    description: VS Code in the browser
    icon: code-server
    widget:
      type: docker
      container: code-server-changemaker

Custom Dashboard Layout¶

# settings.yaml
layout:
  style: columns
  columns: 3

# Responsive breakpoints
responsive:
  mobile: 1
  tablet: 2
  desktop: 3

Official Documentation¶

For comprehensive configuration guides and advanced features: - Homepage Documentation - GitHub Repository - Configuration Examples - Widget Integrations