ab.dem.tf.changemaker/mkdocs/docs/cm-lite/services/homepage.md

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

```yaml
- 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:

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

### Themes and Styling

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

```yaml
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`:

```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
```bash
docker logs homepage-changemaker
```

**Icons not displaying**: Verify icon paths and file permissions
```bash
ls -la ./assets/icons/
```

**Services not reachable**: Verify network connectivity between containers
```bash
docker exec homepage-changemaker ping service-name
```

**Widget data not updating**: Check Docker socket permissions and container access
```bash
docker exec homepage-changemaker ls -la /var/run/docker.sock
```

## Configuration Examples

### Basic Service Widget

```yaml
- 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

```yaml
# 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](https://gethomepage.dev/)
- [GitHub Repository](https://github.com/gethomepage/homepage)
- [Configuration Examples](https://gethomepage.dev/configs/)
- [Widget Integrations](https://gethomepage.dev/widgets/)