homepage README

The project's README from github.com/gethomepage/homepage. As one markdown file: README.md.

A modern, fully static, fast, secure fully proxied, highly customizable application dashboard with integrations for over 100 services and translations into multiple languages. Easily configured via YAML files or through docker label discovery.

GitHub Workflow Status (with event)       Discord     GitHub Sponsors

Features

With features like quick search, bookmarks, weather support, a wide range of integrations and widgets, an elegant and modern design, and a focus on performance, Homepage is your ideal start to the day and a handy companion throughout it.

Docker Integration

Homepage has built-in support for Docker, and can automatically discover and add services to the homepage based on labels. See the Docker Service Discovery page for more information.

Service Widgets

Homepage also has support for hundreds of 3rd-party services, including all popular *arr apps, and most popular self-hosted apps. Some examples include: Radarr, Sonarr, Lidarr, Bazarr, Ombi, Tautulli, Plex, Jellyfin, Emby, Transmission, qBittorrent, Deluge, Jackett, NZBGet, SABnzbd, etc. As well as service integrations, Homepage also has a number of information providers, sourcing information from a variety of external 3rd-party APIs. See the Service page for more information.

Information Widgets

Homepage has built-in support for a number of information providers, including weather, time, date, search, glances and more. System and status information presented at the top of the page. See the Information Providers page for more information.

Customization

Homepage is highly customizable, with support for custom themes, custom CSS & JS, custom layouts, formatting, localization and more. See the Settings page for more information.

Getting Started

For configuration options, examples and more, please check out the homepage documentation.

Security Notice 🔒

Please note that when using features such as widgets, Homepage can access personal information (for example from your home automation system). To keep your information private, if Homepage is reachable from any untrusted network, it:

  1. must sit behind a reverse proxy (and/or VPN) that enforces authentication, TLS, and strictly validates Host headers.
  2. An optional built-in OIDC login flow or simple password login is available (opt-in) offering a simple “authenticated or not” guard.

With Docker

Using docker compose:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: gethomepage.dev # required, may need port. See gethomepage.dev/installation/#homepage_allowed_hosts
      PUID: 1000 # optional, your user id
      PGID: 1000 # optional, your group id
    ports:
      - 3000:3000
    volumes:
      - /path/to/config:/app/config # Make sure your local config directory exists
      - /var/run/docker.sock:/var/run/docker.sock:ro # optional, for docker integrations
    restart: unless-stopped

or docker run:

docker run --name homepage \
  -e HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev \
  -e PUID=1000 \
  -e PGID=1000 \
  -p 3000:3000 \
  -v /path/to/config:/app/config \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  --restart unless-stopped \
  ghcr.io/gethomepage/homepage:latest

From Source

First, clone the repository:

git clone https://github.com/gethomepage/homepage.git

Then install dependencies and build the production bundle:

pnpm install
pnpm build

If this is your first time starting, copy the src/skeleton directory to config/ to populate initial example config files.

Finally, run the server in production mode:

HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev:1234 pnpm start

Configuration

Please refer to the homepage documentation website for more information. Everything you need to know about configuring Homepage is there. Please read everything carefully before asking for help, as most questions are answered there or are simple YAML configuration issues.

Development

Install NPM packages, this project uses pnpm (and so should you!):

pnpm install

Start the development server:

pnpm dev

Open http://localhost:3000 to start.

This is a Next.js application, see their documentation for more information.

Documentation

The homepage documentation is available at https://gethomepage.dev/.

Homepage uses Zensical for documentation. To run the documentation locally, first install the dependencies:

uv sync

Then run the development server:

uv run zensical serve # or build, to build the static site

Support & Suggestions

If you have any questions, suggestions, or general issues, please start a discussion on the Discussions page.

Troubleshooting

In addition to the docs, the troubleshooting guide can help reveal many basic config or network issues. If you're having a problem, it's a good place to start.

Contributing & Contributors

Contributions are welcome! Please see the CONTRIBUTING.md file for more information.

Thanks to the over 200 contributors who have helped make this project what it is today!

Especially huge thanks to @shamoon, who has been the backbone of this community from the very start.

homepage (gethomepage/homepage)

reverse-proxy
Searching Database…

33.2K ·GitHub
Homepage
What is this?Homepage is a fully static, highly customizable application dashboard (startpage) that aggregates service widgets, Docker container stats, bookmarks, and information widgets like weather and search in one place.
Is this a desktop app or something I host myself?It's a self-hosted web app you run yourself (via Docker or from source as a Next.js app) and access through a browser; it's statically generated for speed.
How do I get it running?Easiest way is Docker Compose or `docker run`. Alternatively clone the repo, install dependencies with pnpm, copy `src/skeleton` to `config/` for example configs, build, and run in production mode.
Do I need anything special before installing it?If running from source you need pnpm and Node.js (it's a Next.js app); for Docker it just needs a Docker host. No other accounts are required.
Is it safe to expose this on my network?If reachable from an untrusted network, it must sit behind a reverse proxy/VPN enforcing authentication and TLS, or you can enable the built-in OIDC or password login as a basic guard.
Who is this really built for?It's aimed at homelab and self-hosting enthusiasts who run multiple services (media servers, download clients, *arr apps) and want one dashboard to see and link them all.
What CPU architectures does it support?Official Docker images are built for AMD64 and ARM64.
Does it handle any sensitive personal data?Yes — widgets can pull personal information, for example from your home automation system, so it warns you to secure access carefully.
How does Homepage talk to my Docker containers?It integrates directly with the Docker API and can automatically discover and add services to the dashboard based on container labels, also showing container status and stats.
Which self-hosted apps does it have built-in widgets for?Over 100 service integrations are supported, including popular *arr apps and self-hosted tools like Radarr, Sonarr, Plex, Jellyfin, Transmission, qBittorrent, and more.
How do I configure the dashboard layout and services?Everything is configured through YAML files (or automatically via Docker label discovery), covering services, bookmarks, widgets, and custom layout/theme settings.
Does it support languages other than English?Yes, Homepage has full i18n support with translations into over 40 languages.
What are similar projects?dashy, glance, neko-master, Termix, seerr, github-release-monitor, dockhand, nginx-proxy-manager
Which topics is it in?oidc, homelab, yaml, reverse-proxy, node, i18n, nextjs, customization, dashboard, monitoring, productivity, gui
Creator
gethomepage
Size
56.1 MB
Stars
33.2K
Updated
CommitOct 17Releasev2.6.0Oct 17
Age
4y
Commits · 90 Days