---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-18
name: Developer_Manual
status: active
tags:
- domain/devops
- tech/docker
- tech/nextjs
- tech/react
- tech/tailwind
- tech/typescript
type: reference
---

# Homepage Dashboard Developer Manual

## Architecture Overview

Homepage is a **Next.js** application using **React** and **Tailwind CSS**. It follows a hybrid rendering approach:

- **Static Generation**: Most of the site is statically generated at build time for performance.
- **Client-side Hydration**: Interactive components (Quick Launch, Widgets) use client-side hydration.
- **Data Fetching**: Uses **SWR** for efficient data fetching and caching for real-time updates (service status, weather, etc.).
- **Configuration**: Driven by YAML files in `./config` and/or Docker label discovery.

## Tech Stack

- **Framework**: Next.js (App Router or Pages Router depending on version, likely Pages based on `next-i18next`)
- **Language**: TypeScript / JavaScript
- **Styling**: Tailwind CSS
- **Testing**: Vitest, React Testing Library
- **Data Fetching**: SWR
- **Icons**: Material Design Icons (MDI), Simple Icons (SI), Selfhst Icons
- **Testing Utilities**: Custom `render-with-providers` wrapper for Context

## Local Setup

1. **Clone the repository**:
   ```bash
   git clone https://github.com/gethomepage/homepage.git
   cd homepage
   ```

2. **Install Dependencies**:
   ```bash
   npm install
   # or
   yarn install
   ```

3. **Configuration**:
   Create a `config` directory in the root with your `services.yml` and `settings.yml`.

4. **Run Locally**:
   ```bash
   npm run dev
   ```
   This typically runs the app on `http://localhost:3000`.

5. **Docker Development**:
   The provided `docker-compose.yml` builds the app and mounts `./config`.
   ```bash
   docker-compose up --build
   ```

## Environment Variables

Key variables used in the codebase:

- `NEXT_PUBLIC_BASE_PATH`: Set to `/homepage` in docker-compose. Used for routing prefixes.
- `NEXT_PUBLIC_BUILDTIME`: Build timestamp for version display.
- `NEXT_PUBLIC_REVISION`: Git commit hash.
- `NEXT_PUBLIC_VERSION`: App version string.
- `HOSTNAME`: Set to `"::"` in docker-compose. Likely for internal networking.
- `HOMEPAGE_ALLOWED_HOSTS`: `optical-dev.oliver.solutions`. Restricts which hosts can access the dashboard.
- `NEXT_PUBLIC_DOMAIN`: (Implicit) Used for favicon and meta tags.

## Key Services & Entry Points

- `src/pages/index.js`: Main dashboard entry point.
- `src/components/version.jsx`: Displays version info and update checks via GitHub API.
- `src/components/quicklaunch.jsx`: Implements the global search widget.
- `src/components/resolvedicon.jsx`: Handles dynamic icon loading from CDN (MDI, SI, Selfhst) or custom URLs.
- `src/components/favicon.jsx`: Dynamically generates a favicon SVG and converts it to a data URI for the browser head.
- `src/test-utils/render-with-providers.jsx`: Testing helper to wrap components in `SettingsContext`.
- `src/utils/contexts/settings`: Global state management for dashboard settings.

## API Reference

- `GET /api/healthcheck`: Health check endpoint (used in docker-compose healthcheck).
- `GET /api/releases`: Returns the latest release data from GitHub. Cached for 1 hour.
- `GET /api/widgets`: Returns configured widget data.
- **Proxying**: All backend service API calls are proxied through Next.js API routes to hide keys.

## Deployment

This project uses **Docker Compose** for deployment.

**Key Docker Config:**
- **Port Mapping**: `127.0.0.1:3001:3000` (Localhost only).
- **Volume Mounts**: 
  - `./config:/app/config`: Persist configuration.
  - `/var/run/docker.sock:/var/run/docker.sock:ro`: Allows the app to read Docker labels for service discovery.
- **Restart Policy**: `unless-stopped`.
- **Health Check**: Uses `wget` to ping `/api/healthcheck` every 10 seconds.

**Production Considerations:**
- Bind to `0.0.0.1` if remote access is needed.
- Configure `HOMEPAGE_ALLOWED_HOSTS` appropriately.
- Use a reverse proxy (Nginx, Caddy) for HTTPS and additional security headers.

## Known Gotchas

- **Icon Prefixes**: Icons must use prefixes like `mdi-`, `si-`, or `sh-`. Custom URLs must start with `http` or `/`.
- **Static Context**: Since much is static, configuration changes require a container restart or cache invalidation.
- **Docker Socket**: Mounting `/var/run/docker.sock` gives read-only access to Docker labels. Ensure this is intentional for service discovery.
- **Browser Caching**: The version check caches results for 1 hour via `memory-cache`. Immediate updates may not show "Update Available" immediately.
- **Test Environment**: Tests require `jsdom` environment as specified in `src/test-utils/render-with-providers.jsx` comments.