Security & Authentication
Homepage includes optional password protection. It is fully GUI-driven — no environment variables are required.
First-run setup
When you open Homepage for the first time, a setup screen asks whether you want to enable password protection:
- Yes, add a password — enter and confirm a password. All future visits will require login.
- No, continue without — Homepage runs without any authentication. This can be enabled later.
Logging in
If password protection is enabled, you will see a login screen on every new session. Check Stay logged in to persist the session in localStorage (survives browser restarts). Leave it unchecked to use sessionStorage instead (cleared when the tab or browser is closed).
Sessions expire after 90 days regardless of the "stay logged in" setting.
Managing authentication
Go to Settings → Security to:
| Action | Description |
|---|---|
| Enable password protection | Set up a password on an existing no-auth install |
| Change password | Requires your current password |
| Disable password protection | Requires password confirmation; removes all auth requirements |
| Log out | Clears the current session token |
How it works
- The password is stored as a bcrypt hash in the SQLite database — never in plain text.
- A JWT secret is auto-generated on first use and stored in the database. You do not need to configure it.
- All API routes require a valid Bearer token when auth is enabled. The middleware is a complete no-op when auth is disabled, so there is no performance impact for unauthenticated installs.
- Sessions are JWTs with a 90-day expiry signed with the server's secret.
Exposing Homepage publicly
If you expose Homepage via a reverse proxy or tunnel (e.g. Cloudflare Tunnel, Nginx, Caddy), enabling password protection is strongly recommended. Without it, anyone who can reach the URL can view your widget data, trigger speedtests, and access your backup downloads.
No-auth installs on public URLs
If you chose no password at first-run setup and your instance is publicly reachable, any visitor could go to Settings → Security and enable a password themselves, locking you out. The no-auth mode is intended for use behind a firewall or VPN where you trust all visitors.
If your instance is on a public URL, always set a password.