Skip to content

Installation

You have a few options for deploying homepage, depending on your needs. We offer docker images for a majority of platforms. You can also install and run homepage from source if Docker is not your thing. It can even be installed on Kubernetes with Helm.

Info

Please note that when using features such as widgets, Homepage can access personal information (for example from your home automation system). As of v2.0 Homepage includes a simple authentication gate with a password or OIDC, described in Security & Authentication below. We still recommend homepage be deployed behind a reverse proxy including authentication, SSL etc, and / or behind a VPN.


Docker   Install on Docker

Kubernetes   Install on Kubernetes

Unraid   Install on UNRAID

Next.js   Building from source

HOMEPAGE_ALLOWED_HOSTS

As of v1.0 there is one required environment variable to access homepage via a URL other than localhost, HOMEPAGE_ALLOWED_HOSTS. The setting helps prevent certain kinds of attacks when retrieving data from the homepage API proxy.

The value is a comma-separated (no spaces) list of allowed hosts (sometimes with the port) that can host your homepage install. See the docker, kubernetes and source installation pages for more information about where / how to set the variable.

localhost:3000 and 127.0.0.1:3000 are always included, but you can add a domain or IP address to this list to allow that host such as HOMEPAGE_ALLOWED_HOSTS=gethomepage.dev,192.168.1.2:1234, etc.

If you are seeing errors about host validation, check the homepage logs and ensure that the host exactly as output in the logs is in the HOMEPAGE_ALLOWED_HOSTS list.

This can be disabled by setting HOMEPAGE_ALLOWED_HOSTS to * but this is not recommended. Public deployments must rely on a reverse proxy (and/or VPN) that enforces authentication, TLS, and unexpected Host headers; the built-in host check is a best-effort guard for local setups and is not a substitute for edge protections.

Note

The NextAuth routes (/api/auth/*) and sign-in pages (/auth/*) are exempt from this check so that authentication continues to work, they do not access the API proxy.

Security & Authentication

Public deployments of Homepage should be secured via a reverse proxy, VPN, or similar. As of version 2.0, Homepage supports a simple authorization gate with a password or OIDC. When enabled, Homepage will use password login by default unless OIDC variables are provided.

Required environment variables for authentication:

  • HOMEPAGE_AUTH_ENABLED=true
  • HOMEPAGE_AUTH_SECRET (random string for signing/encrypting cookies, at least 32 characters; generate one with openssl rand -base64 32)
  • HOMEPAGE_EXTERNAL_URL (the absolute URL used to access Homepage, including scheme and port when needed)

Use an https:// URL for public or TLS-terminated deployments so authentication cookies are marked Secure. Trusted HTTP-only LAN deployments may use an http:// URL.

For password-only login:

  • HOMEPAGE_AUTH_PASSWORD (a strong, unique password; required unless OIDC settings are provided)

Warning

Homepage does not apply application-level rate limiting to password attempts. Deployments exposed outside a trusted network should configure their reverse proxy or ingress to rate limit POST requests to /api/auth/callback/credentials. Each failed attempt is logged at warn level as <nextauth> Failed password sign-in attempt, which can be used as a fail2ban or CrowdSec filter.

For OIDC login (overrides password login):

  • HOMEPAGE_OIDC_ISSUER (OIDC issuer URL, e.g., https://auth.example.com/realms/homepage)
  • HOMEPAGE_OIDC_CLIENT_ID
  • HOMEPAGE_OIDC_CLIENT_SECRET
  • Optional: HOMEPAGE_OIDC_NAME (display name), HOMEPAGE_OIDC_SCOPE (defaults to openid email profile)

Warning

Homepage grants access to any identity that the configured OIDC provider authorizes for this client. Configure client assignments, groups, or access policies at the identity provider. Homepage does not apply additional claim-based authorization.

All app pages and /api routes except /api/healthcheck and /api/config/custom.css will require a signed-in session. Static assets remain public.

Configure your OIDC provider with the a callback URI like https://homepage.example.com/api/auth/callback/homepage-oidc.