search

DiUS / pact_broker-docker

'Dockerised' pact broker
http://pact.io
MIT License
76 stars 102 forks source link

readme

Dockerised Pact Broker

Build Status

This repository contains a Dockerized Pact Broker. You can pull the dius/pact-broker image from Dockerhub.

A smaller and sexier Docker image has now been built in the Pact Foundation organization. The new image can be run without root permissions, and is only 98MB compressed! All environment variable configurations are the same, so you should just be able to switch from dius/pact-broker to pactfoundation/pact-broker and run with it - note that the default port has changed from 80 to 9292 though.

Which one should I use?

Please read https://github.com/phusion/passenger/wiki/Puma-vs-Phusion-Passenger for information on which server will suit your needs best. The tl;dr is that if you want to run the docker image in a managed architecture which will make your application highly available (eg. ECS, Kubernetes) then use the pactfoundation/pact-broker. Puma will not restart itself if it crashes, so you will need external monitoring to ensure the Pact Broker stays available.

If you want to run the container as a standalone instance, then the dius/pact-broker image which uses Phusion Passenger may serve you better, as Passenger will restart any crashed processes.

Note: On 12 May 2018, the format of the docker tag changed from M.m.p-RELEASE to M.m.p.RELEASE (where M.m.p is the semantic version of the underlying Pact Broker package) so that Dependabot can recognise when the version has been incremented.

In a hurry?

If you want to try out a Pact Broker that can be accessed by all your teams, without having to fill in requisition forms and wait for 3 months, you can get a free trial at pactflow.io. Built by a group of core Pact maintainers, Pactflow is a fork of the OSS Pact Broker with extra goodies like an improved UI, field level verification results and federated login. It's also fully supported, and that means when something goes wrong, someone else gets woken up in the middle of the afternoon to fix it...

Prerequisites

Getting Started

  1. Install Docker

Create the database

On an instance of Postgres version 10 or later, connect as a user with administrator privileges and run:

CREATE DATABASE pact_broker;
CREATE ROLE pact_broker WITH LOGIN PASSWORD 'CHANGE_ME';
GRANT ALL PRIVILEGES ON DATABASE pact_broker TO pact_broker;

Configure the connection details

You can either set the PACT_BROKER_DATABASE_URL in the format driver://username:password@host:port/database (eg. postgres://user1:pass1@myhost/mydb) or, you can set the credentials individually using the following environment variables:

* `PACT_BROKER_DATABASE_ADAPTER` (optional, defaults to 'postgres', see note below.)
* `PACT_BROKER_DATABASE_USERNAME`
* `PACT_BROKER_DATABASE_PASSWORD`
* `PACT_BROKER_DATABASE_HOST`
* `PACT_BROKER_DATABASE_NAME`
* `PACT_BROKER_DATABASE_PORT` (optional, defaults to the default port for the specified adapter)

Adapter can be 'postgres' (recommended) or 'sqlite'. SQLite will work for spikes, but it is NOT supported as a production database.

For an SQLite database (only recommended for investigation/spikes, as it will be disposed of with the container unless you mount it from an external file system):

You can additionally set:

* `PACT_BROKER_DATABASE_SSLMODE` - optional, possible values: 'disable', 'allow', 'prefer', 'require', 'verify-ca', or 'verify-full' to choose how to treat SSL (only respected if using the postgres database adapter. See https://www.postgresql.org/docs/9.1/libpq-ssl.html for more information.)
* `PACT_BROKER_SQL_LOG_LEVEL` - optional, defaults to debug. The level at which to log SQL statements.
* `PACT_BROKER_SQL_LOG_WARN_DURATION` - optional, defaults to 5 seconds. Log the SQL for queries that take longer than this number of seconds.
* `PACT_BROKER_DATABASE_MAX_CONNECTIONS` - optional, defaults to 4. The maximum size of the connection pool.
* `PACT_BROKER_DATABASE_POOL_TIMEOUT` - optional, 5 seconds by default. The number of seconds to wait if a connection cannot be acquired before raising an error.

Notes

Using basic auth

To enable basic auth, run your container with:

If you want to allow public read access (but still require credentials for writing), then omit setting the READ_ONLY credentials and set PACT_BROKER_ALLOW_PUBLIC_READ=true.

Developers should use the read only credentials on their local machines, and the CI should use the read/write credentials. This will ensure that pacts and verification results are only published from your CI.

Note that the verification status badges are not protected by basic auth, so that you may embed them in README markdown.

Heartbeat URL

If you are using the docker container within an AWS autoscaling group, and you need to make a heartbeat URL publicly available, set PACT_BROKER_PUBLIC_HEARTBEAT=true. No database connection will be made during the execution of this endpoint.

The heartbeat is available at /diagnostic/status/heartbeat.

Healthcheck URL

See Heartbeat URL.

Using SSL

See the Pact Broker configuration documentation.

Setting the log level

Set the environment variable PACT_BROKER_LOG_LEVEL to one of DEBUG, INFO, WARN, ERROR, or FATAL.

Webhook whitelists

Other environment variables

General Pact Broker configuration and usage

Documentation for the Pact Broker application itself can be found in the Pact Broker docs.

Running with Docker Compose

For a quick start with the Pact Broker and Postgres, we have an example Docker Compose setup you can use:

  1. Modify the docker-compose.yml file as required.
  2. Run docker-compose up to get a running Pact Broker and a clean Postgres database

Now you can access your local broker:

curl -v http://localhost # you can visit in your browser too!

# SSL endpoint, note that URLs in response contain https:// protocol
curl -v -k https://localhost:8443

NOTE: this image should be modified before using in Production, in particular, the use of hard-coded credentials

Running with Openshift

See pact-broker-openshift for an example config file.

Troubleshooting

See the Troubleshooting page on the wiki.