Skip to content
Login Changemaker Archive. Learn more

# 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:

1. Ensure Docker socket is mounted (`/var/run/docker.sock`)
2. Configure container mappings in `docker.yaml`
3. 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

### Basic Service Widget

    - 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