## File: README.md # Lighthouse CI ## Overview Lighthouse CI is a suite of tools that make continuously running, saving, retrieving, and asserting against [Lighthouse](https://github.com/GoogleChrome/lighthouse) results as easy as possible. ### Quick Start To get started with GitHub actions for common project configurations, add the following file to your GitHub repository. Follow [the Getting Started guide](./docs/getting-started.md) for a more complete walkthrough and instructions on other providers and setups. **.github/workflows/ci.yml** ```yaml 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/cli@0.15.x - run: npm run build - run: lhci autorun ``` ### Features - 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 If you're already familiar with continuous integration and have an existing process, start with [Getting Started](./docs/getting-started.md). If you're _not_ familiar with continuous integration, start with [Introduction to CI](./docs/introduction-to-ci.md). - [Introduction to CI](./docs/introduction-to-ci.md) - [Getting Started](./docs/getting-started.md) - [Architecture](./docs/architecture.md) - [Troubleshooting / FAQs](./docs/troubleshooting.md) - [Configuration](./docs/configuration.md) - [Server](./docs/server.md) - [Versioning Policy](./docs/version-policy.md) ## Related Community Projects 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](https://github.com/treosh/lighthouse-ci-action) - Automatically run Lighthouse CI on every PR with GitHub Actions, no infrastructure required. - [Lighthouse CI Starter Example](https://github.com/hchiam/learning-lighthouse-ci) - 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](https://github.com/adevinta/actions-lighthouseci-compare) - 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 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](./docs/getting-started.md) before continuing. - [Integrate Lighthouse CI for static website generator](https://blog.akansh.com/integrate-lighthouse-ci-with-static-site-generators/) - An article on integrating Lighthouse CI with static website generators like Gatsby, Jekyll, etc. - [Automating Google Lighthouse audits and uploading results to Azure](https://keepinguptodate.com/pages/2021/07/automating-google-lighthouse-upload-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 We welcome contributions to lighthouse-ci! Read our [contributing guide](./CONTRIBUTING.md) to get started. --- ## File: docs/recipes/lhci-server-vpn-proxy/README.md # nginx-based LHCI Proxy Server **NOTE: be sure to read the [Security section](../../server.md#Security) of the server documentation to protect your server properly** ## Overview This assumes some knowledge of Docker/K8 (see [docker recipe](../docker-server)), VPN remote access, and [nginx config](https://www.nginx.com/resources/wiki/start/topics/examples/full/). 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](https://en.wikipedia.org/wiki/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 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 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](https://circleci.com/blog/vpns-and-why-they-don-t-work/) and [TravisCI](https://docs.travis-ci.com/user/common-build-problems/#ftpsmtpother-protocol-do-not-work) 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 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](https://github.com/GoogleChrome/lighthouse-ci/blob/v0.4.1/packages/server/src/server.js#L51) for your CI tool to communicate with your LHCI server. ⚠️ It is recommended you at least password-protect using [LHCI basic auth](../../server.md#basic-authentication), 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 # Heroku-based LHCI Server **NOTE: be sure to read the [Security section](../../server.md#Security) of the server documentation to protect your server properly** ## Overview 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](https://www.heroku.com/pricing) that provides exactly this! ## Setting Up Your Repo ```bash # 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 This assumes you've already signed up, created a heroku account, and installed the [heroku CLI](https://devcenter.heroku.com/articles/heroku-cli). ```bash # 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](../../getting-started.md#The-Lighthouse-CI-Server) steps using `https://.herokuapp.com` as your LHCI server base URL. ## Updating LHCI 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. ```bash # 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 ```