Healthchecks

Requirements

• Healthchecks.io container self-hosted on Docker
• oauth2-proxy reverse proxy container for authentication
• Reverse proxy with SSL termination at the edge (HTTPS)

Create the client in Pocket ID

1. In Pocket ID, open Administration → OIDC Clients and click Add OIDC Client.
2. Enter a name such as Healthchecks and add the callback URL https://hc.example.com/oauth2/callback.
3. Click Create and copy the Client ID and the Client secret. The client secret is only shown once.
4. On the client’s General tab, turn on PKCE, then click Save.
5. On the client’s Access tab, select the groups that may sign in under Allowed User Groups, or choose All Users.

Configure oauth2-proxy

In the same docker-compose.yml you use for Healthchecks:

1. Add a new oauth2-proxy container under the services: section with the following config:

   oauth2-proxy:
     image: quay.io/oauth2-proxy/oauth2-proxy
     restart: unless-stopped
     command: --config /oauth2-proxy.cfg
     volumes:
       - ./oauth2-proxy.cfg:/oauth2-proxy.cfg
     ports:
       - 1234:4180

2. Add the following to the Healthchecks environment: section:

   - REMOTE_USER_HEADER=HTTP_X_FORWARDED_EMAIL

3. Comment out the ports: section on Healthchecks, so that oauth2-proxy picks up the authentication request instead of Healthchecks directly.

4. Create a file beside docker-compose.yml called oauth2-proxy.cfg with the following config. Replace <client-id> and <client-secret> with the Client ID and Client secret from Pocket ID:

   provider_display_name="Pocket ID"
   provider="oidc"
   oidc_issuer_url="https://id.example.com"
   client_id="<client-id>"
   client_secret="<client-secret>"
   cookie_secret="xxx" # generate with: openssl rand -base64 32 | tr -- '+/' '-_'
   upstreams="http://healthchecks:8000" # internal port
   code_challenge_method="S256" # PKCE challenges plain or S256
   skip_auth_routes = [".*/ping", ".*/api", ".*/badge"]
   reverse_proxy = true
   redirect_url="https://hc.example.com/oauth2/callback"
   scope = "openid email profile groups"
   
   cookie_expire="0" # seconds, 0 for session
   cookie_name="__Host-oauth2-proxy" # or __Secure-oauth2-proxy (less secure)
   cookie_secure="true"
   email_domains = ["*"]
   http_address="0.0.0.0:4180"
   insecure_oidc_allow_unverified_email = "true"

5. Update your public-facing edge reverse proxy config (Caddy, Nginx, etc.) to forward https://hc.example.com to port 1234 (the external port for oauth2-proxy).

6. Restart the entire stack:

   docker compose down
   docker compose pull
   docker compose up -d

You can now sign in to Healthchecks with Pocket ID.

Example full stack

---
services:
  healthchecks:
    image: healthchecks/healthchecks:latest
    environment:
      - ALLOWED_HOSTS=hc.example.com
      - DB=sqlite
      - DB_NAME=/data/hc.sqlite
      - SECRET_KEY=${SECRET_KEY}
      - SITE_ROOT=https://hc.example.com
      - PING_EMAIL_DOMAIN=hc.example.com
      - REGISTRATION_OPEN=False
      - SITE_NAME=Healthchecks
      - RP_ID=hc.example.com
      - REMOTE_USER_HEADER=HTTP_X_FORWARDED_EMAIL
    volumes:
      - ./data:/data
    restart: unless-stopped
    # ports:
    #   - 8000:8000
  oauth2-proxy:
    image: quay.io/oauth2-proxy/oauth2-proxy
    restart: unless-stopped
    command: --config /oauth2-proxy.cfg
    volumes:
      - ./oauth2-proxy.cfg:/oauth2-proxy.cfg
    ports:
      - 1234:4180