/pact-broker-docker

Dockerized Pact Broker http://pact.io

Primary LanguageRubyMIT LicenseMIT

Dockerised Pact Broker Build Status

This repository contains a Dockerized version of the Pact Broker. You can pull the pactfoundation/pact-broker image from Dockerhub. If you're viewing these docs on Dockerhub, here is a link to the github repository.

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...

Notes migration from dius/pact-broker image

The pactfoundation/pact-broker image is a forked version of the dius/pact-broker image. It is smaller (as it runs on Alpine Linux with Puma instead of the larger Passenger Phusion base image), and does not need root permissions.

All the environment variables used for dius/pact-broker are compatible with pactfoundation/pact-broker. The only breaking change is that the default port has changed from 80 to 9292 (because a user without root permisisons cannot bind to a port under 1024). If you wish to expose port 80 (or 443) you can deploy Ngnix in front of it (see the docker-compose file for an example).

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.

Prerequisites

  • A running postgresql database and the ability to connect to it (see POSTGRESQL.md).
  • If on Mac, you will need the timeout or gtimeout function. You can install gtimeout using brew install coreutils.

Getting Started

  1. Install Docker
  2. Prepare your environment if you are not running postgresql in a docker container. Setup the pact broker connection to the database through the use of the following environment variables. If you want to use a disposable postgres docker container just do export DISPOSABLE_PSQL=true before running the script/test.sh.

For a postgres or mysql database:

* 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)
* 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.)

Adapter can be 'postgres' (recommended) or 'mysql2' (please note that future JSON search features may not be supported on mysql).

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):

  • PACT_BROKER_DATABASE_ADAPTER (set to 'sqlite')
  • PACT_BROKER_DATABASE_NAME (arbitrary name eg. pact_broker.sqlite)
  1. Test the pact broker environment by executing script/test.sh

Notes

  • On OSX, if you are not using Docker native, use docker-machine ip $(docker-machine active) to get the IP of the VirtualBox, and connect on port 9292.
  • The application makes use of the Puma application server.
  • Apart from creating a database no further preparation is required.

Using basic auth

To enable basic auth, run your container with:

  • PACT_BROKER_BASIC_AUTH_USERNAME
  • PACT_BROKER_BASIC_AUTH_PASSWORD
  • PACT_BROKER_BASIC_AUTH_READ_ONLY_USERNAME
  • PACT_BROKER_BASIC_AUTH_READ_ONLY_PASSWORD

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.

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

  • PACT_BROKER_WEBHOOK_HOST_WHITELIST - a space delimited list of hosts (eg. github.com travis.org), network ranges (eg. 10.2.3.41/24, or regular expressions (eg. /.*\\.foo\\.com$/). Regular expressions should start and end with a / to differentiate them from Strings. Note that backslashes need to be escaped with a second backslash. Please read the Webhook whitelists section of the Pact Broker configuration documentation to understand how the whitelist is used. Remember to use quotes around this value as it may have spaces in it.
  • PACT_BROKER_WEBHOOK_SCHEME_WHITELIST - a space delimited list (eg. http https). Defaults to https.

Other environment variables

  • PACT_BROKER_PORT - the port that the Pact Broker application runs on. Defaults to 9292.
  • PACT_BROKER_BASE_URL - optional. If you find that the URLs generated by the API are using an IP instead of a hostname, you can set this environment variable to force the desired base URL. Must include the port if it's a non-standard one. eg. https://my-broker:9292. Is not currently used for links in the UI.
  • PACT_BROKER_DISABLE_SSL_VERIFICATION - false by default, may be set to true.
  • PACT_BROKER_BASE_EQUALITY_ONLY_ON_CONTENT_THAT_AFFECTS_VERIFICATION_RESULTS - true by default, may be set to false.
  • PACT_BROKER_ORDER_VERSIONS_BY_DATE - true by default. Setting this to false is deprecated.

General Pact Broker configuration and usage

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

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 build to build the pact_broker container locally.
  3. 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

Don't call your service "pact_broker" as it will create an environment called PACT_BROKER_PORT which will clash with the docker images own environment variables. See this issue: pact-foundation#7

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

Running on Kubernetes

Don't call your service "pact_broker" as it will create an environment called PACT_BROKER_PORT which will clash with the docker images own environment variables. See this issue: pact-foundation#7

Database migrations

The Pact Broker auto migrates on startup, and will always do so in a way that is backwards compatible, to support architectures that run multiple instances of the application at a time (eg. AWS auto scaling).

From the /pact_broker directory on the docker image, you can run migration and rollback scripts via rake. A rollback would be required if you needed to downgrade your Pact Broker image.

To work out which migration to rollback to, select the tag of the Pact Broker gem version you want at https://github.com/pact-foundation/pact_broker and then look in the db/migrations directory. Find the very last migration in the directory, and take the numbers at the start of the file name. This is your "target".

To rollback run:

rake pact_broker:db:migrate[target] eg rake pact_broker:db:migrate[20191101]

You can confirm the new version by running rake pact_broker:db:version

Troubleshooting

See the Troubleshooting page on the wiki.