---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: User_Manual
status: active
tags:
- domain/homelab
- domain/security
- tech/docker
- tech/nextjs
- type/dashboard
- type/sop
type: sop
---

# Homepage Dashboard User Manual

## What This Tool Does

Homepage is a modern, fully static, fast, and secure application dashboard. It provides a centralized landing page for your self-hosted services, featuring:

- **Dashboard Widgets**: Display information about your services, weather, system stats, and more.
- **Quick Launch**: A global search bar to quickly navigate to services or search the web.
- **Bookmarks**: Organize links to your favorite websites.
- **Integrations**: Supports over 100 services with automatic discovery and status monitoring.
- **Customization**: Highly customizable via YAML configuration files.
- **Security**: Proxies API requests to backend services, keeping API keys hidden from the client.

## Who Uses It

Homepage is designed for:

- **Home Lab Enthusiasts**: Who host multiple services (e.g., Nextcloud, Pi-hole, Plex) and want a single entry point.
- **Developers**: Who need quick access to monitoring tools, git repositories, and deployment dashboards.
- **System Administrators**: Who want to monitor service health and status at a glance.

## How to Access

Homepage is typically accessed via a web browser. In this specific deployment configuration:

1. **URL**: Navigate to `http://localhost:3001` (or your server's IP/domain).
2. **Authentication**: If configured in your reverse proxy or via the dashboard settings, you may need to log in. This specific setup does not enable dashboard-level auth by default in the provided config, relying on external reverse proxy security or `HOMEPAGE_ALLOWED_HOSTS`.
3. **Hosts**: Ensure you are accessing it via the allowed host `optical-dev.oliver.solutions` if accessing remotely.

## Main Workflows

### 1. Configuring Services

Homepage can discover services via Docker labels or via a `services.yml` file in the `config` directory.

**Via Docker Labels (Automatic Discovery):**
Add these labels to your service's `docker-compose.yml`:
```yaml
labels:
  homepage.dev/name: "Service Name"
  homepage.dev/description: "What the service does"
  homepage.dev/group: "Infrastructure"
  homepage.dev/widget: "serviceType"
  homepage.dev/url: "http://service:port"
```

**Via YAML (Manual Configuration):**
Edit `config/services.yml`:
```yaml
services:
  Infrastructure:
    - Nextcloud:
        icon: mdi:cloud
        href: http://nextcloud
        description: "File storage"
```

### 2. Customizing the Dashboard

Edit `config/settings.yml`:
```yaml
theme: dark
title: "My Dashboard"
quicklaunch:
  provider: google
  showSearchSuggestions: true
```

### 3. Using Quick Launch

1. Click the search icon in the top-left, top-right, bottom-left, or bottom-right corner (depending on settings).
2. Type a query. It will search using the configured provider (e.g., Google, DuckDuckGo) or local services if available.
3. Use arrow keys to navigate suggestions and Enter to open.

## FAQ

**Q: Where is the configuration stored?**
A: Configuration files are stored in the `./config` directory mapped into the container. Common files include `services.yml`, `settings.yml`, `widgets.yml`, etc.

**Q: How do I update the dashboard?**
A: Homepage updates itself when the underlying Docker image is updated. Check the "Update Available" link in the footer if running an older version.

**Q: Can I use it without Docker?**
A: Yes, it is a Next.js application. However, the provided setup relies on Docker for the proxy and environment configuration.

**Q: How is security handled?**
A: API requests are proxied through the backend, preventing direct exposure of credentials. Always use HTTPS in production via a reverse proxy.

## Related
- [[01 Projects/homepage/DEVELOPER_MANUAL.md]]