epicsoft/unlighthouse repository overview

⁠Unlighthouse

This Docker image is managed and kept up to date by epicsoft LLC⁠.

Unlighthouse⁠ and Wrangler⁠ with Chromium on Alpine, based on the official node LTS image: scan an entire site with Google Lighthouse and publish the reports, for example to Cloudflare Pages.

• Base image: https://hub.docker.com/_/node⁠ (node:lts-alpine), platforms linux/amd64 and linux/arm64
• Dockerfile: https://gitlab.com/epicsoft-networks/unlighthouse/-/blob/main/Dockerfile⁠
• Repository: https://gitlab.com/epicsoft-networks/unlighthouse⁠, mirrored to GitHub⁠ — issues are welcome on both; code changes only as merge requests on GitLab, the mirror overwrites anything pushed to GitHub
• Container registry: https://gitlab.com/epicsoft-networks/unlighthouse/container_registry⁠
• Docker Hub: https://hub.docker.com/r/epicsoft/unlighthouse⁠
• Changelog: https://gitlab.com/epicsoft-networks/unlighthouse/-/blob/main/CHANGELOG.md⁠
• Applications: Unlighthouse⁠, Wrangler⁠
• License: MIT

⁠Description

Unlighthouse is a tool to scan your entire site with Google Lighthouse. Open source, fully configurable with minimal setup.

The reports are written to /unlighthouse/reports by default. Map /unlighthouse to a volume or a local path, for example -v /media/unlighthouse:/unlighthouse.

⁠Versions

Released through a git tag X.Y.Z, which publishes X.Y.Z, X.Y and X and moves latest. Changes and the contained versions are listed in the changelog⁠.

1.0.1 contains Unlighthouse 0.19.1, Wrangler 4.151.1, Node.js 24.22.0, Chromium 155.0.8059.39 and Alpine 3.24.2.

⁠Examples

⁠Show help

docker run --name unlighthouse --rm -it epicsoft/unlighthouse:latest

⁠Use built-in server to display the report

⁠Report for mobile device (default)

docker run --name unlighthouse --rm -it \
  -p 5678:5678 \
  epicsoft/unlighthouse:latest \
    unlighthouse --site="https://example.com"

The Docker container remains active with a running built-in server and can be reached under http://localhost:5678/⁠. The Docker container must be stopped e.g. with ctrl+c or docker stop unlighthouse.

⁠Report for desktop device

docker run --name unlighthouse --rm -it \
  -p 5678:5678 \
  epicsoft/unlighthouse:latest \
    unlighthouse --site="https://example.com" --desktop

⁠Create reports

Static reports can be created automatically, for example in a CI/CD, and uploaded to a central server.

See detailed description on the Unlighthouse website: https://unlighthouse.dev/guide/guides/generating-static-reports⁠

Please note that unlighthouse-ci is used here for execution

⁠Create interactive HTML reports locally

docker run --name unlighthouse --rm -it \
  -v /media/unlighthouse:/unlighthouse \
  epicsoft/unlighthouse:latest \
    unlighthouse-ci --site="https://example.com" --build-static

⁠Create interactive HTML reports on Cloudflare

Required steps for Cloudflare see: https://developers.cloudflare.com/workers/wrangler/ci-cd/⁠

Create a new project at Cloudflare - execute only once.

docker run --name unlighthouse --rm -it \
  -e CLOUDFLARE_ACCOUNT_ID=<YOUR CF ACCOUNT ID> \
  -e CLOUDFLARE_API_TOKEN=<YOUR CF API TOKEN> \
  -e WRANGLER_SEND_METRICS=false \
  epicsoft/unlighthouse:latest \
    wrangler pages project create '<YOUR PROJECT NAME>' --production-branch=main

Automatically create a current version, e.g. with a CI/CD.

docker run --name unlighthouse --rm -it \
  -e CLOUDFLARE_ACCOUNT_ID=<YOUR CF ACCOUNT ID> \
  -e CLOUDFLARE_API_TOKEN=<YOUR CF API TOKEN> \
  -e WRANGLER_SEND_METRICS=false \
  epicsoft/unlighthouse:latest \
    sh -c "unlighthouse-ci --site='https://example.com' --build-static \
      && wrangler pages deploy /unlighthouse/reports \
        --project-name=<YOUR PROJECT NAME> --branch=main"

The report is automatically uploaded to Cloudflare and is immediately available, usually under <YOUR PROJECT NAME>.pages.dev.

⁠Create more reports

Other reports such as CSV, JSON and LHCI can be generated.
Take a look at the Unlighthouse documentation: https://unlighthouse.dev/guide/guides/generating-static-reports⁠
The commands can be easily adapted to the Docker container.

⁠Docker Compose example

services:

  unlighthouse:
    image: epicsoft/unlighthouse:latest
    container_name: unlighthouse
    command: "unlighthouse --site='https://example.com' --desktop"
    ports:
      - 5678:5678

The Docker container can be accessed under http://localhost:5678⁠.

⁠Reporting problems

Issues are welcome on GitLab⁠ and GitHub⁠. Please report a security problem as a confidential issue on GitLab instead of a public one.

⁠License

MIT⁠ — Copyright (c) 2024-2026 epicsoft LLC

The MIT license applies only to files created by epicsoft LLC. Third-party software in the image — Unlighthouse (MIT), Wrangler (MIT OR Apache-2.0), Chromium, the official node image and Alpine Linux — remains under its own licenses.