File: README.md Copy Chapter

Lighthouse CI

Overview Copy Chapter

Lighthouse CI is a suite of tools that make continuously running, saving, retrieving, and asserting against Lighthouse results as easy as possible.

Quick Start Copy Section

To get started with GitHub actions for common project configurations, add the following file to your GitHub repository. Follow the Getting Started guide for a more complete walkthrough and instructions on other providers and setups.

.github/workflows/ci.yml

name: CI
on: [push]
jobs:
  lighthouseci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 18
      - run: npm install && npm install @lhci/[email protected]
      - run: npm run build
      - run: lhci autorun

Features Copy Section

• Get a Lighthouse report alongside every PR.
• Prevent regressions in accessibility, SEO, offline support, and performance best practices.
• Track performance metrics and Lighthouse scores over time.
• Set and keep performance budgets on scripts and images.
• Run Lighthouse many times to reduce variance.
• Compare two versions of your site to find improvements and regressions of individual resources.

Documentation Copy Section

If you're already familiar with continuous integration and have an existing process, start with Getting Started.

If you're not familiar with continuous integration, start with Introduction to CI.

• Introduction to CI
• Getting Started
• Architecture
• Troubleshooting / FAQs
• Configuration
• Server
• Versioning Policy

Related Community Projects Copy Chapter

A collection of projects using Lighthouse CI written by the community. If you're using Lighthouse CI in your open source project, open a PR to add it here!

• Lighthouse CI GitHub Action - Automatically run Lighthouse CI on every PR with GitHub Actions, no infrastructure required.

• Lighthouse CI Starter Example - A minimal example repo that you can use as a template when starting from scratch, offers a beginner-friendly quickstart guide using create-react-app.

• Lighthouse CI Compare Action - A Lighthouse CI Github Action that compares the current commit run against the ancestor commit and creates an object with the differences and a Markdown table that you can use for different purposes.

Community Guides Copy Chapter

A collection of unofficial blog posts, tutorials, and guides written by the community on using Lighthouse CI. If you've written up a guide to using Lighthouse CI in your project, open a PR to add it here!

NOTE: This is not official documentation. You're encouraged to familiarize yourself with Lighthouse CI and read through Getting Started before continuing.

• Integrate Lighthouse CI for static website generator - An article on integrating Lighthouse CI with static website generators like Gatsby, Jekyll, etc.
• Automating Google Lighthouse audits and uploading results to Azure - This article covers configuring Lighthouse CI to run against a website and uploading the results to a Lighthouse CI server Docker container running both locally and in Azure.

Contributing Copy Chapter

We welcome contributions to lighthouse-ci! Read our contributing guide to get started.

File: docs/recipes/lhci-server-vpn-proxy/README.md Copy Chapter

nginx-based LHCI Proxy Server

NOTE: be sure to read the Security section of the server documentation to protect your server properly

Overview Copy Chapter

This assumes some knowledge of Docker/K8 (see docker recipe), VPN remote access, and nginx config. It's not uncommon that a company develops internal tools behind VPN, but if you want to intentionally expose an internal service, like LHCI, you typically use a proxy pattern.

This is a contrived recipe on how to configure a nginx reverse proxy to expose parts of your LHCI server that exists behind a VPN.

Architecture Copy Chapter

Say you build a custom LHCI server behind your company's VPN:

|-----VPN-----|
| LHCI server | X-- www <-- client ¯\_(⊙︿⊙)_/¯
|             |
|-------------|

You hand out VPN profiles to employees to access this private LHCI server at https://lhc-over-vpn.example.com and you see the LHCI server GUI in all its glory:

|-----VPN-----|
| LHCI server | <-- VPN tunnel <-- www <-- remote access client ヽ(´ー｀)ノ
|             |
|-------------|

Problem Copy Section

That works when viewing the GUI with a browser at https://lhc-over-vpn.example.com, but what happens when you need to provide access for public-facing CI tools to upload reports to your private LHCI server? For example, CI tools like CircleCI and TravisCI have limitations in dealing with VPN tunneling or else you are stuck with extremely complicated docker setup using ssh and openvpn. It's definitely not supported out of the box and doesn't work at all with VPN + MFA.

A Proxy Solution Copy Section

So you use a CI tool like CircleCI and want to allow uploading reports to your private LHCI server. One solution might be to use a nginx reverse proxy server to expose only certain routes for your CI tool to communicate with your LHCI server.

⚠️ It is recommended you at least password-protect using LHCI basic auth, since you will be exposing these routes to the public.

So at the gateway of your company's VPN, you might have a nginx server where you can reverse proxy to your private LHCI server:

|-----VPN-----|
| LHCI server | <-- VPN tunnel <-- lhc-over-vpn.example.com/app/projects <-- remote access client
|             |
|             | <-- upload <-- (lhc-over-vpn.example.com/v1/projects) <-- www.public-proxy.example.com/lighthouse/v1/projects <-- CircleCI
|-------------|

With this setup, the GUI at lhc-over-vpn.example.com/app/projects is left intact behind the VPN, but external CI tools now have public access to the exposed, but still password-protected, reverse proxy server (www.public-proxy.example.com/lighthouse/v1)!

File: docs/recipes/heroku-server/README.md Copy Chapter

Heroku-based LHCI Server

NOTE: be sure to read the Security section of the server documentation to protect your server properly

Overview Copy Chapter

The LHCI server can be run in any node environment with persistent disk storage or network access to a postgres database. Heroku offers a free tier of hosting that provides exactly this!

Setting Up Your Repo Copy Chapter

# Create a directory and repo for your heroku project
mkdir lhci-heroku && cd lhci-heroku && git init
# Setup the LHCI files
curl https://raw.githubusercontent.com/GoogleChrome/lighthouse-ci/main/docs/recipes/heroku-server/package.json > package.json
curl https://raw.githubusercontent.com/GoogleChrome/lighthouse-ci/main/docs/recipes/heroku-server/server.js > server.js
# Create the project's first commit
git add package.json server.js && git commit -m 'Initial commit'

Setting Up Heroku Copy Chapter

This assumes you've already signed up, created a heroku account, and installed the heroku CLI.

# Create a new project on heroku
heroku create
# Add a database to your project
heroku addons:create heroku-postgresql:essential-0
# Deploy your code to heroku
git push heroku main
# Ensure heroku is running your app and open the URL
heroku ps:scale web=1
heroku open

Once you've got the server up and running you can continue with the Getting Started steps using https://.herokuapp.com as your LHCI server base URL.

Updating LHCI Copy Chapter

Updates are made to the LHCI server from time to time and you'll want to keep up! You can update your LHCI server on Heroku just by pushing a commit.

# Update LHCI
npm install --save @lhci/server@latest
# Create a commit with your update
git add package.json && git commit -m 'update LHCI'
# Deploy your update to heroku
git push heroku main