search

spotify / lighthouse-audit-service

Apache License 2.0
95 stars 30 forks source link

readme

Lighthouse Audit Service

Actions Status Version

A service meant to help you run, schedule, store, and monitor Lighthouse reports over time. The API is built with Backstage in mind, but can be used without!

Usage

With Docker

The simplest way to deploy the app is with our image on Docker Hub.

docker run spotify/lighthouse-audit-service:latest

Be sure to see "Configuring Postgres" - you will likely need to configure the Postgres credentials, even when trying the app out locally. A list of supported environment variables:

With Docker Compose

A simple way to trial this tool is with the following docker compose file which spins up a postgres container and connects it with the lighthouse image. This would not be a great way to run this in a production environment, but a fast way to test out this tool and see if it meets your needs.

# docker-compose.yml
version: '3.1'

services:

  db:
    image: postgres:latest
    restart: always
    environment:
      POSTGRES_USER: dbuser
      POSTGRES_PASSWORD: example

  lighthouse:
    image: spotify/lighthouse-audit-service:latest
    environment:
      PGHOST: db
      PGUSER: dbuser
      PGPASSWORD: example
      LAS_PORT: 4008
    ports:
      - "4008:4008"

As an npm package

Install the project:

yarn add @spotify/lighthouse-audit-service

Then, you may either start up the server as a standalone process:

import { startServer } from '@spotify/lighthouse-audit-service';

startServer({
  port: 8080,
  cors: true,
  postgresConfig: {
    db: 'postgres',
    database: 'mydb',
    password: 'secretpassword',
    port: 3211,
  },
});

As an express app

You may nest the express app that the lighthouse-audit-service exposes inside of another express app as a subapp by using getApp and app.use():

import express from 'express';
import { getApp as getLighthouseAuditServerApp } from '@spotify/lighthouse-audit-service';

async function startup() {
  const app = express();
  const lighthouseServer = await getLighthouseAuditServerApp();

  app.use('/lighthouse', lighthouseServer);

  const server = app.listen(4000, () => {
    console.log(
      'listening on 4000 - http://localhost:4000/lighthouse/v1/websites',
    );
  });

  // be sure to `.get()` the connection and end it as you close your custom server.
  server.on('close', () => {
    lighthouseServer.get('connection').end();
  });
}

startup();

Configuring Postgres

You will need a Postgres database for lighthouse-audit-service to use to manage the stored audits. The database will be configured on app startup, so you need only initialize an empty database and provide credentials to lighthouse-audit-service.

You can set the Postgres credentials up either by setting environment variables, which will be interpreted by pg:

PGUSER=dbuser \
PGHOST=database.server.com \
PGPASSWORD=secretpassword \
PGDATABASE=mydb \
PGPORT=3211 yarn start

..or, by passing the config in programmatically as postgresConfig:

import { startServer } from '@spotify/lighthouse-audit-service';

startServer({
  port: 8080,
  cors: true,
  postgresConfig: {
    database: 'mydb',
    host: 'my.db.host',
    user: 'dbuser',
    password: 'secretpassword',
    port: 3211,
  },
});

Both startServer and getApp support this. Further, both of these methods support optionally passing a pg client as an optional second argument.

import { Pool } from 'pg';
const conn = new Pool();
startServer({}, conn);

API

We offer a REST API, as well as some programmatic ways, to interact with lighthouse-audits-service.

REST

We are currently seeking contributions on documenting the API in a sustainable way (aka with Swagger/OpenAPI, preferably generated). For now, the REST API includes:

Audit routes

Website routes

Programatic

All of the API methods exposed on REST are also exposed programmatically.

Server

Audit methods

Website methods

Contributing

This project adheres to the Open Code of Conduct. By participating, you are expected to honor this code.

Publish should occur on merge using web-scripts and semantic-release. Please use conventional commits to signal what the new version should be.

External contributions and issues are welcome!

License

Copyright 2020 Spotify AB.

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0