diff --git a/.github/workflows/sync-docs.yml b/.github/workflows/sync-docs.yml index fd4cb188..9e14f571 100644 --- a/.github/workflows/sync-docs.yml +++ b/.github/workflows/sync-docs.yml @@ -11,7 +11,6 @@ on: - pact-rust-docs-updated - pact-cpp-docs-updated - pact-broker-docker-pactfoundation-docs-updated - - pact-broker-docker-dius-docs-updated - pact-broker-helm-chart-docs-updated - pact-broker-client-docs-updated - pact-net-docs-updated @@ -32,7 +31,6 @@ on: - pact-rust-docs-updated - pact-cpp-docs-updated - pact-broker-docker-pactfoundation-docs-updated - - pact-broker-docker-dius-docs-updated - pact-broker-helm-chart-docs-updated - pact-broker-client-docs-updated - pact-net-docs-updated @@ -92,10 +90,6 @@ jobs: run: bundle exec scripts/sync/pact_broker_docker_pactfoundation.rb && echo 'COMMIT_MESSAGE=synced pactfoundation/pact-broker docker image docs' >> $GITHUB_ENV if: steps.identify_event.outputs.update_event == 'pact-broker-docker-pactfoundation-docs-updated' - - name: Sync dius/pact-broker Docker image docs - run: bundle exec scripts/sync/pact_broker_docker_dius.rb && echo 'COMMIT_MESSAGE=synced dius/pact-broker docker image docs' >> $GITHUB_ENV - if: steps.identify_event.outputs.update_event == 'pact-broker-docker-dius-docs-updated' - - name: Sync Pact Broker Helm Chart docs run: bundle exec scripts/sync/pact_broker_helm_chart.rb && echo 'COMMIT_MESSAGE=synced pact-broker Helm Chart docs' >> $GITHUB_ENV if: steps.identify_event.outputs.update_event == 'pact-broker-helm-chart-docs-updated' diff --git a/scripts/sync/pact_broker_docker_dius.rb b/scripts/sync/pact_broker_docker_dius.rb deleted file mode 100755 index dfe62843..00000000 --- a/scripts/sync/pact_broker_docker_dius.rb +++ /dev/null @@ -1,18 +0,0 @@ -#!/usr/bin/env ruby -require_relative 'support' - -SOURCE_REPO = 'dius/pact_broker-docker' -DESTINATION_DIR = relative_path_to('docs/pact_broker/docker_images') -TRANSFORM_PATH = -> (path) { File.join(DESTINATION_DIR, path.downcase).gsub('/readme.md', '/dius.md') } -INCLUDE = [ - ->(path) { %w{README.md}.include?(path) } -] -IGNORE = [] -CUSTOM_ACTIONS = [ - [:all, ->(md_file_contents) { md_file_contents.extract_title } ], - ["README.md", ->(md_file_contents) { md_file_contents.fields[:title] = "dius/pact-broker" } ] -] - -FileUtils.mkdir_p DESTINATION_DIR - -sync(SOURCE_REPO, INCLUDE, IGNORE, TRANSFORM_PATH, CUSTOM_ACTIONS) diff --git a/scripts/sync/pact_jvm.rb b/scripts/sync/pact_jvm.rb index e3ad4369..8968e5de 100755 --- a/scripts/sync/pact_jvm.rb +++ b/scripts/sync/pact_jvm.rb @@ -1,7 +1,7 @@ #!/usr/bin/env ruby require_relative 'support' -SOURCE_REPO = 'DiUS/pact-jvm' +SOURCE_REPO = 'pact-foundation/pact-jvm' DESTINATION_DIR = relative_path_to('docs/implementation_guides/jvm') TRANSFORM_PATH = -> (path) { # Rename README.md file, but not the top level README diff --git a/website/docs/faq.md b/website/docs/faq.md index faab2000..93651828 100644 --- a/website/docs/faq.md +++ b/website/docs/faq.md @@ -246,7 +246,7 @@ When Pact reads the pact files for verification on the Provider side, it needs t **Here are some options** * Create a Mock authentication service used during testing - this gives you the best control. -* If using the JVM, you can use [request filters](https://github.com/DiUS/pact-jvm/tree/master/pact-jvm-provider-gradle#modifying-the-requests-before-they-are-sent) to modify the request headers before they are sent to the Provider. +* If using the JVM, you can use [request filters](https://github.com/pact-foundation/pact-jvm/tree/master/pact-jvm-provider-gradle#modifying-the-requests-before-they-are-sent) to modify the request headers before they are sent to the Provider. * If using Pact JS you can use [request filters](https://github.com/pact-foundation/pact-js#modify-requests-prior-to-verification-request-filters) * If using Pact Go you can use [request filters](https://github.com/pact-foundation/pact-go#request-filtering) * Configure a relaxed OAuth2 validation service on the Provider that accepts any valid headers, so long as the match the spec \(e.g. `Authorization` header\). You might leverage the [provider states](http://docs.pact.io/getting_started/provider_states) feature for this. diff --git a/website/docs/getting_started/further_reading.md b/website/docs/getting_started/further_reading.md index feaafb0b..7bf801b1 100644 --- a/website/docs/getting_started/further_reading.md +++ b/website/docs/getting_started/further_reading.md @@ -17,7 +17,7 @@ Hear how Soundcloud ["Move Fast and Consumer-Driven-Contract-Testing Things"](ht ## Implementations * [Ruby Pact](https://github.com/pact-foundation/pact-ruby) -* [JVM Pact](https://github.com/DiUS/pact-jvm) and [Scala-Pact](https://github.com/ITV/scala-pact) +* [JVM Pact](https://github.com/pact-foundation/pact-jvm) and [Scala-Pact](https://github.com/ITV/scala-pact) * [.NET Pact](https://github.com/SEEK-Jobs/pact-net) * [JS Pact](https://github.com/pact-foundation/pact-js) * [Go Pact](https://github.com/pact-foundation/pact-go) diff --git a/website/docs/implementation_guides/jvm.md b/website/docs/implementation_guides/jvm.md index 80fdd0f6..9dec4276 100644 --- a/website/docs/implementation_guides/jvm.md +++ b/website/docs/implementation_guides/jvm.md @@ -2,7 +2,7 @@ title: Overview --- -[Pact JVM](https://github.com/DiUS/pact-jvm) is currently compliant to Pact Specification Version [3.0](https://github.com/pact-foundation/pact-specification/tree/version-3). +[Pact JVM](https://github.com/pact-foundation/pact-jvm) is currently compliant to Pact Specification Version [4.0](https://github.com/pact-foundation/pact-specification/tree/version-4). Head to the [README](jvm/readme) to get started with Pact on the JVM \(Java, Scala, Clojure etc.\). diff --git a/website/docs/pact_broker/administration/maintenance.md b/website/docs/pact_broker/administration/maintenance.md index d1c65ebb..d01aa2a4 100644 --- a/website/docs/pact_broker/administration/maintenance.md +++ b/website/docs/pact_broker/administration/maintenance.md @@ -66,9 +66,3 @@ If you have a very large database, and you are just now enabling the clean, the #### pactfoundation/pact-broker Docker image See the [environment variable documentation here](/pact_broker/docker_images/pactfoundation#automatic-data-clean-up) - -#### dius/pact-broker Docker image - -Not released yet. - - diff --git a/website/docs/pact_broker/advanced_topics/using-tls.md b/website/docs/pact_broker/advanced_topics/using-tls.md index c0f51b1c..96057110 100644 --- a/website/docs/pact_broker/advanced_topics/using-tls.md +++ b/website/docs/pact_broker/advanced_topics/using-tls.md @@ -51,7 +51,7 @@ bTk5fOGqTBqgzp1BgJKIKhI9CIUeAUYwggCWOeZnq4dpMkXH1xbsk4MMSOTimWbe You'll need to configure the certificate both your development environment and your CI. It's a bit of a hassle, so again, do consider a CA signed certificate from [Let's Encrypt](https://letsencrypt.org) instead. -You can use this [Docker Compose](https://github.com/DiUS/pact_broker-docker/blob/master/docker-compose.yml) file to spike and troubleshoot connecting to a broker with a self signed certificate. Once you have run `docker-compose up` once and seen it work with the built in files, replace the certificate and key files with your own and run `docker-compose down` and `docker-compose up`. +You can use this [Docker Compose](https://github.com/pact-foundation/pact-broker-docker/blob/master/docker-compose.yml) file to spike and troubleshoot connecting to a broker with a self signed certificate. Once you have run `docker-compose up` once and seen it work with the built in files, replace the certificate and key files with your own and run `docker-compose down` and `docker-compose up`. ##### Extracting a copy of the certificate from a running Pact Broker diff --git a/website/docs/pact_broker/docker_images.md b/website/docs/pact_broker/docker_images.md index 9a12fb44..4be3b7f9 100644 --- a/website/docs/pact_broker/docker_images.md +++ b/website/docs/pact_broker/docker_images.md @@ -5,7 +5,7 @@ sidebar_label: Overview The Pact Broker is an application for sharing for Pact contracts and verification results, and is required for integrating Pact into CI/CD pipelines. -There are currently two supported Docker images: one which based on [Alpine, running on Puma](/pact_broker/docker_images/pactfoundation), and one which is based on [Ubuntu, running Phusion Passenger](/pact_broker/docker_images/dius). See [Which Docker image should I use?](#which-docker-image-should-i-use) for a comparison. +There is currently one supported Docker image based on [Alpine, running on Puma](/pact_broker/docker_images/pactfoundation). While there are [high level instructions][rollyourown] provided for running the application outside of Docker, we cannot provide support for these installations, as there are too many variables. @@ -13,27 +13,4 @@ While there are [high level instructions][rollyourown] provided for running the If you want to try out a Pact Broker that can be accessed by all your teams, without having to fill in infrastructure 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 user and teams management. 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... - -## Which Docker image should I use? - -The `pactfoundation` image: - -* Uses Puma on Alpine -* Is smaller -* Does not require root to run (and hence, can only run on ports above 1024) -* Will not restart itself if it crashes -* Is more suited to being run by a Docker container orchestration service (ECS, Fargate, Kubernetes etc.) - -The `dius` image: - -* Uses Passenger on Ubuntu -* Is bigger -* Requires root to run (and hence, can run on ports under 1024) -* Will restart the child processes if they crash. - -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 Puma based `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. - - [rollyourown]: https://github.com/pact-foundation/pact_broker#rolling-your-own diff --git a/website/docs/pact_broker/docker_images/dius.md b/website/docs/pact_broker/docker_images/dius.md deleted file mode 100644 index f3acde72..00000000 --- a/website/docs/pact_broker/docker_images/dius.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: dius/pact-broker -custom_edit_url: https://github.com/dius/pact_broker-docker/edit/master/README.md ---- - - - -[![Build Status](https://travis-ci.org/DiUS/pact_broker-docker.svg)](https://travis-ci.org/DiUS/pact_broker-docker) - -This repository contains a Dockerized [Pact Broker](https://github.com/pact-foundation/pact_broker). You can pull the `dius/pact-broker` image from [Dockerhub](https://hub.docker.com/r/dius/pact-broker/). - -> A smaller and sexier Docker image has now been built in the [Pact Foundation](https://github.com/pact-foundation/pact-broker-docker) 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 - -* A running postgresql database and the ability to connect to it (see [POSTGRESQL.md][postgres]). -* If on Mac, you will need the `timeout` or `gtimeout` function. You can install `gtimeout` using `brew install coreutils`. - -## Getting Started - -1. [Install Docker](https://docs.docker.com/engine/installation/) - -### 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): - - * `PACT_BROKER_DATABASE_ADAPTER` (set to 'sqlite') - * `PACT_BROKER_DATABASE_NAME` (arbitrary name eg. /tmp/pact_broker.sqlite) - -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 - -* Use `-p 80:80` to start the docker image, as some of the Rack middleware gets confused by receiving requests for other ports and will return a 404 otherwise (port forwarding does not rewrite headers). -* 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 80. -* The application makes use of the phusion passenger 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][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](#heartbeat-url). - -## Using SSL - -See the [Pact Broker configuration documentation][reverse-proxy]. - -## 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`), 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](https://docs.pact.io/pact_broker/configuration#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_BASE_URL` - optional but *strongly recommended* when deploying the Pact Broker to production as it prevents some [security vulnerabilities](https://www.cloudflare.com/learning/dns/dns-cache-poisoning/). 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`. This can also be used if you are mounting the Docker container so that it runs on a non root context eg. `https://my-company.com/pact-broker`. Not that this setting does not change where the application is mounted within the Docker container - it just changes the links. -* `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. -* `PACT_BROKER_DISABLE_SSL_VERIFICATION` - `false` by default, may be set to `true`. Disables SSL verification for webhook endpoints. - -## General Pact Broker configuration and usage - -Documentation for the Pact Broker application itself can be found in the Pact Broker [docs][pact-broker-docs]. - -## Running with Docker Compose - -For a quick start with the Pact Broker and Postgres, we have an example -[Docker Compose][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: - -```sh -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](https://github.com/jaimeniswonger/pact-broker-openshift) for an example config file. - -# Troubleshooting - -See the [Troubleshooting][troubleshooting] page on the wiki. - -[badges]: https://docs.pact.io/pact_broker/advanced_topics/provider_verification_badges -[troubleshooting]: https://github.com/pact-foundation/pact-broker-docker/wiki/Troubleshooting -[postgres]: https://github.com/DiUS/pact_broker-docker/blob/master/POSTGRESQL.md -[test-script]: https://github.com/DiUS/pact_broker-docker/blob/master/script/test.sh -[docker-compose]: https://github.com/DiUS/pact_broker-docker/blob/master/docker-compose.yml -[pact-broker-docs]: https://docs.pact.io/pact_broker/ -[reverse-proxy]: https://docs.pact.io/pact_broker/configuration#running-the-broker-behind-a-reverse-proxy diff --git a/website/docs/pact_broker/upgrading.md b/website/docs/pact_broker/upgrading.md index 2413e2de..4819cf73 100644 --- a/website/docs/pact_broker/upgrading.md +++ b/website/docs/pact_broker/upgrading.md @@ -10,7 +10,7 @@ We recommend you back up your database before performing an upgrade, just to be ## For Docker images -Change the tag to the latest available version (following semantic versioning rules) from the [pact-foundation](https://hub.docker.com/r/pactfoundation/pact-broker/tags?page=1&ordering=last_updated) organisation or the [DiUS](https://hub.docker.com/repository/docker/dius/pact-broker/tags?page=1&ordering=last_updated) organisation, and redeploy your Docker managed infrastructure. Remember not use the tag `latest`, for a production installation of the Pact Broker. +Change the tag to the latest available version (following semantic versioning rules) from the [pact-foundation](https://hub.docker.com/r/pactfoundation/pact-broker/tags?page=1&ordering=last_updated) organisation, and redeploy your Docker managed infrastructure. Remember not use the tag `latest`, for a production installation of the Pact Broker. ## For native Ruby installations