diff --git a/website/docs/docs/ai/using.md b/website/docs/docs/ai/using.md index 512c06c6..cb5b618f 100644 --- a/website/docs/docs/ai/using.md +++ b/website/docs/docs/ai/using.md @@ -414,4 +414,44 @@ In AI, context is key. The more relevant information you can provide the more ta ### 3. Use Test Templates -Test Templates reduce the amount of refactoring required after generation. If you start to see a common generation pattern you wish to avoid, update the Test Template to help PactFlow AI generate improved output. \ No newline at end of file +Test Templates reduce the amount of refactoring required after generation. If you start to see a common generation pattern you wish to avoid, update the Test Template to help PactFlow AI generate improved output. + +## Comparing PactFlow AI with Other AI Tools + +PactFlow AI is purpose-built for contract testing workflows. While general-purpose AI tools like ChatGPT, GitHub Copilot, and IDE-native assistants (e.g., Windsurf) offer broad utility, they are not optimized for *specific* domains and use cases like contract testing with Pact. + +The table below outlines key differences between these tools to help you understand how PactFlow AI can be incorporated into your development process. + +### Feature Comparison + +| Feature | **PactFlow AI** | **ChatGPT / Claude** | **GitHub Copilot** | **IDE-native AI (e.g., Windsurf)** | +|--------|------------------|----------------------|--------------------|-------------------------------| +| **Primary Use Case** | Contract test generation, review, and maintenance | General knowledge, Q&A, prototyping | Inline code suggestions | IDE-embedded assistant for development tasks | +| **Breadth of Application** | Focused on Pact | Wide range of dev and non-dev tasks | General-purpose coding | Full-stack code, terminal, file editing | +| **Strength in General Coding** | ❌ Not built for general-purpose coding | ✅ Excellent at most languages and use cases | ✅ Great for scaffolding and boilerplate | ✅ Helps with app logic, CLI, tests, refactors | +| **Integration Surface** | CLI (now), IDE via MCP (coming), UI (planned) | Chat/web/app with integrations | Deep IDE integration (VS Code, JetBrains), Web/UI | Native to Cursor, Cline, etc. | +| **Contract Testing Support** | ✅ Pact-specific knowledge, updated DSLs, test structure and matcher guidance | ❌ Generic or outdated knowledge | ❌ May suggest invalid or old Pact patterns | ❌ No contract testing awareness | +| **Contract Testing Maintenance** | ✅ Review, update, and fix existing Pact tests | ❌ Prompt-based only | ❌ Suggests code, not test upkeep | ❌ Not designed for test maintenance | +| **TDD Alignment** | ✅ Encourages scoped, purposeful test creation | ❌ May reinforce ad hoc development | ✅ Scaffolds tests, but not goal-oriented | ⚠️ Speed-optimized, not test-structured | +| **Human-in-the-loop Design** | ✅ AI suggestions are reviewable and optional | ⚠️ User must prompt and validate output | ✅ Autocomplete with human review | ⚠️ High-speed, low-friction suggestions | +| **Governance & Control** | ✅ RBAC-aware, CLI and platform-controlled | ⚠️ Black-box models, limited traceability | ⚠️ Limited observability | ⚠️ Tool-dependent privacy and trust model | + +### When to Use Each Tool + +| Use Case | Recommended Tool | +|----------|------------------| +| Creating and maintaining Pact tests | **PactFlow AI** | +| Prototyping or researching APIs, code patterns | **ChatGPT / Claude** | +| Writing app logic, scaffolding components or full-stack development in IDE | **GitHub Copilot**, **IDE-native AI tools** | + +### Summary + +PactFlow AI is not designed to replace general-purpose AI tools. Instead, it complements them by offering deep, current knowledge of contract testing—particularly Pact. + +While other tools can help with coding in general, they do not provide guidance on: +- Pact test quality +- Over-specification and drift detection +- DSL correctness and best practices +- And other contract-testing specific capabilities + +For teams working with Pact, PactFlow AI acts as a domain expert—reviewing, generating, and maintaining tests with precision and context. diff --git a/website/docs/docs/on-premises-2x.md b/website/docs/docs/on-premises-2x.md new file mode 100644 index 00000000..f0ead206 --- /dev/null +++ b/website/docs/docs/on-premises-2x.md @@ -0,0 +1,57 @@ +--- +title: PactFlow On-Premises Architecture +sidebar_label: Architecture +--- + +## System architecture + +### Minimum requirements + +* An application server capable of running Docker +* PostgreSQL database +* Redis cache +* SAML IDP for SSO +* PactFlow license file + +### Recommended architecture + +* Deploy to a service designed for Docker container orchestration (ECS, Fargate, Kubernetes etc.) + +### Example AWS deployment using ECS + +![System architecture](/img/saas-architecture-2x.png) + +## Internal architecture + +The PactFlow On-Premises application is distributed as a Docker image. It is based on the open source [Pact Broker](https://github.com/pact-foundation/pact_broker), which is a Ruby application. + +### Application user requirements + +The PactFlow application does not need any elevated privileges to run. It runs under the user `app`. + +### Application port + +The PactFlow application runs on port `9292` by default. This can be configured by setting the [PACTFLOW_HTTP_PORT](/docs/on-premises/environment-variables#pactflow_http_port) environment variable. + +### Healthcheck endpoint + +A healthcheck endpoint for use by a Docker container managment service is available at `http:///diagnostic/status/heartbeat`. No authentication is required. This endpoint does not make a connection to the database. You can use this check to confirm your load balancer targets are healthy. + +If the healthcheck is running from inside the container, make sure to use the port defined in the environment variable `$PACTFLOW_HTTP_PORT`, which defaults to `9292`. You can use `supervisorctl` to perform the healthcheck request. + +An example healthcheck configuration for Docker Compose: + +```yaml +healthcheck: + test: ["supervisorctl", "status", "haproxy", "marko", "pactflow"] + interval: 30s + timeout: 10s + retries: 3 +``` + +To check the connection to the database, use the endpoint `/diagnostic/status/dependencies`. This endpoint should not be used by Docker container managment services, as unrelated database issues might cause the Docker container to churn. + +### License file + +PactFlow on-premises version requires a license file to run. [Contact us](https://support.smartbear.com/pactflow/message/) if you have not +received one when your account was setup. See the [section on licenses for installation instructions](/docs/on-premises/license). diff --git a/website/docs/docs/on-premises-2x/authentication.md b/website/docs/docs/on-premises-2x/authentication.md new file mode 100644 index 00000000..3684ff6a --- /dev/null +++ b/website/docs/docs/on-premises-2x/authentication.md @@ -0,0 +1,16 @@ +--- +title: Authentication +--- + +## User interface + +The PactFlow On-Premises application currently supports single sign for SAML identity providers. It supports both IDP and SP initiated log in. + +Any user who is able to authenticate to the configured IDP is allowed access to PactFlow. + +The SAML IDP is configured via [environment variables](environment-variables#saml-authentication). + +## API + +The API is accessed using a bearer token that is set in the HTTP header of the request (eg. `Authorization: Bearer `). The tokens are administered on a per user basis in the [settings page](/docs/user-interface/settings/api-tokens) of the PactFlow application. + diff --git a/website/docs/docs/on-premises-2x/authentication/demo.md b/website/docs/docs/on-premises-2x/authentication/demo.md new file mode 100644 index 00000000..c9544f14 --- /dev/null +++ b/website/docs/docs/on-premises-2x/authentication/demo.md @@ -0,0 +1,29 @@ +--- +title: Demo Auth +--- + +To allow experimentation with PactFlow without the need to configure an external identity provider, the "demo" authentication provider can be enabled. With demo auth enabled, any user can log in to PactFlow by providing a name and email address. No password is used to authenticate the user. + +The first user to log in will be assigned the [Administrator](/docs/permissions/predefined-roles#administrator) role, and every user thereafter will receive the default ([User](/docs/permissions/predefined-roles#user)) role. + +After a user has logged in, they may perform all the actions their role allows, as if they were a user created via a real identify provider. + +:::caution + +This method of authentication is NOT secure and should not be used in production. + +::: + +Demo auth replaces the basic auth capability that was previously used for this purpose. + +## Configuration + +See the [Demo](/docs/on-premises-2x/environment-variables#demo_auth_enabled) section of the environment variables page. Demo auth cannot be enabled at the same time as any other method of authentication (ie. SAML). + +## Converting to a production IDP + +Demo authentication cannot be enabled at the same time as a real authentication provider (eg. SAML). We recommend starting with a clean database when installing PactFlow for production use. This will ensure no demo users remain in the system. + +## Docker Compose example + +This [Docker Compose example](/docs/on-premises-2x/docker-compose-example) is configured using Demo Auth. diff --git a/website/docs/docs/on-premises-2x/authentication/oauth2.md b/website/docs/docs/on-premises-2x/authentication/oauth2.md new file mode 100644 index 00000000..81aea089 --- /dev/null +++ b/website/docs/docs/on-premises-2x/authentication/oauth2.md @@ -0,0 +1,48 @@ +--- +title: OAuth2 +--- + +## Configuration + +An OAuth2 identify provider is configured by a set of environment variables prefixed with `PACTFLOW_TEST_OAUTH2_`, or using the `test_oauth2` key in a YAML configuration file. See the [Test OAuth2](/docs/on-premises-2x/environment-variables/1.14-beta) section of the environment variables page for the full list. + +## Callback URL + +The callback URL is `https:///auth/oauth2/callback`. This must be configured in the settings for the PactFlow client in your Identify Provider. + +## Authorize params + +The following parameters are sent to the Identity Provider's configured [`authorize_url`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__authorize_url) during the request phase. + +| Parameter | Description | +|-----------|-------------| +| scope | `openid profile email` | +| response_type | `code` | +| response_mode | `form_post` | +| state | A randomly generated hex string | +| client_id | The configured [client_id](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_id) | +| redirect_uri | The [callback URL](#callback-url) as documented above | + +The parameters configured in the [`custom_authorize_params`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__custom_authorize_params__key) are also merged into these default parameters. + +## Token params + +The following parameters are sent to the Identity Provider's configured [`token_url`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__token_url). + +| Parameter | Description | +|-----------|-------------| +| code | The `code` returned by the IDP during the callback phase. | +| grant_type | `authorization_code` | +| client_id | The configured [client_id](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_id) | +| client_secret | The configured [client_secret](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__client_secret) | +| redirect_uri | The [callback URL](#callback-url) as documented above | + +The parameters configured in the [`custom_token_params`](/docs/on-premises-2x/environment-variables/1.14-beta#pactflow_test_oauth2__custom_token_params__key) are also merged into these default parameters. + +## Custom Auth handler + +At the end of the OAuth2 login flow, a JWT is retrieved by PactFlow from the customer's Identify Provider. A custom Ruby auth handler configuration file will be supplied by PactFlow to map claims from the JWT to PactFlow roles and teams. The auth handler configuration file must be mounted as a volume on the PactFlow container, in the directory `/home/pactflow/extensions/` eg. `/home/pactflow/extensions/auth_ext_script.rb`. + +## Debugging + +The URLs and headers of the HTTP interactions with the Identity Provider will be logged at `info` level in the PactFlow logs. To see the request and response bodies, set the `PACTFLOW_LOG_LEVEL` to `debug`. Note that this will log sensitive information, so do not leave the logging at this level permanently. diff --git a/website/docs/docs/on-premises-2x/authentication/saml.md b/website/docs/docs/on-premises-2x/authentication/saml.md new file mode 100644 index 00000000..b3840c69 --- /dev/null +++ b/website/docs/docs/on-premises-2x/authentication/saml.md @@ -0,0 +1,128 @@ +--- +title: SAML +--- + +PactFlow supports single sign on using the SAML authentication protocol. + +Once SAML has been configured, if the database contains no users, the first user to log in will be assigned the [Administrator](/docs/permissions/predefined-roles#administrator) role, and every user thereafter will receive the default ([User](/docs/permissions/predefined-roles#user)) role. + +## Configuration + +A SAML provider is configured by a set of environment variables prefixed with `PACTFLOW_SAML_`. See the [SAML](/docs/on-premises-2x/environment-variables#saml-authentication) section of the environment variables page for the full list. + +## Assertion Consumer URL + +This is the endpoint to which the IDP will post the SAML assertion after the user is authenticated. It is also called the "sign on URL", "reply URL", and "callback URL", depending on your IDP. You will need to configure this value in your IDP when you set up the PactFlow service provider. + +The URL is `https:///auth/saml/callback`. + +## Metadata URL + +The PactFlow SAML service provider metadata URL is available at `https:///auth/saml/metadata`. + +## Configuring multiple SAML providers + +In PactFlow 1.7.0 and later, multiple SAML providers may be configured. To configure a second SAML provider, create another set of the [SAML environment variables](/docs/on-premises-2x/environment-variables#saml-authentication) with the prefix `PACTFLOW_SAML_2_` (and `PACTFLOW_SAML_3_` for the third, etc). The `PACTFLOW_SAML_ISSUER` does not need to be specified again, as it is shared between all SAML providers. + +The callback path for the second provider is `/auth/saml/2/callback`, and for the third `/auth/saml/3/callback` etc. The path for the metadata for subsequent SAML providers will be `/auth/saml/2/metadata`, `/auth/saml/3/metadata` etc. + +## Configuring Azure Active Directory + +### Create a non gallery application + +* Follow the [Microsoft documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-non-gallery-app) for creating a non gallery application. + * Choose `Non-gallery application` at the `Add your own app` screen. + * Set the name to `PactFlow On-Premesis` when prompted. + +* When the application has been created, assign the users that should be allowed to login to PactFlow. + +* Once the users have been assigned, select the `Single sign-on` tab. Select `SAML`. + +* Set the Identifier (Entity ID) to `https://pactflow.` eg. `https://pactflow.mycompany.com`. This field must match the [PACTFLOW_SAML_ISSUER]../(environment-variables#pactflow_saml_issuer) environment variable. + +* Set the Reply URL to `https:///auth/saml/callback` + +* Leave the Sign On URL, Relay State and Logout Url fields blank. + +### Configure the PactFlow environment variables + +You can find a template for the required environment variables [here](/docs/on-premises-2x/environment-variables/templates#azure-active-directory). + +* Set the [PACTFLOW_SAML_ISSUER](/docs/on-premises-2x/environment-variables#pactflow_saml_issuer) to the `Identifier (Entity ID)`. +* Set the [PACTFLOW_SAML_IDP_SSO_TARGET_URL](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_sso_target_url) to the `Login URL`. +* Set the [PACTFLOW_SAML_IDP_ENTITY_ID](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_entity_id) to the `Azure AD Identifier` +* Set the [PACTFLOW_SAML_IDP_CERT_FINGERPRINT](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_cert_fingerprint) to the `Thumbprint` +* Set the [PACTFLOW_SAML_IDP_NAME](/docs/on-premises-2x/environment-variables#pactflow_saml_idp_name) to your choice - this is a display name for the login button. +* Set the identifier, email and name attributes as per the [template](/docs/on-premises-2x/environment-variables#/templates#azure-active-directory). + + +## Docker Compose Example + +Follow [steps 1 and 2](/docs/on-premises-2x/docker-compose-example) from the Docker Compose example that uses Demo Auth, then use the following `docker-compose.yml` file to run your services. + +``` +version: "3" + +services: + simplesaml: + image: kristophjunge/test-saml-idp + logging: + driver: none # comment out the logging config to see the SAML server logs + ports: + - "8080:8080" + - "8443:8443" + environment: + - SIMPLESAMLPHP_SP_ENTITY_ID=https://pactflow.io + - SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://localhost/auth/saml/callback + + pactflow: + image: quay.io/pactflow/enterprise + depends_on: + - postgres + environment: + - PACTFLOW_HTTP_PORT=9292 + - PACTFLOW_BASE_URL=http://localhost + - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres + # insecure settings only for the purposes of this demo! Not to be used in production. + - PACTFLOW_DATABASE_SSLMODE=disable + - PACTFLOW_REQUIRE_HTTPS=false + - PACTFLOW_LOG_FORMAT=short # normally this would be set to json, use short for demo only + - PACTFLOW_ADMIN_API_KEY=admin + - PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY=thisissomerandombytes + - PACTFLOW_SAML_AUTH_ENABLED=true + - PACTFLOW_SAML_IDP_NAME=Simple SAML + - PACTFLOW_SAML_IDP_SSO_TARGET_URL=http://localhost:8080/simplesaml/saml2/idp/SSOService.php + - PACTFLOW_SAML_IDP_CERT_FINGERPRINT=11:9B:9E:02:79:59:CD:B7:C6:62:CF:D0:75:D9:E2:EF:38:4E:44:5F + - PACTFLOW_SAML_IDP_ID_ATTRIBUTE=uid + - PACTFLOW_SAML_EMAIL_ATTRIBUTE=email + - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret--------- + - PACT_BROKER_ADMIN_API_KEY=admin + - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/ + ports: + - "80:9292" + healthcheck: + test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"] + interval: 30s + timeout: 10s + retries: 3 + entrypoint: dockerize + command: -wait tcp://postgres:5432 docker-entrypoint + volumes: + - ./pactflow-onprem.lic:/home/pactflow-onprem.lic + + postgres: + image: postgres:13-alpine + healthcheck: + test: psql postgres --command "select 1" -U postgres + ports: + - "5432:5432" + volumes: + - postgres-volume:/var/lib/postgresql/data + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: password + POSTGRES_DB: postgres + +volumes: + postgres-volume: +``` diff --git a/website/docs/docs/on-premises-2x/database.md b/website/docs/docs/on-premises-2x/database.md new file mode 100644 index 00000000..7716694e --- /dev/null +++ b/website/docs/docs/on-premises-2x/database.md @@ -0,0 +1,60 @@ +--- +title: Database +--- + +A PostgreSQL database is required for storage of the application data. + +:::info + If you would like to migrate an existing PostgreSQL database, skip this section and instead follow the guide [**here**](/docs/on-premises-2x/installation/migrating). +::: + +## Supported versions + +PostgreSQL version 10.6 and later are supported. + +## Database creation + +Log in as your database administrator, and execute the following statements in an SQL session. + +```sql +CREATE USER pactflow_user WITH PASSWORD ''; +CREATE DATABASE pactflow; +GRANT ALL PRIVILEGES ON DATABASE pactflow TO pactflow_user; +REVOKE ALL ON DATABASE pactflow FROM PUBLIC; +``` + +## SSL + +The application's PostgreSQL SSL mode is set to `require` by default, which means it requires the connection to the database to be encrypted, but does not verify the server's certificate. See the documentation for the [PACTFLOW_DATABASE_SSLMODE](environment-variables#pactflow_database_sslmode) environment variable for more options. It is not recommended to use any option weaker than `require`. + +## Authentication + +## Username/password authentication + +Database access between the PactFlow application and Postgres instance can be secured using a [username](/docs/on-premises-2x/environment-variables#pactflow_database_username) and [password](/docs/on-premises-2x/environment-variables#pactflow_database_password), configured via environment variables. + +## AWS IAM authentication + +When deploying PactFlow on AWS Cloud infrastructure, database access between the PactFlow application and the RDS Postgres instance can be secured using IAM. Please see the [AWS RDS IAM documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAM.html) for more information. + +The following environmet variables must be set for the PactFlow application: + +* [`PACTFLOW_DATABASE_ADAPTER="postgresiam"`](/docs/on-premises-2x/environment-variables#pactflow_database_adapter) +* [`PACTFLOW_DATABASE_USERNAME`](/docs/on-premises-2x/environment-variables#pactflow_database_username) +* [`PACTFLOW_DATABASE_HOST`](/docs/on-premises-2x/environment-variables#pactflow_database_host) +* [`PACTFLOW_DATABASE_PORT`](/docs/on-premises-2x/environment-variables#pactflow_database_port) +* [`PACTFLOW_DATABASE_NAME`](/docs/on-premises-2x/environment-variables#pactflow_database_name) +* [`PACTFLOW_DATABASE_SSLMODE="require"`](/docs/on-premises-2x/environment-variables#pactflow_database_sslmode) +* [`AWS_REGION`](/docs/on-premises-2x/environment-variables#aws_region) + +## Schema migrations + +The database schema migrations will be run automatically on start up. See the documentation on [Database migrations](upgrading/database-migrations) for more information. + +### Migrating from OSS Pact Broker to PactFlow + +If you have been hosting your own instance of the open source Pact Broker, you can point the new PactFlow On-Premises application at the same database, and the missing migrations will be applied. + +## Schema + +![Database schema](/on-premises/schema.png) diff --git a/website/docs/docs/on-premises-2x/docker-compose-example.md b/website/docs/docs/on-premises-2x/docker-compose-example.md new file mode 100644 index 00000000..2b5cd739 --- /dev/null +++ b/website/docs/docs/on-premises-2x/docker-compose-example.md @@ -0,0 +1,128 @@ +--- +title: Docker Compose example +--- + +In this guide, we'll provide an example `docker compose` setup so that you can see how all of the bits hang together. We will demonstrate: + +* Authenticating to Quay.io +* Running the PactFlow enterprise container +* Persistent storage with a postgres database + +**Pre-requsites** +* [Docker](https://docs.docker.com/engine/install/) +* [Docker Compose](https://docs.docker.com/compose/install/) +* A working *nix environment and access to a terminal +* Valid credentials to authenticate to our [Docker image registry](docker-image-registry) +* PactFlow license file + +## 1. Authenticating to Quay.io + +After obtaining valid robot credentials, you need to authenticate to Quay.io so that the docker engine is able to fetch our images. + +``` +docker login -u="" -p="" quay.io +docker pull quay.io/pactflow/enterprise +``` + +After this, you should have the latest PactFlow enterprise image on your machine. You can verify by executing + +```sh +docker images quay.io/pactflow/enterprise +``` + +Which should produce an output such as: + +```sh +> docker images quay.io/pactflow/enterprise +REPOSITORY TAG IMAGE ID CREATED SIZE +quay.io/pactflow/enterprise 2.0.0 32db429fda01 1 day ago 462MB # <- this guide applies to 2.x.x version +quay.io/pactflow/enterprise latest 32db429fda01 1 day ago 462MB +quay.io/pactflow/enterprise 1.36.0 7f9b3c3aa50e 7 weeks ago 454MB +``` + +## 2. PactFlow license file + +The PactFlow on-premises version requires a license file to run. You should have received this from us during the +on-boarding process. If not, please contact your Account Manager. + +Save the license file into a temporary directory with the name `pactflow-onprem.lic` (it needs to be the same directory as used in step 3). + +## 3. Startup PactFlow and supporting services + +Save the below file as `docker-compose.yml` in the same directory as the license file and then run `docker-compose up`: + +```yaml +version: "3" + +services: + pactflow: + image: quay.io/pactflow/enterprise:2.0.0 + depends_on: + - postgres + - redis + environment: + # This is set to localhost for this example but in a real deployment, this needs to be set to the actual URL of the application + - PACTFLOW_BASE_URL=http://localhost + # Insecure setting only for the purposes of this demo! Not to be used in production. + - PACTFLOW_DATABASE_SSLMODE=disable + # Insecure setting only for the purposes of this demo! Not to be used in production. + - PACTFLOW_REQUIRE_HTTPS=false + # Demo auth should only be used for demo purposes. Not to be used in production. + - PACTFLOW_DEMO_AUTH_ENABLED=true + # 'Allow all' for the webhook host whitelist should only be used for demo purposes. See docs for configuring this in production. + - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/ + - PACTFLOW_HTTP_PORT=9292 + # Link to the postgres database + - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres + - PACTFLOW_LOG_LEVEL=info + - PACTFLOW_ADMIN_API_KEY=admin + - PACTFLOW_MASTER_ENCRYPTION_KEY=thisissomerandombytes + - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret--------- + - PACT_BROKER_ADMIN_API_KEY=admin + - PACTFLOW_HTTP_LOGGING_ENABLED=true + # Link to the redis cache + - REDIS_URL=redis://redis:6379 + ports: + - "80:9292" + healthcheck: + test: ["CMD", "supervisorctl", "status", "haproxy", "marko", "pactflow"] + interval: 30s + timeout: 10s + retries: 3 + volumes: + - ./pactflow-onprem.lic:/home/pactflow-onprem.lic + + postgres: + image: postgres:13-alpine + healthcheck: + test: psql postgres --command "select 1" -U postgres + volumes: + - postgres-volume:/var/lib/postgresql/data + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: password + POSTGRES_DB: postgres + + redis: + image: redis:latest + +volumes: + postgres-volume: +``` + +You can verify all services by running `docker ps`: + +``` +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +1cefdf8b1e1b quay.io/pactflow/enterprise:2.0.0 "docker-entrypoint" 24 minutes ago Up 24 minutes (healthy) 0.0.0.0:80->9292/tcp tmp_pactflow_1 +6bedae5936dc redis:latest "docker-entrypoint.s…" 2 hours ago Up 24 minutes 6379/tcp tmp_redis_1 +8b393d35a20c postgres:13-alpine "docker-entrypoint.s…" 9 days ago Up 24 minutes (healthy) 5432/tcp tmp_postgres_1 +``` + +## 3. Login to PactFlow + +Head to [http://localhost](http://localhost) in your browser, and choose to login with "PACTFLOW DEMO AUTH". Provide a name and email address to create your account and login. (The details don't need to be valid, and won't be used to send any emails.) + +That's it 🎉. + +For production use, you'll need to replicate this setup using a proper container orchestration tool, such as Kubernetes, AWS ECS/Fargate, AKS, GKE, Mesos etc, and your real Identity Provider. diff --git a/website/docs/docs/on-premises-2x/docker-image-registry.md b/website/docs/docs/on-premises-2x/docker-image-registry.md new file mode 100644 index 00000000..8a2f6880 --- /dev/null +++ b/website/docs/docs/on-premises-2x/docker-image-registry.md @@ -0,0 +1,50 @@ +--- +title: Docker image registry +--- + +## Accessing the Enterprise PactFlow container registry + +Docker images for our self-hosted PactFlow Enterprise product are hosted at [Quay](http://quay.io). We will provide Quay.io access for you when signing up to the product. + +### User Account Access + +:::note +If you are on a PactFlow trial, creating a RedHat account is **not** required. You will be issued a separate set of credentials (see [CI Access](#ci-access) below) by your Account Manager for the duration of the trial. +::: + +To set you up with console access, you will need to create a [RedHat account](https://quay.io/signin/). Choose "Register for a RedHat account" and once comwpleted, provide the username/email address to us to add you to the registry. + +Once we have granted access to your given email address, you should receive an email from Red Hat Quay confirming access to the PactFlow organization. + +### CI Access + +In additional to user access, we will create you one or more [Robot Accounts](https://docs.quay.io/glossary/robot-accounts.html) for use in CI. + +## Getting started + +Once we have created you a new user, you will receive an email from Quay.io inviting you to join a new team and a license file from us. You can setup the new account as follows: + +1. Make sure you have received a PactFlow on-premises license file from your Account Manager +1. You should receive an email from Red Hat Quay, requesting you join a team `pactflow/`: + + ![Join PactFlow repository email](/on-premises/quay-join-team-email.png) + +1. Follow the link in your email to login to an existing accoun + + +1. You will be added to the correct team and you should then see our Enterprise repository (click [Repositories](https://quay.io/repository/) in the menu bar to see this): + + ![Completed signup](/on-premises/quay-completed.png) + +1. You should now have access to the `enterprise` repository in the `pactflow` organization. + +1. You can now sign in with your account (in addition to your Robot Account) to quay to pull docker images. See [getting started with Quay.io](https://docs.quay.io/solution/getting-started.html) for more on this. + +## Downloading the image + +With your personal credentials or Robot token (provided by your PactFlow Account Manager), you can login to your docker management system and pull the image: + +```sh +docker login -u="" -p="" quay.io # you can use either the robot token or your user credentials here +docker pull quay.io/pactflow/enterprise +``` diff --git a/website/docs/docs/on-premises-2x/environment-variables.md b/website/docs/docs/on-premises-2x/environment-variables.md new file mode 100644 index 00000000..c8a60327 --- /dev/null +++ b/website/docs/docs/on-premises-2x/environment-variables.md @@ -0,0 +1,646 @@ +--- +title: Environment variables +--- + + + + + +## Logging + +
+ + + +### PACTFLOW_LOG_LEVEL + +The PactFlow application log level + +**Required:** false
+**Default:** `INFO`
+**Allowed values:** `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
+ +### PACTFLOW_HTTP_LOGGING_ENABLED + +When true, HTTP request details and response status and duration will be logged to stdout in json format + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +## Monitoring + +
+ + + +### NEW_RELIC_AGENT_ENABLED + +Set this to true to enable New Relic application monitoring. The New Relic config file should be mounted at /home/pactflow/config/newrelic.yml + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +## Database + +
+ + + +### PACTFLOW_DATABASE_URL + +The fully qualified database connection string. If using Postgres on RDS with IAM authentication, the scheme must be `postgresiam` and the port must also be set. + +**Required:** if separate host, name, username, password environment variables are not set
+**Example:** `postgresql://username:password@host:port/database`
+ +### PACTFLOW_DATABASE_ADAPTER + +The database adapter to use. Use `postgresiam` when using Postgres on RDS with IAM authentication (rather than username/password authentication). + +**Required:** false
+**Default:** `postgres`
+**Allowed values:** `postgres`, `postgresiam`
+ +### PACTFLOW_DATABASE_USERNAME + +The database username + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +### PACTFLOW_DATABASE_PASSWORD + +The database password + +**Required:** if PACTFLOW_DATABASE_URL is not set, unless using Postgres on RDS with IAM authentication
+ +### PACTFLOW_DATABASE_HOST + +The database host + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +### PACTFLOW_DATABASE_PORT + +The database port + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +### PACTFLOW_DATABASE_NAME + +The database name + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +### PACTFLOW_DATABASE_SSLMODE + +The Postgresql ssl mode. Note, if using Postgres on AWS RDS with IAM authentication, this must be `require`. + +**Required:** false
+**Default:** `require`
+**Allowed values:** `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`
+**More information:** https://ankane.org/postgres-sslmode-explained
+ +### PACTFLOW_DATABASE_CONNECTION_VALIDATION_TIMEOUT + +The number of seconds after which to check the health of a connection from a connection pool before passing it to the application. + +`-1` means that connections will be validated every time, which avoids errors +when databases are restarted and connections are killed. This has a performance +penalty, so consider increasing this timeout if building a frequently accessed service. + +**Required:** false
+**Default:** `3600`
+**Allowed values:** -1 or any positive integer.
+**More information:** https://sequel.jeremyevans.net/rdoc-plugins/files/lib/sequel/extensions/connection_validator_rb.html
+ +### PACTFLOW_SQL_LOG_WARN_DURATION + +The duration in seconds, as a float, after which to log an SQL statement + +**Required:** false
+**Default:** `5`
+ +### PACTFLOW_SQL_LOG_LEVEL + +The log level that will be specified when the SQL query statements are logged. + +**Required:** false
+**Default:** `NONE`
+**Allowed values:** `NONE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
+ +### PACTFLOW_DATABASE_MAX_CONNECTIONS + +The maximum size of the connection pool per application instance. The total number of connections for the database must be calculated by multiplying this value by the number of instances (ie. running Docker containers). + +**Required:** false
+**Default:** `4`
+**Allowed values:** A positive integer value.
+**More information:** https://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-General+connection+options
+ +### PACTFLOW_DATABASE_POOL_TIMEOUT + +The number of seconds to wait if a connection cannot be acquired before raising an error. + +**Required:** false
+**Default:** `5`
+**Allowed values:** A positive integer.
+**More information:** https://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-General+connection+options
+ +### PACTFLOW_DATABASE_AUTO_MIGRATE + +Whether or not to automatically apply the schema and data migrations to the database on startup + +**Required:** false
+**Default:** `true`
+**Allowed values:** `true`, `false`
+ +### AWS_REGION + +Required for running Postgres on RDS with IAM authentication. This must be set to the AWS region where the RDS database instance is running. + +**Required:** false
+ +## Webhooks + +
+ + + +### PACTFLOW_WEBHOOK_HOST_WHITELIST + +A space delimited list of hosts for which webhook response logging will be enabled. By default, all responses will be redacted for security purposes. To allow logging for all hosts, use the value `/.*/`. + +**Required:** false
+**Example:** `/.*\.foo\.com$/ github.com foo.slack.com`
+**More information:** https://docs.pact.io/pact_broker/configuration#webhook-whitelists
+ +### PACTFLOW_WEBHOOK_SCHEME_WHITELIST + +A space delimited list of allowed schemes for a webhook to use. + +**Required:** false
+**Default:** `https`
+**Allowed values:** `https`, `http`
+**More information:** https://docs.pact.io/pact_broker/configuration#webhook-whitelists
+ +### PACTFLOW_WEBHOOK_HTTP_METHOD_WHITELIST + +A space delimited list of allowed http methods for a webhook to use. *It is strongly recommended to only allow POST requests for security purposes.* + +**Required:** false
+**Default:** `POST`
+**Allowed values:** `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
+**More information:** https://docs.pact.io/pact_broker/configuration#webhook-whitelists
+ +### PACTFLOW_DISABLE_SSL_VERIFICATION + +Whether or not to disable SSL verificaton when executing webhooks. + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_WEBHOOK_CERTIFICATES + +A list of SSL certificate configuration objects with the properties `description`, and either `content` or `path`. These +certificates are used when a webhook needs to connect to a server that uses a self signed certificate. + +Each certificate configuration item accepts a chain of certificates in PEM format - there may be multiple 'BEGIN CERTIFICATE' and 'END CERTIFICATE' in the content of each item. + +The certificate configuration is not validated on startup. If any of the configured certificates cannot be loaded during the execution of a webhook, an error +will be logged, and they will be ignored. You can check if the configuration is working by testing the execution of +a webhook that connects to the server with the self signed certificate by following these instructions https://docs.pact.io/pact_broker/webhooks/debugging_webhooks#testing-webhook-execution + +When setting the path, the full path to the certificate file in PEM format must be specified. When using Docker, you must ensure the +certificate file is [mounted into the container](https://docs.docker.com/storage/volumes/). + +Each property of the certificate is described by an indexed environment variable in the format `PACTFLOW_WEBHOOK_CERTIFICATES____`. +Environment variables with the same index are grouped together to form the complete object. Note the use of the double underscores before the index and property. + +Example: + +```shell +PACTFLOW_WEBHOOK_CERTIFICATES__0__LABEL="An example self signed certificate with content" +PACTFLOW_WEBHOOK_CERTIFICATES__0__CONTENT="-----BEGIN CERTIFICATE----- + MIIDZDCCAkygAwIBAgIBATANBgkqhkiG9w0BAQsFADBCMRMwEQYKCZImiZPyLGQB + + jHT1Ty2CglM= + -----END CERTIFICATE-----" +PACTFLOW_WEBHOOK_CERTIFICATES__1__LABEL="An example self signed certificate with a path" +PACTFLOW_WEBHOOK_CERTIFICATES__1__PATH="/full/path/to/the/cert.pem" +``` + +**Supported versions:** From v1.14.0
+**Required:** false
+ +## SAML authentication + +
+ +To configure more than one SAML identity provider, specify another set of the following environment variables with a `_2` after the `PACTFLOW_SAML` prefix (and `_3` for the third etc.). The `PACTFLOW_SAML_ISSUER` is shared between all the SAML providers so does not need to be duplicated. + +eg. For the second SAML identity provider set `PACTFLOW_SAML_2_AUTH_ENABLED`, `PACTFLOW_SAML_2_IDP_NAME` etc and for the third `PACTFLOW_SAML_3_AUTH_ENABLED`, `PACTFLOW_SAML_3_IDP_NAME` etc. + + +### PACTFLOW_SAML_AUTH_ENABLED + +Whether or not to enable SAML authentication. + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_SAML_ISSUER + +The name of this application as it is known to the SAML IDP. + +**Required:** false
+**Default:** `https://pactflow.io`
+**Example:** `http://pactflow.mycompany.com`
+ +### PACTFLOW_SAML_IDP_NAME + +The display name of the SAML IDP. This value will be used as the login button label. + +**Required:** true
+ +### PACTFLOW_SAML_IDP_LOGO + +URL of a logo for IDP, to be displayed next to the login button. + +**Required:** false
+ +### PACTFLOW_SAML_IDP_SSO_TARGET_URL + +The URL to which the authentication request should be sent. This endpoint is on the identity provider. + +**Required:** if PACTFLOW_SAML_IDP_METADATA_URL is not set
+**More information:** https://github.com/omniauth/omniauth-saml#options
+ +### PACTFLOW_SAML_IDP_CERT_FINGERPRINT + +The SHA1 fingerprint of the certificate, e.g. "90:CC:16:F0:8D:...". This is provided from the identity provider when setting up the relationship. + +**Required:** if PACTFLOW_SAML_IDP_METADATA_URL is not set
+**More information:** https://github.com/omniauth/omniauth-saml#options
+ +### PACTFLOW_SAML_IDP_ID_ATTRIBUTE + +The name of the SAML response attribute that uniquely and permanently identifies a user for the IDP. + +**Required:** true
+ +### PACTFLOW_SAML_EMAIL_ATTRIBUTE + +The name of the SAML response attribute that contains the email address. + +**Required:** true
+ +### PACTFLOW_SAML_NAME_ATTRIBUTE + +The name of the SAML response attribute that contains the full name. + +**Required:** true
+ +### PACTFLOW_SAML_FIRST_NAME_ATTRIBUTE + +The name of the SAML response attribute that contains the first name. + +**Required:** false
+ +### PACTFLOW_SAML_LAST_NAME_ATTRIBUTE + +The name of the SAML response attribute that contains the last name. + +**Required:** false
+ +### PACTFLOW_SAML_IDP_METADATA_URL + +The URL of the IDP's metadata endpoint. If this is set, then the PACTFLOW_SAML_IDP_SSO_TARGET_URL and PACTFLOW_SAML_IDP_CERT_FINGERPRINT can be skipped. + +**Required:** false
+**More information:** https://github.com/omniauth/omniauth-saml#idp-metadata
+ +### PACTFLOW_SAML_NAME_IDENTIFIER_FORMAT + +Used during SP-initiated SSO. Describes the format of the username required by this application. + +**Required:** false
+**Default:** `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`
+**Allowed values:** `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`, `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`
+ +### PACTFLOW_SAML_ALLOWED_CLOCK_DRIFT + +To allow for a small amount of clock drift between PactFlow and the Identity Provider, the allowed clock drift may be specified. Its value must be given in a number (and/or fraction) of seconds. The value is added to the current time at which the response is validated, before it is tested against the NotBefore assertion. + +**Required:** false
+**Default:** `0`
+ +## Demo authentication + +
+ + + +### PACTFLOW_DEMO_AUTH_ENABLED + +Whether or not to enable authentication for demo users. For demonstration purposes only - not to be set to `true` for production use. + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +## Encryption + +
+ + + +### PACTFLOW_MASTER_ENCRYPTION_KEY + +A randomly generated string which will be the master key for encrypting secrets and API tokens. Renamed from `PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY`. + +Do not change or lose the value of this key. All encrypted data (secrets and API keys) will be unretrievable if this key is lost. Rotation is not currently supported but will be added in a future release. + +To generate an appropriate value, run the following on Linux/Mac: + +``` +env LC_CTYPE=C tr -dc '_A-Z-a-z-0-9!#$%&*+-\\.^_|~' < /dev/urandom | fold -w 32 | head -n 1 +``` + +**Required:** true
+**Example:** `eLM5xPxPu9ftDhA34ZUw2ry2okpMnOPCrA-twxLBUUk`
+ +## Secrets + +
+ + + +### PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY + +Deprecated in favour of `PACTFLOW_MASTER_ENCRYPTION_KEY`. If you have a previous installation of PactFlow with `PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY` set, please rename it to `PACTFLOW_MASTER_ENCRYPTION_KEY`. + +**Required:** false
+ +## Content Security + +
+ + + +### PACTFLOW_CSP_ALLOWED_SOURCES + +Space separated list of allowed content sources that should be allowed in addition to the hosts configured in the identity provider settings (eg. `PACTFLOW_SAML_IDP_SSO_TARGET_URL`). This may be useful if you need additional assets on your instance of PactFlow. For example, if you need to support multiple redirects for SAML authentication, you need to add them here for PactFlow to generate the appropriate Content-Security-Policy to allow that to happen. + +**Required:** false
+**Example:** `https://my-intermediate-idp-host.com`
+ +## User administration + +
+ + + +### PACTFLOW_ADMIN_API_KEY + +The value of the X-Api-Key header required to make the HTTP call to provision the admin user. + +To generate an appropriate value, run the following on Linux/Mac: + +``` +env LC_CTYPE=C tr -dc '_A-Z-a-z-0-9!#$%&*+-\\.^_|~' < /dev/urandom | fold -w 32 | head -n 1 +``` + +**Required:** true
+**Allowed values:** `A-Za-z0-9!#$%&*+-^_``|~.`
+**Example:** `4wmplZfucVG-LdIHD9L`
+**More information:** https://tools.ietf.org/html/rfc7230#section-3.2.6
+ +## Domain + +
+ + + +### PACTFLOW_ALLOW_DANGEROUS_CONTRACT_MODIFICATION + +Whether or not to allow the pact content for an existing consumer version to be modified. It is strongly recommended that this is set to false, +as allowing modification makes the results of can-i-deploy unreliable. When this is set to false as recommended, each commit must publish pacts +with a unique version number. + +**Supported versions:** From v1.14.0
+**Required:** false
+**Default:** For new installations of v1.14.0 and later, this defaults to `false`.
+**Allowed values:** `true`, `false`
+**More information:** https://docs.pact.io/versioning
+ +### PACTFLOW_USE_FIRST_TAG_AS_BRANCH + +When the value is `true`, the first tag applied to a version (within 10 seconds) +will be used to populate the `branch` property of the version. + +This is to assist in the migration from using tags to track branches to using the branches feature. + +**Required:** false
+**Default:** `true`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_CREATE_DEPLOYED_VERSIONS_FOR_TAGS + +When the value is `true` and a tag is created, if there is an environment with the name of the newly created tag, a deployed version is +also created for the pacticipant version. + +This is to assist in the migration from using tags to track deployments to using the deployed and released versions feature. + +**Supported versions:** From v1.14.0
+**Required:** false
+**Default:** `true`
+**Allowed values:** `true`, `false`
+**More information:** https://docs.pact.io/pact_broker/recording_deployments_and_releases/
+ +## Badges + +
+ + + +### PACTFLOW_SHIELDS_IO_BASE_URL + +The URL of the free service that is used to generate the build badges. Note that the badge files are served via a redirect in the browser, so there is no request made from the PactFlow application to the shields server. + +**Required:** false
+**Default:** `https://img.shields.io`
+**More information:** https://shields.io
+ +## Resources + +
+ + + +### PACTFLOW_BASE_URL + +The base url, including HTTP scheme and any application context path, at which the PactFlow application will be publicly +accessible. It should not include a trailing slash. If there are multiple interfaces on which the application will be addressed, +list all the base URLs separated by spaces. + + +**Required:** true
+**Example:** `https://pactflow.mycompany.com https://pactflow.internal.mycompany.com`
+ +### PACTFLOW_HTTP_PORT + +The HTTP port on which the PactFlow application will be exposed on the Docker container. Must be greater than 1024. + +**Required:** false
+**Default:** `9292`
+ +### PACTFLOW_SESSION_LENGTH + +The number of seconds after which the user needs to re-authenticate with the IDP. Default is 1 week. + +**Required:** false
+**Default:** `604800`
+ +### PACTFLOW_SESSION_INACTIVITY_TIMEOUT + +The number of seconds of inactivity after which the user needs to re-authenticate with the IDP. By default, this will be set to the value of the `PACTFLOW_SESSION_LENGTH`, effectively disabling the feature, unless a value is specified by the user. + +**Required:** false
+**Default:** `604800`
+ +### PACTFLOW_COOKIE_SECRET + +The secret used to encrypt the rack.session cookie. +To generate an appropriate value, run the following on Linux/Mac: + +``` +env LC_ALL=C tr -dc '_A-Z-a-z-0-9!#$%&*+-\\.^_|~' < /dev/urandom | fold -w 64 | head -n 1 +``` + +**Required:** true
+**Example:** `X-sbeCpAUgO-8FRtKxYrVhgZ2hIJhPuzCh_89PypYrI`
+ +### PACTFLOW_OLD_COOKIE_SECRET + +The previous secret - used when rotating the rack.session cookie secret. + +**Required:** false
+ +### PACTFLOW_REQUIRE_HTTPS + +When set to `true`, the header `Strict-Transport-Security: max-age=31536000 ; includeSubDomains` is added to ensure connections are made over HTTPS, and the `PACTFLOW_BASE_URL` is validated to ensure it starts with https. + +This value should never be set to false in a production environment. It should only ever be set to false for local testing or demonstration purposes where an SSL certificate is not available. + + +**Required:** false
+**Default:** `true`
+**Allowed values:** `true`, `false`
+ +### SSL_CERT_FILE + +The PEM certificate file to use if the webhooks have to connect to servers that use self signed certificates. + +**Required:** false
+ +### SSL_CERT_DIR + +The PEM certificate directory to use if the webhooks have to connect to servers that use self signed certificates. + +**Required:** false
+ +### http_proxy + +HTTP proxy used when making outgoing HTTP requests + +**Required:** false
+ +### https_proxy + +HTTPS proxy used when making outgoing HTTP requests + +**Required:** false
+ +### no_proxy + +The hosts for which to not use a proxy + +**Required:** false
+ +### PACTFLOW_USE_HAL_BROWSER + +Whether or not to enable the embedded HAL Browser. + +**Required:** false
+**Default:** `true`
+**Allowed values:** `true`, `false`
+**More information:** https://github.com/mikekelly/hal-browser
+ +## Miscellaneous + +
+ + + +### TZ + +The timezone in which to display dates for server side rendered pages. + +**Required:** true
+**More information:** [Valid timezones](/docs/on-premises-2x/environment-variables/timezones)
+ +## API Tokens + +
+ + + +### PACTFLOW_API_TOKEN_AUTH_ENABLED + +Whether or not to enable the inbuilt PactFlow API tokens used for bearer authentication. Used to disable API tokens if an external Identify Provider is configured for API authentication. + +**Required:** false
+**Default:** `true`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_API_TOKEN_ENCRYPTION_ENABLED + +Enables encryption of API token values in the database. Requires `PACTFLOW_API_TOKEN_IV` and `PACTFLOW_MASTER_ENCRYPTION_KEY` to also be set. + +**Required:** false
+ +### PACTFLOW_API_TOKEN_IV + +If `PACTFLOW_API_TOKEN_ENCRYPTION_ENABLED` is set to `true`, then this value must contain a base 64 encoded string of random 16 bytes for the +encryption initialization vector. + +To generate an appropriate value, run the following on Linux/Mac: + +``` +head < /dev/random -c 16 | base64 +``` + +**Required:** if `PACTFLOW_API_TOKEN_ENCRYPTION_ENABLED` is set to `true`
+**Example:** `JUVDdnRzLXZyWHA7UF93RAo=`
+ +## User Interface + +
+ + + +### PACTFLOW_CLARITY_DISABLED + +Disables the new user interface introduced in version 2.0.0. When this environment variable is set, the legacy interface becomes the default and users cannot switch to the new UI. + +**Required:** false
+**Default:** unset
+**Allowed values:** `true`
\ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/environment-variables/1.14-beta.md b/website/docs/docs/on-premises-2x/environment-variables/1.14-beta.md new file mode 100644 index 00000000..d8ae64d4 --- /dev/null +++ b/website/docs/docs/on-premises-2x/environment-variables/1.14-beta.md @@ -0,0 +1,259 @@ +# PactFlow Environment Variables - 1.14 beta features + +This page contains documentation for the usage of the JWT and OAuth2 features that are in beta release in PactFlow 1.14 + +## Test JWT bearer authentication + +
+These settings can be configured in a YAML file, as per this example. + +```yaml +test_jwt_bearer_token_auth_enabled: true +test_jwt_bearer_token: + iss: https://idp + exp_leeway: 60 + jwks_url: https://idp/jwks + aud: some-aud + auth_config_handler: auth_ext_script.rb + claim_mappings: + idp_id: SomeUniqueIdentifier + email: EmailAddress + name: DisplayName + first_name: FirstName + last_name: LastName + ``` + + +### PACTFLOW_TEST_JWT_BEARER_TOKEN_AUTH_ENABLED + +Whether or not to enable JWT bearer token authentication for testing purposes. This is not yet ready for production use. + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_TEST_JWT_BEARER_TOKEN__JWKS_URL + +The endpoint from which the JSON web key set can be retrieved to decode and verify the JWT used as the bearer token. + +**Required:** false
+ +### PACTFLOW_TEST_JWT_BEARER_TOKEN__AUD + +The expected token audience ("aud") of the JWT. + +**Required:** false
+ +### PACTFLOW_TEST_JWT_BEARER_TOKEN__ISS + +The expected token issuer ("iss") of the JWT. + +**Required:** false
+ +### PACTFLOW_TEST_JWT_BEARER_TOKEN__EXP_LEEWAY + +The number of seconds of leeway to allow when verifying the expiration of the JWT, to allow for click drift between Pactlow and the Identity Provider. + +**Required:** false
+**Default:** `0`
+ +### PACTFLOW_TEST_JWT_BEARER_TOKEN__AUTH_CONFIG_HANDLER + +The name of a Ruby script which will parse the decoded JWT and extract the roles and teams associated with the user. The script must be mounted into the PactFlow Docker container in the directory `/home/pactflow/extensions`. + +**Required:** false
+ +### PACTFLOW_TEST_JWT\_\_CLAIM_MAPPINGS__{KEY} + +This setting maps the IDP's claims in the JWT to the required PactFlow user attributes. This setting is best configured in the YAML file as a map. +At least one of the keys must be called `sub` or `idp_id`. This will be used by PactFlow to uniquely identify the user from the Identify Provider. +The other recommended keys are `name`, `email`, `first_name` and `last_name`. + +eg. + +```yaml +test_jwt_bearer_token: + # other configurations here ... + claim_mappings: + idp_id: "SomeUniqueIdentifier" + name: "Name" + email: "Email" + first_name: "FirstName" + last_name: "LastName" +``` + +When setting the claim mappings using environment variables, the key name must be uppercased and prefixed by `PACTFLOW_TEST_JWT__CLAIM_MAPPINGS__` eg. `PACTFLOW_TEST_JWT__CLAIM_MAPPINGS__EMAIL=Email`. This will be mapped to a lower case `{ "email": "Email" }` internally. + +**Required:** false
+ +
+ +## Test OAuth2 authentication + +
+These settings can be configured in a YAML file, as per this example. + +```yaml +test_oauth2_auth_enabled: true +test_oauth2: + client_id: "..." + client_secret: "..." + idp_url: "https://idp" + authorize_url: "https://idp/authorize" + token_url: "https://idp/token" + jwks_url: "https://idp/jwks" + token_issuer: "https://idp" + token_audience: "..." + token_exp_leeway: 60 + auth_config_handler: "auth_ext_script.rb" + custom_authorize_params: + resource: "SomeResource" + claim_mappings: + idp_id: "SomeUniqueIdentifier" + email: "Email" + name: "DisplayName" + first_name: "FirstName" + last_name: "LastName" +``` + + +### PACTFLOW_TEST_OAUTH2_AUTH_ENABLED + +Whether or not to enable OAuth2 authentication for testing purposes. This is not yet ready for production use. + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_TEST_OAUTH2__CLIENT_ID + +The unique identier by which the PactFlow application is known to the identity provider. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__CLIENT_SECRET + +The client secret which the PactFlow application shares with the identity provider. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__IDP_URL + +The identity provider's URL. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__AUTHORIZE_URL + +The authorize endpoint of the OAuth2 provider. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__TOKEN_URL + +The endpoint at which PactFlow can retrieve the JWT containing the user's information. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__JWKS_URL + +The endpoint from which the JSON web key set can be retrieved to decode and verify the JWT returned by the token endpoint. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__TOKEN_ISSUER + +The expected token issuer ("iss") of the JWT. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__TOKEN_AUDIENCE + +The expected token audience ("aud") of the JWT. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2__TOKEN_EXP_LEEWAY + +The number of seconds of leeway to allow when verifying the expiration of the JWT, to allow for click drift between Pactlow and the Identity Provider. + +**Required:** false
+**Default:** `0`
+ +### PACTFLOW_TEST_OAUTH2__AUTH_CONFIG_HANDLER + +The name of a Ruby script which will parse the decoded JWT and extract the roles and teams associated with the user. The script must be mounted into the PactFlow Docker container in the directory `/home/pactflow/extensions`. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2\_\_CUSTOM_AUTHORIZE_PARAMS__{KEY} + +Allows custom authorize parameters to be set. These will be sent to the IDP in the request phase along with the default authorize parameters. + +eg. + +```yaml +test_oauth2: + custom_authorize_params: + resource: "SomeResource" +``` + +When setting the custom authorize params using environment variables, the key name must be uppercased and prefixed by `PACTFLOW_TEST_OAUTH2__CUSTOM_AUTHORIZE_PARAMS__` +eg. `PACTFLOW_TEST_OAUTH2__CLAIM_MAPPINGS__RESOURCE=SomeResource`. This will be mapped to a lower case `{ "resource": "SomeResource" }` internally. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2\_\_CUSTOM_TOKEN_PARAMS__{KEY} + +Allows custom token parameters to be set. These will be sent to the token endpoint along with the default token parameters. + +eg. + +```yaml +test_oauth2: + custom_token_params: + resource: "SomeResource" +``` + +When setting the custom token params using environment variables, the key name must be uppercased and prefixed by `PACTFLOW_TEST_OAUTH2__CUSTOM_TOKEN_PARAMS__` +eg. `PACTFLOW_TEST_OAUTH2__CUSTOM_TOKEN_PARAMS__RESOURCE=SomeResource`. This will be mapped to a lower case `{ "resource": "SomeResource" }` internally. + +**Required:** false
+ +### PACTFLOW_TEST_OAUTH2\_\_CLAIM_MAPPINGS__{KEY} + +This setting maps the IDP's claims in the JWT to the required PactFlow user attributes. This setting is best configured in the YAML file as a map. +At least one of the keys must be called `sub` or `idp_id`. This will be used by PactFlow to uniquely identify the user from the Identify Provider. +The other recommended keys are `name`, `email`, `first_name` and `last_name`. + +eg. + +```yaml +test_oauth2: + # other configurations here ... + claim_mappings: + idp_id: "SomeUniqueIdentifier" + name: "Name" + email: "Email" + first_name: "FirstName" + last_name: "LastName" +``` + +When setting the claim mappings using environment variables, the key name must be uppercased and prefixed by `PACTFLOW_TEST_OAUTH2__CLAIM_MAPPINGS__` +eg. `PACTFLOW_TEST_OAUTH2__CLAIM_MAPPINGS__EMAIL=Email`. This will be mapped to a lower case `{ "email": "Email" }` internally. + +**Required:** false
+ +
+ +## API Tokens + +
+ + +### PACTFLOW_API_TOKENS__ENABLED + +Whether or not to enable the inbuilt PactFlow API tokens used for bearer authentication. Used to disable API tokens if an external Identify Provider is configured for API authentication. + +**Required:** false
+**Allowed values:** `true`, `false`
diff --git a/website/docs/docs/on-premises-2x/environment-variables/jwt.md b/website/docs/docs/on-premises-2x/environment-variables/jwt.md new file mode 100644 index 00000000..dbdeffac --- /dev/null +++ b/website/docs/docs/on-premises-2x/environment-variables/jwt.md @@ -0,0 +1,109 @@ +# Environment Variables - JWT + + + + + +## JWT bearer authentication + +
+These settings can be configured in a YAML file, as per this example. + +```yaml +jwt_bearer_token_auth_enabled: true +jwt_bearer_token: + issuer: https://idp + audience: some-aud + expiry_leeway: 60 + jwks_url: https://idp/jwks + auth_config_handler: auth_ext_script.rb + claim_mappings: + idp_id: SomeUniqueIdentifier + email: EmailAddress + name: DisplayName + first_name: FirstName + last_name: LastName + ``` + + +### PACTFLOW_JWT_BEARER_TOKEN_AUTH_ENABLED + +Whether or not to enable JWT bearer token authentication. + +**Supported versions:** From v1.16.0
+**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_JWT_BEARER_TOKEN\_\_JWKS_URL + +The endpoint from which the JSON web key set can be retrieved to decode and verify the JWT used as the bearer token. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_JWT_BEARER_TOKEN\_\_AUDIENCE + +The expected token audience ("aud") of the JWT. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_JWT_BEARER_TOKEN\_\_ISSUER + +The expected token issuer ("iss") of the JWT. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_JWT_BEARER_TOKEN\_\_EXPIRY_LEEWAY + +The number of seconds of leeway to allow when verifying the expiration of the JWT, to allow for click drift between Pactlow and the Identity Provider. + +**Supported versions:** From v1.16.0
+**Required:** false
+**Default:** `0`
+ +### PACTFLOW_JWT_BEARER_TOKEN\_\_AUTH_CONFIG_HANDLER + +The name of a Ruby script which will parse the decoded JWT and extract the roles and teams associated with the user. The script must be mounted into the PactFlow Docker container in the directory `/home/pactflow/extensions`. + +**Supported versions:** From v1.16.0
+**Required:** false
+ +### PACTFLOW_JWT\_\_CLAIM_MAPPINGS\_\_{KEY} + +This setting maps the IDP's claims in the JWT to the required PactFlow user attributes. This setting is best configured in the YAML file as a map. +At least one of the keys must be called `sub` or `idp_id`. This will be used by PactFlow to uniquely identify the user from the Identify Provider. +The other recommended keys are `name`, `email`, `first_name` and `last_name`. + +eg. + +```yaml +jwt_bearer_token_auth_enabled: true +jwt_bearer_token: + # other configurations here ... + claim_mappings: + idp_id: "SomeUniqueIdentifier" + name: "Name" + email: "Email" + first_name: "FirstName" + last_name: "LastName" +``` + +When setting the claim mappings using environment variables, a separate environment variable must be used for each claim mapping. +The key name must be uppercased and prefixed by `PACTFLOW_JWT__CLAIM_MAPPINGS__`. + +eg. + +```shell +PACTFLOW_JWT__CLAIM_MAPPINGS__IDP_ID="SomeUniqueIdentifier" +PACTFLOW_JWT__CLAIM_MAPPINGS__NAME="Name" +PACTFLOW_JWT__CLAIM_MAPPINGS__EMAIL="Email" +PACTFLOW_JWT__CLAIM_MAPPINGS__FIRST_NAME="FirstName" +PACTFLOW_JWT__CLAIM_MAPPINGS__LAST_NAME="LastName" +```` + +**Supported versions:** From v1.16.0
+**Required:** false
+ diff --git a/website/docs/docs/on-premises-2x/environment-variables/oauth2.md b/website/docs/docs/on-premises-2x/environment-variables/oauth2.md new file mode 100644 index 00000000..7d9de85d --- /dev/null +++ b/website/docs/docs/on-premises-2x/environment-variables/oauth2.md @@ -0,0 +1,193 @@ +# Environment Variables - OAuth2 + + + + + +## OAuth2 authentication + +
+These settings can be configured in a YAML file, as per this example. + +```yaml +oauth2_auth_enabled: true +oauth2: + client_id: "..." + client_secret: "..." + idp_name: "Some IDP" + idp_url: "https://idp" + authorize_url: "https://idp/authorize" + token_url: "https://idp/token" + jwks_url: "https://idp/jwks" + token_issuer: "https://idp" + token_audience: "..." + token_expiry_leeway: 60 + auth_config_handler: "auth_ext_script.rb" + custom_authorize_params: + resource: "SomeResource" + claim_mappings: + idp_id: "SomeUniqueIdentifier" + email: "Email" + name: "DisplayName" + first_name: "FirstName" + last_name: "LastName" +``` + + +### PACTFLOW_OAUTH2_AUTH_ENABLED + +Whether or not to enable OAuth2 authentication. + +**Supported versions:** From v1.16.0
+**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +### PACTFLOW_OAUTH2\_\_CLIENT_ID + +The unique identier by which the PactFlow application is known to the identity provider. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_OAUTH2\_\_CLIENT_SECRET + +The client secret which the PactFlow application shares with the identity provider. + +**Supported versions:** From v1.16.0
+**Required:** false
+ +### PACTFLOW_OAUTH2\_\_IDP_NAME + +The identity provider's name. This value will appear on the login button. + +**Supported versions:** From v1.16.0
+**Required:** false
+ +### PACTFLOW_OAUTH2\_\_IDP_URL + +The identity provider's URL. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_OAUTH2\_\_AUTHORIZE_URL + +The authorize endpoint of the OAuth2 provider. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_OAUTH2\_\_TOKEN_URL + +The endpoint at which PactFlow can retrieve the JWT containing the user's information. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_OAUTH2\_\_JWKS_URL + +The endpoint from which the JSON web key set can be retrieved to decode and verify the JWT returned by the token endpoint. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_OAUTH2\_\_TOKEN_ISSUER + +The expected token issuer ("iss") of the JWT. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_OAUTH2\_\_TOKEN_AUDIENCE + +The expected token audience ("aud") of the JWT. + +**Supported versions:** From v1.16.0
+**Required:** true
+ +### PACTFLOW_OAUTH2\_\_TOKEN_EXPIRY_LEEWAY + +The number of seconds of leeway to allow when verifying the expiration of the JWT, to allow for click drift between Pactlow and the Identity Provider. + +**Supported versions:** From v1.16.0
+**Required:** false
+**Default:** `0`
+ +### PACTFLOW_OAUTH2\_\_AUTH_CONFIG_HANDLER + +The name of a Ruby script which will parse the decoded JWT and extract the roles and teams associated with the user. The script must be mounted into the PactFlow Docker container in the directory `/home/pactflow/extensions`. + +**Supported versions:** From v1.16.0
+**Required:** false
+ +### PACTFLOW_OAUTH2\_\_CUSTOM_AUTHORIZE_PARAMS\_\_{KEY} + +Allows custom authorize parameters to be set. These will be sent to the IDP in the request phase along with the default authorize parameters. + +eg. + +```yaml +oauth2: + custom_authorize_params: + resource: "SomeResource" +``` + +When setting the custom authorize params using environment variables, the key name must be uppercased and prefixed by `PACTFLOW_OAUTH2__CUSTOM_AUTHORIZE_PARAMS__` +eg. `PACTFLOW_OAUTH2__CUSTOM_AUTHORIZE_PARAMS__RESOURCE=SomeResource`. This will be mapped to a lower case `{ "resource": "SomeResource" }` internally. + +**Supported versions:** From v1.16.0
+**Required:** false
+ +### PACTFLOW_OAUTH2\_\_CUSTOM_TOKEN_PARAMS\_\_{KEY} + +Allows custom token parameters to be set. These will be sent to the token endpoint along with the default token parameters. + +eg. + +```yaml +oauth2: + custom_token_params: + resource: "SomeResource" +``` + +When setting the custom token params using environment variables, the key name must be uppercased and prefixed by `PACTFLOW_OAUTH2__CUSTOM_TOKEN_PARAMS__` +eg. `PACTFLOW_OAUTH2__CUSTOM_TOKEN_PARAMS__RESOURCE=SomeResource`. This will be mapped to a lower case `{ "resource": "SomeResource" }` internally. + +**Supported versions:** From v1.16.0
+**Required:** false
+ +### PACTFLOW_OAUTH2\_\_CLAIM_MAPPINGS\_\_{KEY} + +This setting maps the IDP's claims in the JWT to the required PactFlow user attributes. This setting is best configured in the YAML file as a map. +At least one of the keys must be called `sub` or `idp_id`. This will be used by PactFlow to uniquely identify the user from the Identify Provider. +The other recommended keys are `name`, `email`, `first_name` and `last_name`. + +eg. + +```yaml +oauth2: + # other configurations here ... + claim_mappings: + idp_id: "SomeUniqueIdentifier" + name: "Name" + email: "Email" + first_name: "FirstName" + last_name: "LastName" +``` + +When setting the claim mappings using environment variables, a separate environment variable must be used for each claim mapping. +The key name must be uppercased and prefixed by `PACTFLOW_OAUTH2__CLAIM_MAPPINGS__`. + +eg. + +```shell +PACTFLOW_OAUTH2__CLAIM_MAPPINGS__IDP_ID="SomeUniqueIdentifier" +PACTFLOW_OAUTH2__CLAIM_MAPPINGS__NAME="Name" +PACTFLOW_OAUTH2__CLAIM_MAPPINGS__EMAIL="Email" +PACTFLOW_OAUTH2__CLAIM_MAPPINGS__FIRST_NAME="FirstName" +PACTFLOW_OAUTH2__CLAIM_MAPPINGS__LAST_NAME="LastName" +```` + +**Supported versions:** From v1.16.0
+**Required:** false
diff --git a/website/docs/docs/on-premises-2x/environment-variables/templates.md b/website/docs/docs/on-premises-2x/environment-variables/templates.md new file mode 100644 index 00000000..333de9c7 --- /dev/null +++ b/website/docs/docs/on-premises-2x/environment-variables/templates.md @@ -0,0 +1,75 @@ +--- +title: Configuration file templates +--- + +## Required environment variables + +```yml +- name: "PACTFLOW_DATABASE_URL" + value: "postgres://username:password@host:port/database" +- name: "PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY" + value: "" +- name: "PACTFLOW_COOKIE_SECRET" + value: "" +- name: "TZ" + value: "" +- name: "PACTFLOW_BASE_URL" + value: "" + +# SAML +- name: "PACTFLOW_SAML_IDP_NAME" + value: "" +- name: "PACTFLOW_SAML_ISSUER" + value: "" +- name: "PACTFLOW_SAML_NAME_IDENTIFIER_FORMAT" + value: "" +- name: "PACTFLOW_SAML_EMAIL_ATTRIBUTE" + value: "" +- name: "PACTFLOW_SAML_NAME_ATTRIBUTE" + value: "" +- name: "PACTFLOW_SAML_FIRST_NAME_ATTRIBUTE" + value: "" +- name: "PACTFLOW_SAML_LAST_NAME_ATTRIBUTE" + value: "" +- name: "PACTFLOW_SAML_IDP_SSO_TARGET_URL" + value: "" +- name: "PACTFLOW_SAML_IDP_CERT_FINGERPRINT" + value: "" +- name: "PACTFLOW_SAML_IDP_ID_ATTRIBUTE" + value: "" +``` + +## Recommended environment variables + +```yml +- name: "PACTFLOW_WEBHOOK_HOST_WHITELIST" + value: "" +``` + +## SAML +### Azure Active Directory + +```yml +- name: "PACTFLOW_SAML_ISSUER" + value: "eg. https://pactflow.mycompany.com" +- name: "PACTFLOW_SAML_IDP_NAME" + value: "eg. Azure AD" +- name: "PACTFLOW_SAML_IDP_SSO_TARGET_URL" + value: "eg. https://login.microsoftonline.com/abcd/saml2" +- name: "PACTFLOW_SAML_IDP_CERT_FINGERPRINT" + value: "eg. E97D948158F893A93827A0A4D70701A38AB1A499" +- name: "PACTFLOW_SAML_IDP_ENTITY_ID" + value: "eg. https://sts.windows.net/abcd/" +- name: "PACTFLOW_SAML_NAME_IDENTIFIER_FORMAT" + value: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" +- name: "PACTFLOW_SAML_IDP_ID_ATTRIBUTE" + value: "http://schemas.microsoft.com/identity/claims/objectidentifier" +- name: "PACTFLOW_SAML_EMAIL_ATTRIBUTE" + value: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" +- name: "PACTFLOW_SAML_NAME_ATTRIBUTE" + value: "http://schemas.microsoft.com/identity/claims/displayname" +- name: "PACTFLOW_SAML_FIRST_NAME_ATTRIBUTE" + value: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" +- name: "PACTFLOW_SAML_LAST_NAME_ATTRIBUTE" + value: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" +``` diff --git a/website/docs/docs/on-premises-2x/environment-variables/timezones.md b/website/docs/docs/on-premises-2x/environment-variables/timezones.md new file mode 100644 index 00000000..9a039699 --- /dev/null +++ b/website/docs/docs/on-premises-2x/environment-variables/timezones.md @@ -0,0 +1,601 @@ +--- +title: Timezones +--- + +These are the valid values for the [TZ environment variable](/docs/on-premises-2x/environment-variables#tz). + +* Africa/Abidjan +* Africa/Accra +* Africa/Addis_Ababa +* Africa/Algiers +* Africa/Asmara +* Africa/Asmera +* Africa/Bamako +* Africa/Bangui +* Africa/Banjul +* Africa/Bissau +* Africa/Blantyre +* Africa/Brazzaville +* Africa/Bujumbura +* Africa/Cairo +* Africa/Casablanca +* Africa/Ceuta +* Africa/Conakry +* Africa/Dakar +* Africa/Dar_es_Salaam +* Africa/Djibouti +* Africa/Douala +* Africa/El_Aaiun +* Africa/Freetown +* Africa/Gaborone +* Africa/Harare +* Africa/Johannesburg +* Africa/Juba +* Africa/Kampala +* Africa/Khartoum +* Africa/Kigali +* Africa/Kinshasa +* Africa/Lagos +* Africa/Libreville +* Africa/Lome +* Africa/Luanda +* Africa/Lubumbashi +* Africa/Lusaka +* Africa/Malabo +* Africa/Maputo +* Africa/Maseru +* Africa/Mbabane +* Africa/Mogadishu +* Africa/Monrovia +* Africa/Nairobi +* Africa/Ndjamena +* Africa/Niamey +* Africa/Nouakchott +* Africa/Ouagadougou +* Africa/Porto-Novo +* Africa/Sao_Tome +* Africa/Timbuktu +* Africa/Tripoli +* Africa/Tunis +* Africa/Windhoek +* America/Adak +* America/Anchorage +* America/Anguilla +* America/Antigua +* America/Araguaina +* America/Argentina/Buenos_Aires +* America/Argentina/Catamarca +* America/Argentina/ComodRivadavia +* America/Argentina/Cordoba +* America/Argentina/Jujuy +* America/Argentina/La_Rioja +* America/Argentina/Mendoza +* America/Argentina/Rio_Gallegos +* America/Argentina/Salta +* America/Argentina/San_Juan +* America/Argentina/San_Luis +* America/Argentina/Tucuman +* America/Argentina/Ushuaia +* America/Aruba +* America/Asuncion +* America/Atikokan +* America/Atka +* America/Bahia +* America/Bahia_Banderas +* America/Barbados +* America/Belem +* America/Belize +* America/Blanc-Sablon +* America/Boa_Vista +* America/Bogota +* America/Boise +* America/Buenos_Aires +* America/Cambridge_Bay +* America/Campo_Grande +* America/Cancun +* America/Caracas +* America/Catamarca +* America/Cayenne +* America/Cayman +* America/Chicago +* America/Chihuahua +* America/Coral_Harbour +* America/Cordoba +* America/Costa_Rica +* America/Creston +* America/Cuiaba +* America/Curacao +* America/Danmarkshavn +* America/Dawson +* America/Dawson_Creek +* America/Denver +* America/Detroit +* America/Dominica +* America/Edmonton +* America/Eirunepe +* America/El_Salvador +* America/Ensenada +* America/Fort_Nelson +* America/Fort_Wayne +* America/Fortaleza +* America/Glace_Bay +* America/Godthab +* America/Goose_Bay +* America/Grand_Turk +* America/Grenada +* America/Guadeloupe +* America/Guatemala +* America/Guayaquil +* America/Guyana +* America/Halifax +* America/Havana +* America/Hermosillo +* America/Indiana/Indianapolis +* America/Indiana/Knox +* America/Indiana/Marengo +* America/Indiana/Petersburg +* America/Indiana/Tell_City +* America/Indiana/Vevay +* America/Indiana/Vincennes +* America/Indiana/Winamac +* America/Indianapolis +* America/Inuvik +* America/Iqaluit +* America/Jamaica +* America/Jujuy +* America/Juneau +* America/Kentucky/Louisville +* America/Kentucky/Monticello +* America/Knox_IN +* America/Kralendijk +* America/La_Paz +* America/Lima +* America/Los_Angeles +* America/Louisville +* America/Lower_Princes +* America/Maceio +* America/Managua +* America/Manaus +* America/Marigot +* America/Martinique +* America/Matamoros +* America/Mazatlan +* America/Mendoza +* America/Menominee +* America/Merida +* America/Metlakatla +* America/Mexico_City +* America/Miquelon +* America/Moncton +* America/Monterrey +* America/Montevideo +* America/Montreal +* America/Montserrat +* America/Nassau +* America/New_York +* America/Nipigon +* America/Nome +* America/Noronha +* America/North_Dakota/Beulah +* America/North_Dakota/Center +* America/North_Dakota/New_Salem +* America/Nuuk +* America/Ojinaga +* America/Panama +* America/Pangnirtung +* America/Paramaribo +* America/Phoenix +* America/Port-au-Prince +* America/Port_of_Spain +* America/Porto_Acre +* America/Porto_Velho +* America/Puerto_Rico +* America/Punta_Arenas +* America/Rainy_River +* America/Rankin_Inlet +* America/Recife +* America/Regina +* America/Resolute +* America/Rio_Branco +* America/Rosario +* America/Santa_Isabel +* America/Santarem +* America/Santiago +* America/Santo_Domingo +* America/Sao_Paulo +* America/Scoresbysund +* America/Shiprock +* America/Sitka +* America/St_Barthelemy +* America/St_Johns +* America/St_Kitts +* America/St_Lucia +* America/St_Thomas +* America/St_Vincent +* America/Swift_Current +* America/Tegucigalpa +* America/Thule +* America/Thunder_Bay +* America/Tijuana +* America/Toronto +* America/Tortola +* America/Vancouver +* America/Virgin +* America/Whitehorse +* America/Winnipeg +* America/Yakutat +* America/Yellowknife +* Antarctica/Casey +* Antarctica/Davis +* Antarctica/DumontDUrville +* Antarctica/Macquarie +* Antarctica/Mawson +* Antarctica/McMurdo +* Antarctica/Palmer +* Antarctica/Rothera +* Antarctica/South_Pole +* Antarctica/Syowa +* Antarctica/Troll +* Antarctica/Vostok +* Arctic/Longyearbyen +* Asia/Aden +* Asia/Almaty +* Asia/Amman +* Asia/Anadyr +* Asia/Aqtau +* Asia/Aqtobe +* Asia/Ashgabat +* Asia/Ashkhabad +* Asia/Atyrau +* Asia/Baghdad +* Asia/Bahrain +* Asia/Baku +* Asia/Bangkok +* Asia/Barnaul +* Asia/Beirut +* Asia/Bishkek +* Asia/Brunei +* Asia/Calcutta +* Asia/Chita +* Asia/Choibalsan +* Asia/Chongqing +* Asia/Chungking +* Asia/Colombo +* Asia/Dacca +* Asia/Damascus +* Asia/Dhaka +* Asia/Dili +* Asia/Dubai +* Asia/Dushanbe +* Asia/Famagusta +* Asia/Gaza +* Asia/Harbin +* Asia/Hebron +* Asia/Ho_Chi_Minh +* Asia/Hong_Kong +* Asia/Hovd +* Asia/Irkutsk +* Asia/Istanbul +* Asia/Jakarta +* Asia/Jayapura +* Asia/Jerusalem +* Asia/Kabul +* Asia/Kamchatka +* Asia/Karachi +* Asia/Kashgar +* Asia/Kathmandu +* Asia/Katmandu +* Asia/Khandyga +* Asia/Kolkata +* Asia/Krasnoyarsk +* Asia/Kuala_Lumpur +* Asia/Kuching +* Asia/Kuwait +* Asia/Macao +* Asia/Macau +* Asia/Magadan +* Asia/Makassar +* Asia/Manila +* Asia/Muscat +* Asia/Nicosia +* Asia/Novokuznetsk +* Asia/Novosibirsk +* Asia/Omsk +* Asia/Oral +* Asia/Phnom_Penh +* Asia/Pontianak +* Asia/Pyongyang +* Asia/Qatar +* Asia/Qostanay +* Asia/Qyzylorda +* Asia/Rangoon +* Asia/Riyadh +* Asia/Saigon +* Asia/Sakhalin +* Asia/Samarkand +* Asia/Seoul +* Asia/Shanghai +* Asia/Singapore +* Asia/Srednekolymsk +* Asia/Taipei +* Asia/Tashkent +* Asia/Tbilisi +* Asia/Tehran +* Asia/Tel_Aviv +* Asia/Thimbu +* Asia/Thimphu +* Asia/Tokyo +* Asia/Tomsk +* Asia/Ujung_Pandang +* Asia/Ulaanbaatar +* Asia/Ulan_Bator +* Asia/Urumqi +* Asia/Ust-Nera +* Asia/Vientiane +* Asia/Vladivostok +* Asia/Yakutsk +* Asia/Yangon +* Asia/Yekaterinburg +* Asia/Yerevan +* Atlantic/Azores +* Atlantic/Bermuda +* Atlantic/Canary +* Atlantic/Cape_Verde +* Atlantic/Faeroe +* Atlantic/Faroe +* Atlantic/Jan_Mayen +* Atlantic/Madeira +* Atlantic/Reykjavik +* Atlantic/South_Georgia +* Atlantic/St_Helena +* Atlantic/Stanley +* Australia/ACT +* Australia/Adelaide +* Australia/Brisbane +* Australia/Broken_Hill +* Australia/Canberra +* Australia/Currie +* Australia/Darwin +* Australia/Eucla +* Australia/Hobart +* Australia/LHI +* Australia/Lindeman +* Australia/Lord_Howe +* Australia/Melbourne +* Australia/NSW +* Australia/North +* Australia/Perth +* Australia/Queensland +* Australia/South +* Australia/Sydney +* Australia/Tasmania +* Australia/Victoria +* Australia/West +* Australia/Yancowinna +* Brazil/Acre +* Brazil/DeNoronha +* Brazil/East +* Brazil/West +* CET +* CST6CDT +* Canada/Atlantic +* Canada/Central +* Canada/Eastern +* Canada/Mountain +* Canada/Newfoundland +* Canada/Pacific +* Canada/Saskatchewan +* Canada/Yukon +* Chile/Continental +* Chile/EasterIsland +* Cuba +* EET +* EST +* EST5EDT +* Egypt +* Eire +* Etc/GMT +* Etc/GMT+0 +* Etc/GMT+1 +* Etc/GMT+10 +* Etc/GMT+11 +* Etc/GMT+12 +* Etc/GMT+2 +* Etc/GMT+3 +* Etc/GMT+4 +* Etc/GMT+5 +* Etc/GMT+6 +* Etc/GMT+7 +* Etc/GMT+8 +* Etc/GMT+9 +* Etc/GMT-0 +* Etc/GMT-1 +* Etc/GMT-10 +* Etc/GMT-11 +* Etc/GMT-12 +* Etc/GMT-13 +* Etc/GMT-14 +* Etc/GMT-2 +* Etc/GMT-3 +* Etc/GMT-4 +* Etc/GMT-5 +* Etc/GMT-6 +* Etc/GMT-7 +* Etc/GMT-8 +* Etc/GMT-9 +* Etc/GMT0 +* Etc/Greenwich +* Etc/UCT +* Etc/UTC +* Etc/Universal +* Etc/Zulu +* Europe/Amsterdam +* Europe/Andorra +* Europe/Astrakhan +* Europe/Athens +* Europe/Belfast +* Europe/Belgrade +* Europe/Berlin +* Europe/Bratislava +* Europe/Brussels +* Europe/Bucharest +* Europe/Budapest +* Europe/Busingen +* Europe/Chisinau +* Europe/Copenhagen +* Europe/Dublin +* Europe/Gibraltar +* Europe/Guernsey +* Europe/Helsinki +* Europe/Isle_of_Man +* Europe/Istanbul +* Europe/Jersey +* Europe/Kaliningrad +* Europe/Kiev +* Europe/Kirov +* Europe/Lisbon +* Europe/Ljubljana +* Europe/London +* Europe/Luxembourg +* Europe/Madrid +* Europe/Malta +* Europe/Mariehamn +* Europe/Minsk +* Europe/Monaco +* Europe/Moscow +* Europe/Nicosia +* Europe/Oslo +* Europe/Paris +* Europe/Podgorica +* Europe/Prague +* Europe/Riga +* Europe/Rome +* Europe/Samara +* Europe/San_Marino +* Europe/Sarajevo +* Europe/Saratov +* Europe/Simferopol +* Europe/Skopje +* Europe/Sofia +* Europe/Stockholm +* Europe/Tallinn +* Europe/Tirane +* Europe/Tiraspol +* Europe/Ulyanovsk +* Europe/Uzhgorod +* Europe/Vaduz +* Europe/Vatican +* Europe/Vienna +* Europe/Vilnius +* Europe/Volgograd +* Europe/Warsaw +* Europe/Zagreb +* Europe/Zaporozhye +* Europe/Zurich +* Factory +* GB +* GB-Eire +* GMT +* GMT+0 +* GMT-0 +* GMT0 +* Greenwich +* HST +* Hongkong +* Iceland +* Indian/Antananarivo +* Indian/Chagos +* Indian/Christmas +* Indian/Cocos +* Indian/Comoro +* Indian/Kerguelen +* Indian/Mahe +* Indian/Maldives +* Indian/Mauritius +* Indian/Mayotte +* Indian/Reunion +* Iran +* Israel +* Jamaica +* Japan +* Kwajalein +* Libya +* MET +* MST +* MST7MDT +* Mexico/BajaNorte +* Mexico/BajaSur +* Mexico/General +* NZ +* NZ-CHAT +* Navajo +* PRC +* PST8PDT +* Pacific/Apia +* Pacific/Auckland +* Pacific/Bougainville +* Pacific/Chatham +* Pacific/Chuuk +* Pacific/Easter +* Pacific/Efate +* Pacific/Enderbury +* Pacific/Fakaofo +* Pacific/Fiji +* Pacific/Funafuti +* Pacific/Galapagos +* Pacific/Gambier +* Pacific/Guadalcanal +* Pacific/Guam +* Pacific/Honolulu +* Pacific/Johnston +* Pacific/Kiritimati +* Pacific/Kosrae +* Pacific/Kwajalein +* Pacific/Majuro +* Pacific/Marquesas +* Pacific/Midway +* Pacific/Nauru +* Pacific/Niue +* Pacific/Norfolk +* Pacific/Noumea +* Pacific/Pago_Pago +* Pacific/Palau +* Pacific/Pitcairn +* Pacific/Pohnpei +* Pacific/Ponape +* Pacific/Port_Moresby +* Pacific/Rarotonga +* Pacific/Saipan +* Pacific/Samoa +* Pacific/Tahiti +* Pacific/Tarawa +* Pacific/Tongatapu +* Pacific/Truk +* Pacific/Wake +* Pacific/Wallis +* Pacific/Yap +* Poland +* Portugal +* ROC +* ROK +* Singapore +* Turkey +* UCT +* US/Alaska +* US/Aleutian +* US/Arizona +* US/Central +* US/East-Indiana +* US/Eastern +* US/Hawaii +* US/Indiana-Starke +* US/Michigan +* US/Mountain +* US/Pacific +* US/Pacific-New +* US/Samoa +* UTC +* Universal +* W-SU +* WET +* Zulu \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/installation/checklist.md b/website/docs/docs/on-premises-2x/installation/checklist.md new file mode 100644 index 00000000..3c6f148e --- /dev/null +++ b/website/docs/docs/on-premises-2x/installation/checklist.md @@ -0,0 +1,43 @@ +--- +title: Installation checklist +--- + +## 1. PactFlow license file + +The PactFlow on-premises version requires a license file to run. You should have received this from us during the +on-boarding process. If not, please contact your Account Manager. + +## 2. Run Docker Compose example + +See the [Docker Compose example](/docs/on-premises-2x/docker-compose-example). + +## 3. Choose the domain name for your PactFlow On-Premises application + +eg. `https://pactflow.mycompany.com` + +You will need this for the next step. + +## 4. Configure identity provider + +Configure the PactFlow On-Premises application in your identity provider. See the [Azure Active Directory](/docs/on-premises-2x/authentication/saml#configuring-azure-active-directory) documentation. + +## 5. Deploy PactFlow On-Premises application stack + +* Configure the [PactFlow Docker image](/docs/on-premises-2x/docker-image-registry) to be pulled from Quay. +* Use the [environment variable templates](/docs/on-premises-2x/environment-variables/templates) to create the appropriate deployment configuration artifacts for the PactFlow Docker image (eg. Cloudformation template, Helm chart etc.) +* Ensure the [compute resources](/docs/on-premises-2x/system-requirements) have the appropriate specifications. +* Create a [PostgreSQL database](/docs/on-premises-2x/database) +* Setup a [Redis cache](/docs/on-premises-2x/redis) +* Ensure the [network](/docs/on-premises-2x/network-configuration) is configured appropriately. +* Ensure the [logs](/docs/on-premises-2x/logging) are forwarded to a log aggregation service. +* Make sure the [license file](/docs/on-premises-2x/license) is mounted into the running containers. +* Ensure you have [load tested](load-testing) the system and have confidence the system can handle your baseline load, and can scale with increased demand. + +## 6. Setup database cleaning + +Setup [database cleaning](/docs/on-premises-2x/maintenance/database) to ensure optimal PactFlow performance and reliability. + +:::warning this step is not optional +Failure to enable database cleaning is likely to result in a gradual decline in system performance and, eventually, query timeouts and system failure. +::: + diff --git a/website/docs/docs/on-premises-2x/installation/load-testing.md b/website/docs/docs/on-premises-2x/installation/load-testing.md new file mode 100644 index 00000000..3fcf7835 --- /dev/null +++ b/website/docs/docs/on-premises-2x/installation/load-testing.md @@ -0,0 +1,28 @@ +--- +title: Load Testing +--- + + +# Load testing + +Load testing is an important part of installation, it helps to give confidence that the system is setup and configured to scale with the needs of the organisation. + +It also helps us to identify the key scaling properties - e.g. is it CPU, I/O or network bound - in order to tune autoscaling, metrics and alarms. + +## Calculating base usage + +There is no easy answer on how many requests per second should the system be able to handle, but the simplest approach is to base it off the number of CI builds and releases you perform on your busiest day. + +If you can imagine a histogram of these builds with time as the x-axis, and number of builds on the y-axis, you can take the peak number and use that as your baseline "concurrent users" metric. + +A starting point of being able to handle 10 concurrent users (builds) is a good start, as each build will usually perform several API calls. + +It's worth pointing out that each real CI build will usually span multiple minutes, and only a fraction of the build time will be dedicated Pact and communicting with PactFlow directly. + +## Running a load test + +We have created a tool that you can use to run a load test on your platform. + +Using the metric from above, the load testing tool maps to a random scenario (which may perform multiple API calls to PactFlow), attempting to create a more realistic system load. + +You can download and run the tool from: https://github.com/pactflow/pactflow-load-test \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/installation/migrating-from-pact-broker.md b/website/docs/docs/on-premises-2x/installation/migrating-from-pact-broker.md new file mode 100644 index 00000000..a006ccf0 --- /dev/null +++ b/website/docs/docs/on-premises-2x/installation/migrating-from-pact-broker.md @@ -0,0 +1,41 @@ +--- +id: migrating +title: Migrating from Pact Broker +--- + +# Migrating from Pact Broker + +If you have previously used the open source Pact Broker with a PostgreSQL database it is possible to migrate that data to PactFlow, keeping everything and making it available in PactFlow. The migration process uses the existing Pact Broker database. Database migrations are then performed to add additional tables and data used for PactFlow features. + +:::note +Migration is only supported for a Pact Broker running a PostgreSQL database. +::: + +## Single Pact Broker instance + +Follow existing [set up documentation](/docs/on-premises-2x) for setting up your new PactFlow. When you reach the section regarding setting up a [Database](/docs/on-premises-2x/database) follow these steps to migrate instead of creating a new database: + +1. Re-use your existing Pact Broker environment variables, updating the names to read `PACTFLOW_*` instead of `PACT_BROKER_*`. A full list of the PactFlow environment variables can be found [here](/docs/on-premises-2x/environment-variables). + +:::tip + +It is crucial that all `PACT_BROKER_DATABASE_*` environment variables are renamed to `PACTFLOW_DATABASE_*` while their `values` remain the same. This is because your existing Pact Broker database will be used, and updated for use with PactFlow as part of the process. +::: + +2. If you previously set the environment variables `PACT_BROKER_AUTO_MIGRATE_DB` and `PACT_BROKER_AUTO_MIGRATE_DB_DATA` remove these and replace them with a new environment variable named `PACTFLOW_DATABASE_AUTO_MIGRATE`. Set its value to `true`. This environment variable will allow your existing database to be updated with the required structures and data to support PactFlow, and maintain any existing data. +You do not need to add the new variable if you did not previously set `PACT_BROKER_AUTO_MIGRATE_DB` and `PACT_BROKER_AUTO_MIGRATE_DB_DATA`. + +4. When the PactFlow instance starts up the migrations will run automatically. The migrations can be run manually instead if needed. See details [here](/docs/on-premises-2x/upgrading/database-migrations) + +## Multiple Pact Broker instances + +It is not currently possible to combine multiple Pact Broker databases into a single database for use with PactFlow. Instead one Pact Broker database can be used in the migration, and the others ran in parallel with the new PactFlow instance until sufficient data is transferred. The PactFlow instance must contain all production versions of all services used in the contract test before it can safely take over all 'can-i-deploy' checks. + +The recommended steps are as follows: + +1. Select one of the Pact Broker databases to update and use going forwards. +2. Follow instructions above to set up PactFlow using this database. +3. The Pact Broker instances that was used in the upgrade process and be decommissioned, as the database and its contents are now available in PactFlow. +4. Run the PactFlow instance and any other existing Pact Broker instances in parallel. Duplicate the pact publication and pact verification tasks in your pipeline. The duplicated task should use the new PactFlow instance details. In this way all new data can gradually added to PactFlow while ensuring `can-i-deploy` still has access to production versions of all services. +5. Continue to run PactFlow and Pact Brokers in parallel. Once the PactFlow instance contains all the `production` versions for all the services used in the contract tests the old Pact Broker instances can be safely decommissioned. This will allow PactFlow to be the sole source of data for 'can-i-deploy' +6. Clean up any code and API calls that were used to run PactFlow and existing Pact Brokers in parallel. The pact publication and pact verification steps in your pipeline that used the old Pact Brokers can be removed. diff --git a/website/docs/docs/on-premises-2x/license.md b/website/docs/docs/on-premises-2x/license.md new file mode 100644 index 00000000..97640294 --- /dev/null +++ b/website/docs/docs/on-premises-2x/license.md @@ -0,0 +1,66 @@ +--- +title: License file +--- + +The PactFlow on-premises version requires a license file to run. You should have received this from us during the +on-boarding process. If not, please contact your Account Manager. + +The license file needs to be mounted into the docker container at the `/home/pactflow-onprem.lic` path. This can +be done by either using a volume mount or building a new image with the license file in it. + +## Volume mounting the license file + +Refer to the docker documentation on using [volumes](https://docs.docker.com/storage/volumes/). + +For an example, you can use the docker CLI `-v` parameter to mount the license file (i.e. if the license file +is stored at `/opt/pactflow/pactflow-onprem.lic` on your server, then `-v /opt/pactflow/pactflow-onprem.lic/pactflow-onprem.lic:/home/pactflow-onprem.lic` will mount it). + +## Building a new image with the license file in + +You can also create a new docker file with the license file baked in. Here is an example docker build file that does that: + +```dockerfile +ARG ONPREM_IMAGE +FROM ${ONPREM_IMAGE} + +COPY --chown=app:app pactflow-onprem.lic $APP_HOME/../pactflow-onprem.lic +``` + +This can then be built with the following docker command: + +```console +$ docker build . --build-arg ONPREM_IMAGE=quay.io/pactflow/enterprise:1.10.0 +``` + +## Customising the location of the license file + +If mounting the license file in `/home` is not desirable, you can specify a custom directory using the `RG_LIC_PATH` environment variable. + +For example, to change the path to `/opt/pactflow/pactflow-onprem.lic` you would set the environment variable in the container to `RG_LIC_PATH=/opt/pactflow/`. + +## License enforcement + +The license provided encodes your designated subscription limits, such as your allocated number of users and the expiration date of your subscription. These limits are enforced by the application at runtime. In the event you have an invalid or incompatible license, the system will not boot and will provide an error in your system log file + + + +In the event the license does expire, the [health check endpoint](/docs/on-premises-2x#healthcheck-endpoint) will continue to remain operational. + +## FAQ + +### What happens when I reach my licenses user limit? + +New users will be unable to login and will receive a message indicating the user limit has been reached. + +You can rectify this by: + +1. Disabling any users that no longer require access to Pactflow +2. Upgrading your subscription to allow more users + +### What happens when my license expires? + +Well ahead of your license expiration you will be contacted from a SmartBear representative to help with ensuring a smooth transition from your expiring license to a new one. + +Pactflow will provide in-application notices when there are 30 days or less until expiry of the subscription. The notices will be displayed on both the login screen and in the footer. + +When the subscription reaches its end date, if the license has not been replaced you will lose access to Pactflow and the system will cease to function (with the exception of the [health check endpoint](/docs/on-premises-2x#healthcheck-endpoint)). diff --git a/website/docs/docs/on-premises-2x/logging.md b/website/docs/docs/on-premises-2x/logging.md new file mode 100644 index 00000000..fca9cc15 --- /dev/null +++ b/website/docs/docs/on-premises-2x/logging.md @@ -0,0 +1,15 @@ +--- +title: Logging +--- + +## Output + +PactFlow application logs are sent to the standard output stream of the Docker container, with the expectation that the container orchestration service will collect and forward them to a log aggregation service. Both the UI and App logs will be interspersed here. They are distinguishable by the `application` property. UI will be `pactflow-ui` and API will be `pactflow-application`. + +## Format + +The log format is JSON. + +## Level + +The default log level is `INFO`. This can be changed by setting the [PACTFLOW_LOG_LEVEL](environment-variables#pactflow_log_level) environment variable. diff --git a/website/docs/docs/on-premises-2x/maintenance/database.md b/website/docs/docs/on-premises-2x/maintenance/database.md new file mode 100644 index 00000000..ad6cbd9b --- /dev/null +++ b/website/docs/docs/on-premises-2x/maintenance/database.md @@ -0,0 +1,274 @@ +--- +title: Database +--- + + + +## Automatic data clean up + +:::note +Automatic data clean up is available in PactFlow On-Premises version 1.23.0 and later. +::: + +Performance can degrade when too much data accumulates in the PactFlow database. Fortunately, a lot of the data in a PactFlow instance is "unreachable" and can be removed without affecting the way it operates functionally, as generally speaking, the application (pacticipant) versions that are referenced in the verification and can-i-deploy tasks are a very small subset of the total published dataset. + +### Categories of removable data + +* Overwritten data for application versions + * Overwritten consumer contracts: these are created when a consumer contract is published with the same consumer version but different content from a previous publication - it shouldn't happen if following best practice, and there is a configuration option to stop this occurring, but such data may exist in older PactFlow instances. + * Duplicate verifications: these are created when verification results for the same pact version content are published by the same provider version multiple times - this can happen quite often under normal operation. +* Historical webhook execution data. +* Old or superseded (ie. versions that are not the latest for their branch/tag) application versions and their associated tags/pacts/verifications/webhooks. + +### How the application version cleaning works + +To ensure that the data that is still in use is not deleted, a list of "keep" selectors must be configured to specify which application versions (and associated data) should be kept. Any application version not selected by one or more of the keep selectors will (eventually) be deleted. To ensure that the clean up task itself does not impact the performance of the Broker, a limit is placed on the number of application versions that will be deleted at one time. The task will first identify all the application versions to keep, exclude those records, and then delete the oldest \[configurable number\] of application versions and their associated contracts, verifications, tags, webhook executions, and any orphan contract versions. + +### Understanding the "keep" selectors + +The keep selectors operate in a very similar way to the [consumer version selectors](https://docs.pact.io/pact_broker/advanced_topics/consumer_version_selectors/) used during verification. Each selector can have the following properties: + +* `pacticipant`: the name of the pacticipant +* `branch`: the name of the branch as a string to indicate a particular branch, or a boolean `true` to indicate "any version associated with a branch" +* `tag`: the name of the tag as a string to indicate a particular tag, or a boolean `true` to indicate "any version with a tag" +* `latest`: if `true`, then the latest version matching the other selection properties is specified. If `false` or omitted, all versions matching the other selection properties are specified. +* `mainBranch`: if set to true, specifies all versions that belong to the pacticipant's configured main branch. +* `deployed`: if set to true, specifies all currently deployed pacticipant versions +* `released`: if set to true, specifies all released pacticipant versions that are currently in support +* `max_age`: the number of days since it was created, as an integer, for which to keep the application version. + +The `pacticipant` and `max_age` property may be used in combination with the other tags. The `max_age` and `latest` keys cannot be used together. + +:::note + +The selectors `{ "deployed": true }` and `{ "released": true }` will automatically be added to the keep selectors, meaning that all versions that have ever been deployed or released will be kept. + +::: + +#### Examples + +* keep all versions on the main branch of each pacticipant that are less than 30 days old: `{ "max_age": 30, "mainBranch": true }` +* keep the latest version from each pacticipant's branch: `{ "branch": true, "latest": true }` +* keep the latest version for each pacticipant/tag: `{ "latest": true, "tag": true }` +* keep all versions less than 30 days old: `{ "max_age": 30 }` +* keep all currently deployed versions: `{ "deployed": true }` +* keep all released and currently supported versions: `{ "released": true }` +* keep all versions for Foo app: `{ "pacticipant": "Foo" }` +* keep the latest version for each pacticipant: `{ "latest": true }` +* keep all versions tagged "develop" for Foo app: `{ "pacticipant": "Foo", "tag": "develop" }` + +The selectors combine by "OR", meaning that a version is kept if it matches any of the selectors. So `[{ "max_age": 30 }, { "branch": true, "latest": true }, { "deployed": true }]` would mean "keep every version younger than 30 days old, or is the latest version for its branch, or is currently deployed". + +#### Recommended starting configuration for keep selectors + +The following are the default keep selectors specified in the clean tool, and they are a good place to start. (Remember, only one of the selectors needs to be matched to keep the version). + +* Keep all versions under 90 days old - `{ "max_age": 90 }` +* Keep all versions that are the latest for their branch - `{ "branch": true, "latest": true }` +* Keep all versions that are the latest for their tag - `{ "tag": true, "latest": true }` +* Keep all the currently deployed versions - `{ "deployed": true }` +* Keep all the released and currently supported versions - `{ "released": true }` +* Keep the latest version for every pacticipant - `{ "latest": true }` + +Notes: + +* When you deploy an application to production, the relevant pacticipant version needs to be recorded as deployed in PactFlow, so you need to ensure that you keep any version that you're likely to deploy (or rollback to). Specify a `max_age` value that is at minimum the number of days it takes between a commit being created and that commit being deployed (with a very comfortable margin of error) and any branch that you deploy from. A reasonable max_age value might be 90 days for the `main` branch. eg. `{"max_age": 90, "mainBranch": true }` +* If an application is not under active development, a selector that keeps versions by age limit might not actually select any versions. To ensure that we don't lose those critical "latest" versions for our main line of development or our deployed environments, add a selector with `{"mainBranch": true, "latest": true }`, or keep the latest version from each branch by specifying `{"branch": true, "latest": true }`. + +### Execution + +The database clean tool comes built into the PactFlow On-Premises Docker image. The Docker container should be executed using a tool like Kubernetes CronJob or AWS Batch. It should run on a regular schedule (eg. daily) and be configured to delete at least as many application versions as are expected to be created between each clean execution. + +:::note + +The clean task must use the same Docker image tag as the currently running PactFlow application. + +::: + +To execute the clean task, run the Docker container with the appropriate environment variables (documented below), the PactFlow license mounted, and the entrypoint set to `db-clean`. + +eg. +```sh +docker run --rm \ + --entrypoint db-clean \ + --volume ./pactflow-onprem.lic:/home/pactflow-onprem.lic \ + --env PACTFLOW_DATABASE_URL="..." \ # appropriate environment variables here + quay.io/pactflow/enterprise +``` + +This example Docker Compose file shows an example configuration. It can be run by saving the contents as `docker-compose.yml` and then running `docker compose up` in the same directory. Note that a PactFlow license file is required to run the PactFlow container. + +There will be no data in the database to delete, but the logs will show that the clean process has run. + +```yml +version: "3" + +services: + postgres: + image: postgres:13-alpine + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: password + POSTGRES_DB: postgres + + clean: + image: quay.io/pactflow/enterprise + depends_on: + - postgres + environment: + PACTFLOW_DATABASE_URL: "postgres://postgres:password@postgres/postgres" + PACTFLOW_DATABASE_SSLMODE: "disable" # overriding default value of "require" for demo only - "disable" should never be used in production + PACTFLOW_DATABASE_CLEAN_DELETION_LIMIT: "500" + PACTFLOW_SQL_LOG_WARN_DURATION: "60" + # Keep the latest version for every pacticipant branch, and all versions less than 30 days old, and anything deployed or released + PACTFLOW_DATABASE_CLEAN_KEEP_VERSION_SELECTORS: "[{ \"branch\": true, \"latest\": true }, {\"max_age\": 30 }, {\"deployed\": true }, {\"released\": true }]" + PACTFLOW_LOG_LEVEL: "INFO" + PACTFLOW_SQL_LOG_LEVEL: "DEBUG" + entrypoint: dockerize + # There will be no data in the database to delete, but the logs will show that the clean process has run + command: -wait tcp://postgres:5432 sh -c 'db-migrate && db-clean' + volumes: + - ./pactflow-onprem.lic:/home/pactflow-onprem.lic + +``` + +#### Initial clean strategy + +If you have a very large database, and you are just now enabling the clean, the initial clean up might take some time. To ensure that the clean does not have an impact on the performance of PactFlow, it is recommended to set the cron schedule to something quite regular for the first day (eg. every 2 minutes), and set the clean limit quite low (eg. 100). Once the task has stopped deleting any more records, set the schedule back to something like once/twice a day, and make sure the clean limit is higher than the number of new versions you expect in that time period. + +### Configuration + + + + +#### PACTFLOW_LOG_LEVEL + +The PactFlow application log level + +**Required:** false
+**Default:** `INFO`
+**Allowed values:** `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
+ +#### PACTFLOW_LOG_FORMAT + +The PactFlow application log format + +**Required:** false
+**Default:** `json`
+**Allowed values:** `json`, `default`, `color`
+**More information:** https://github.com/rocketjob/semantic_logger/tree/master/lib/semantic_logger/formatters
+ +#### PACTFLOW_SQL_LOG_LEVEL + +The log level that will be specified when the SQL query statements are logged. + +**Required:** false
+**Default:** `NONE`
+**Allowed values:** `NONE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
+ +#### PACTFLOW_DATABASE_URL + +The fully qualifed database connection string. If using Postgres on RDS with IAM authentication, the scheme must be `postgresiam` and the port must also be set. + +**Required:** if separate host, name, username, password environment variables are not set
+**Example:** `postgresql://username:password@host:port/database`
+ +#### PACTFLOW_DATABASE_ADAPTER + +The database adapter to use. Use `postgresiam` when using Postgres on RDS with IAM authentication (rather than username/password authentication). + +**Required:** false
+**Default:** `postgres`
+**Allowed values:** `postgres`, `postgresiam`
+ +#### PACTFLOW_DATABASE_USERNAME + +The database username + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +#### PACTFLOW_DATABASE_PASSWORD + +The database password + +**Required:** if PACTFLOW_DATABASE_URL is not set, unless using Postgres on RDS with IAM authentication
+ +#### PACTFLOW_DATABASE_HOST + +The database host + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +#### PACTFLOW_DATABASE_PORT + +The database port + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +#### PACTFLOW_DATABASE_NAME + +The database name + +**Required:** if PACTFLOW_DATABASE_URL is not set
+ +#### PACTFLOW_DATABASE_SSLMODE + +The Postgresql ssl mode. Note, if using Postgres on AWS RDS with IAM authentication, this must be `require`. + +**Required:** false
+**Default:** `require`
+**Allowed values:** `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`
+**More information:** https://ankane.org/postgres-sslmode-explained
+ +#### PACTFLOW_DATABASE_CLEAN_DELETION_LIMIT + +Only required when running the `db-clean` entrypoint in the PactFlow Docker container. +The maximum number of records to delete at a time from each of the (categories of removable data)[#categories-of-removable-data]. +Should be set to a number higher than the expected number of application versions that will be created between each clean, +but not so high that it will impact on the performance of the application while it is running. You may need to run tests find the optimal number to use in your environment. + +**Required:** false
+**Default:** `500`
+ +#### PACTFLOW_DATABASE_CLEAN_KEEP_VERSION_SELECTORS + +Only required when running the `db-clean` entrypoint in the PactFlow Docker container. +A JSON string containing a list of the "keep" selectors described in (Understanding the keep selectors)[#understanding-the-keep-selectors]. +To ensure the integity of the PactFlow data, the selectors `{ "deployed": true }` and `{ "released": true }` will be automatically added to the selector list if they are not specified. +Remember to escape the quotes if necessary in your configuration files. + +**Required:** false
+**Default:** `[{ "max_age": 90 }, { "branch": true, "latest": true }, { "tag": true, "latest": true }, { "deployed": true }, { "released": true }, { "latest": true }]`
+ +#### PACTFLOW_DATABASE_CLEAN_OVERWRITTEN_DATA_MAX_AGE + +Only required when running the `db-clean` entrypoint in the PactFlow Docker container. +The maximum number of days to keep "overwritten" data as described in (categories of removable data)[#categories-of-removable-data] + +**Required:** false
+**Default:** `7`
+ +#### PACTFLOW_DATABASE_CLEAN_DRY_RUN + +Only required when running the `db-clean` entrypoint in the PactFlow Docker container. +When set to `true`, the `db-clean` process will not delete any data, but will instead log the data that would be deleted if dry run was not enabled. +Use this to test that the container is configured correctly. + +**Required:** false
+**Default:** `false`
+**Allowed values:** `true`, `false`
+ +#### AWS_REGION + +Required for running Postgres on RDS with IAM authentication. This must be set to the AWS region where the RDS database instance is running. + +**Required:** false
+ + + diff --git a/website/docs/docs/on-premises-2x/network-configuration.md b/website/docs/docs/on-premises-2x/network-configuration.md new file mode 100644 index 00000000..4c0e2fa3 --- /dev/null +++ b/website/docs/docs/on-premises-2x/network-configuration.md @@ -0,0 +1,27 @@ +--- +title: Network configuration +--- + +## Firewall Configuration + +### Inbound + +#### Application port + +The PactFlow application runs on port `9292` by default. This can be configured by setting the [PACTFLOW_HTTP_PORT](/docs/on-premises-2x/environment-variables#pactflow_http_port) environment variable. + +### Outbound + +#### Webhooks + +The PactFlow application provides [webhooks](https://docs.pact.io/pact_broker/advanced_topics/webhooks) that are primarily designed for triggering builds in the **CI systems** of integrated applications. They may also be used to provide status updates to **source control systems** (eg. Github) or **team chat software** (eg. Slack). To enable PactFlow to operate correctly, network access should be configured to systems that are likely to be the targets of these webhooks. + +The host names of these services should also be whitelisted in the [PACTFLOW_WEBHOOK_HOST_WHITELIST](/docs/on-premises-2x/environment-variables/#pactflow_webhook_host_whitelist) environment variable. + +## Certificate and TLS termination + +The recommended configuration is to terminate TLS at the load balancer, communicating over HTTP to the target application servers, which in turn communicate over local sockets to applications within the container. + +If you would like to run PactFlow in a TLS-everywhere configuration, modify the HAProxy configuration file (`/tmp/haproxy.cfg`) to bind a certificate to the `frontend`, and ensure the certificate has been appropriately mounted/added to the container. + +Refer to the [HAProxy documentation](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/security/ssl-tls/client-side-encryption/) for further information. \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/redis.md b/website/docs/docs/on-premises-2x/redis.md new file mode 100644 index 00000000..f926b955 --- /dev/null +++ b/website/docs/docs/on-premises-2x/redis.md @@ -0,0 +1,38 @@ +--- +title: Redis Cache +--- + +## Introduction + +PactFlow requires a Redis-compatible storage for the following functions: + +- User session management +- UI caching for performance + +## Session management + +User sessions are stored in Redis. Only a 128-bit session ID is shared with the user's browser. This ID is valid for 30 days and is signed with a server-side secret to prevent tampering—regardless of the cookie's expiry time. This protects against cookie replay attacks. + +All user data, including `idToken` and `accessToken`, is stored server-side and is never exposed to the user. + +## Caching + +To improve UI performance, PactFlow uses a server-side caching layer. + +This may result in temporary staleness—displayed content can differ based on when data was last fetched. Differences may appear between users or across browser sessions. + +PactFlow uses a *per-user* server-side cache, following a `stale-while-revalidate` strategy: + +- **Hot cache:** Data is used without validation. +- **Warm cache:** Data is served immediately, and the cache is refreshed in the background. +- **Cold cache:** The UI blocks until data is fetched from the API. + +This approach balances performance and freshness. + +When a user writes data through the UI, their *entire user cache* is invalidated immediately. This ensures correctness for the current user. However, if the change is made by another user or via the API, it may take longer to appear. + +As a fallback, the PactFlow UI follows HTTP cache-control conventions. If a user performs a hard refresh (`Shift+Refresh`), the browser sends headers like `Cache-Control: no-cache` or `Pragma: no-cache`, which bypass the cache. + +## Supported versions + +Redis 7.0 and later is supported. \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/releases/1.10.0.md b/website/docs/docs/on-premises-2x/releases/1.10.0.md new file mode 100644 index 00000000..90460c95 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.10.0.md @@ -0,0 +1,17 @@ +--- +title: 1.10.0 +--- + +## Release date + +31 March 2021 + +## Notes + +* The on-premises version of PactFlow requires a license file to run. Contact your Account Manager if you have not received one. + +## Features + +* Update OSS broker to 2.79.0 +* Generate downloadable example projects for consumers and providers + diff --git a/website/docs/docs/on-premises-2x/releases/1.11.0.md b/website/docs/docs/on-premises-2x/releases/1.11.0.md new file mode 100644 index 00000000..9903ba26 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.11.0.md @@ -0,0 +1,72 @@ +--- +title: 1.11.0 +--- + +## Release date + +5 July 2021 + +## Features + +- Allow a banner to be configured and displayed post-login. +- Support [user preferences](/docs/user-interface/settings/preferences#personal-preferences). +- Support [system preferences](/docs/user-interface/settings/preferences#system-preferences). +- Support [PACTFLOW_DATABASE_PORT](/docs/on-premises-2x/environment-variables#pactflow_database_port) environment variable. +- Allow API token expiry to be configured. +- Show warning in UI when API token is due to expire. +- Support database field level encryption of API tokens. +- Support [ignoring specified applications](https://docs.pact.io/pact_broker/client_cli/readme#can-i-deploy) when using can-i-deploy. +- Allow [secrets](/docs/user-interface/settings/secrets) and [webhooks](/docs/user-interface/settings/webhooks) to be assigned to, and managed by, a specific team. +- Improve [pending pacts and WIP pacts](https://github.com/pact-foundation/pact_broker/pull/432) logic. +- Add [pactbroker.azureDevOpsVerificationStatus webhook parameter](/docs/user-interface/settings/webhooks#pactflow). +- Validate that well formed JSON or YAML is used when publishing Base64 encoded provider contracts. +- Disallow the deletion of predefined roles. +- Add endpoint to [reset role/permissions assignments](/docs/permissions/predefined-roles#resetting-permissions-for-predefined-roles) for predefined roles. +- Deprecate `system:preference:read` permission. All logged in users may now read the system preferences. +- Allow team administrators to be assigned to teams. Team administrators can add and remove users and applications from teams. +- Add [`system_account:manage:team`](/docs/permissions#system_accountmanageteam) permission to allow team users to view/regenerate the API tokens for system account users that are assigned to their team. +- Update default permissions assigned to predefined roles to use [team scoped permissions](/docs/permissions/predefined-roles#user) where ever applicable. +- Renamed "Test Maintainer" role to ["User"](/docs/permissions/predefined-roles#user) for new installations. + +## Fixes + +- Ensure the SAML provider base URL is derived correctly when the login endpoint is specified in the metadata, not an environment variable +- Correctly record which SAML provider was used to log in when multiple SAML providers are configured +- Ensure api token values are not show in debug logging + +## Migration notes + +- If not already set, the `PACTFLOW_BASE_URL` should be set to mitigate cache poisoning vulnerabilities. +- The `PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY` environment variable has been renamed to `PACTFLOW_MASTER_ENCRYPTION_KEY`. The old name will continue to work, but please update your configuration to avoid warnings. Do not change the value of this key. +- Steps to enable API token database field level encryption: + + - Please read the relevant documentation for each of the following environment variables, and update your configuration with the appropriate values. + - [`PACTFLOW_MASTER_ENCRYPTION_KEY`](/docs/on-premises-2x/environment-variables#pactflow_master_encryption_key) - renamed from `PACTFLOW_MASTER_SECRETS_ENCRYPTION_KEY`. Do not change the value of this key. + - [`PACTFLOW_API_TOKEN_ENCRYPTION_ENABLED`](/docs/on-premises-2x/environment-variables#pactflow_api_token_encryption_enabled) - must be set to "true" + - [`PACTFLOW_API_TOKEN_IV`](/docs/on-premises-2x/environment-variables#pactflow_api_token_iv) - a random value must be assigned as per the documentation. + - Restart the PactFlow application. The API tokens will be encrypted during start up once the `PACTFLOW_API_TOKEN_ENCRYPTION_ENABLED` environment variable has been set to true. + - Verify that the API tokens have been encrypted by running the SQL: + + ```sql + SELECT COUNT(*) FROM saas_api_tokens; + SELECT COUNT(*) FROM saas_api_tokens WHERE encrypted_value IS NOT NULL; + ``` + + Both counts should be the same. + + - Verify that users still have access to the API using their existing tokens executing the following curl command, or making the same request with Postman or equivalent: + + ```bash + curl -v https://{YOUR_PACTFLOW_DOMAIN} \ + -H "Authorization: Bearer {EXISTING_TOKEN_VALUE}" + ``` + + The response should be a 200 OK with a JSON body. + + - Once it has been confirmed that the now-encrypted API tokens are working correctly, please clear the unencrypted values from the database using the following SQL: + + ```sql + UPDATE saas_api_tokens SET value = NULL; + ``` + + - Once API token encryption has been enabled and the unencrypted values removed, encryption cannot be disabled again. diff --git a/website/docs/docs/on-premises-2x/releases/1.11.1.md b/website/docs/docs/on-premises-2x/releases/1.11.1.md new file mode 100644 index 00000000..ca99878c --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.11.1.md @@ -0,0 +1,11 @@ +--- +title: 1.11.1 +--- + +## Release date + +9 July 2021 + +## Fixes + +* Fix runtime error generating validation message for can-i-deploy diff --git a/website/docs/docs/on-premises-2x/releases/1.12.0.md b/website/docs/docs/on-premises-2x/releases/1.12.0.md new file mode 100644 index 00000000..b3350c04 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.12.0.md @@ -0,0 +1,14 @@ +--- +title: 1.12.0 +--- + +## Release date + +21 September 2021 + +## Features + +* Add support for [PACTFLOW_SAML_ALLOWED_CLOCK_DRIFT](/docs/on-premises-2x/environment-variables#pactflow_saml_allowed_clock_drift) +* Validate encryption master key on startup +* Allow the default role and team to be configured in the system preferences +* Add [Guest role](/docs/permissions/predefined-roles#guest). diff --git a/website/docs/docs/on-premises-2x/releases/1.13.0.md b/website/docs/docs/on-premises-2x/releases/1.13.0.md new file mode 100644 index 00000000..c1796a09 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.13.0.md @@ -0,0 +1,11 @@ +--- +title: 1.13.0 +--- + +## Release date + +23 September 2021 + +## Features + +* Add support for [PACTFLOW_HTTP_LOGGING_ENABLED](/docs/on-premises-2x/environment-variables#pactflow_http_logging_enabled) diff --git a/website/docs/docs/on-premises-2x/releases/1.13.1.md b/website/docs/docs/on-premises-2x/releases/1.13.1.md new file mode 100644 index 00000000..77d17db7 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.13.1.md @@ -0,0 +1,11 @@ +--- +title: 1.13.1 +--- + +## Release date + +27 September 2021 + +## Fixes + +* Correct missing default value for the database adapter which stops the application from starting up when the individual database connection attributes are used. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.0.md b/website/docs/docs/on-premises-2x/releases/1.14.0.md new file mode 100644 index 00000000..9672fb4c --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.0.md @@ -0,0 +1,30 @@ +--- +title: 1.14.0 +--- + +## Release date + +2 December 2021 + +## Features + +- Add support for publishing pacts and verification results with [branches](https://docs.pact.io/pact_broker/branches). +- Add support for recording [deployments and releases](https://docs.pact.io/pact_broker/recording_deployments_and_releases). +- Add [global](/docs/permissions#deployment_and_releaserecord) and [team](/docs/permissions#deployment_and_releaserecordteam) scoped permissions for recording deployments and releases. +- Add support for the new [`contract_requiring_verification_published` webhook](https://docs.pact.io/blog/2021/10/11/contract-requiring-verification-published-webhook-event). +- Add support for disabling [dangerous pact modification](https://docs.pact.io/pact_broker/configuration/settings#allow_dangerous_contract_modification). +- Added support for the following configuration settings: + - [PACTFLOW_DATABASE_CONNECTION_VALIDATION_TIMEOUT](/docs/on-premises-2x/environment-variables#pactflow_database_connection_validation_timeout) + - [PACTFLOW_ALLOW_DANGEROUS_CONTRACT_MODIFICATION](/docs/on-premises-2x/environment-variables#pactflow_allow_dangerous_contract_modification) + - [PACTFLOW_USE_FIRST_TAG_AS_BRANCH](/docs/on-premises-2x/environment-variables#pactflow_use_first_tag_as_branch) + - [PACTFLOW_CREATE_DEPLOYED_VERSIONS_FOR_TAGS](/docs/on-premises-2x/environment-variables#pactflow_create_deployed_versions_for_tags) + - [PACTFLOW_USE_HAL_BROWSER](/docs/on-premises-2x/environment-variables#pactflow_use_hal_browser) + +## Fixes + +- Do not error when attempting to add a user or application to the default team as configured in the system preferences, and the default team no longer exists. + +## Migration notes + +- Update the PactFlow Docker image tag to `1.14.0` and redeploy the PactFlow application infrastructure. +- There are no configuration changes to be made. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.1.md b/website/docs/docs/on-premises-2x/releases/1.14.1.md new file mode 100644 index 00000000..090f470f --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.1.md @@ -0,0 +1,11 @@ +--- +title: 1.14.1 +--- + +## Release date + +7 December 2021 + +## Fixes + +* Display correct icon for pacts with status "failed_pending". diff --git a/website/docs/docs/on-premises-2x/releases/1.14.2.md b/website/docs/docs/on-premises-2x/releases/1.14.2.md new file mode 100644 index 00000000..c8cd5431 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.2.md @@ -0,0 +1,15 @@ +--- +title: 1.14.2 +--- + +## Release date + +31 January 2022 + +## Fixes + +* Fix error raised when setting [`database_connection_validation_timeout`](/docs/on-premises-2x/environment-variables#pactflow_database_connection_validation_timeout). + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.3.md b/website/docs/docs/on-premises-2x/releases/1.14.3.md new file mode 100644 index 00000000..84c8252d --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.3.md @@ -0,0 +1,15 @@ +--- +title: 1.14.3 +--- + +## Release date + +1 February 2022 + +## Fixes + +* Fixed CVE-2021-23807 + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.4.md b/website/docs/docs/on-premises-2x/releases/1.14.4.md new file mode 100644 index 00000000..1e1c29d9 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.4.md @@ -0,0 +1,17 @@ +--- +title: 1.14.4 +--- + +## Release date + +3 February 2022 + +## Fixes + +* Updated Docker base image to `ruby:2.7.5-alpine3.13` +* Fixed `disable_ssl_verification` setting which was not being honoured in the webhook background process. +* Fixed `webhook_certificates` setting which was not being honoured in the webhook background process. + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.5.md b/website/docs/docs/on-premises-2x/releases/1.14.5.md new file mode 100644 index 00000000..c574b88e --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.5.md @@ -0,0 +1,15 @@ +--- +title: 1.14.5 +--- + +## Release date + +7 February 2022 + +## Fixes + +* Fix CVE-2021-3918 + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.6.md b/website/docs/docs/on-premises-2x/releases/1.14.6.md new file mode 100644 index 00000000..9b4f3056 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.6.md @@ -0,0 +1,19 @@ +--- +title: 1.14.6 +--- + +## Release date + +10 February 2022 + +## Fixes + +* Fix CVE-2018-20677 (bootstrap) +* Fix CVE-2018-20676 (bootstrap) +* Fix CVE-2018-14041 (bootstrap) +* Fix CVE-2021-23358 (underscore) +* Fix CVE-2021-31799 (rdoc) + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.7.md b/website/docs/docs/on-premises-2x/releases/1.14.7.md new file mode 100644 index 00000000..b038761a --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.7.md @@ -0,0 +1,15 @@ +--- +title: 1.14.7 +--- + +## Release date + +11 February 2022 + +## Fixes + +* Add missing custom token params to JWT retrieval call. + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.14.8.md b/website/docs/docs/on-premises-2x/releases/1.14.8.md new file mode 100644 index 00000000..82bad596 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.14.8.md @@ -0,0 +1,15 @@ +--- +title: 1.14.8 +--- + +## Release date + +11 February 2022 + +## Fixes + +* Parse teams and roles from access token instead of id token. + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.15.0.md b/website/docs/docs/on-premises-2x/releases/1.15.0.md new file mode 100644 index 00000000..6d082f59 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.15.0.md @@ -0,0 +1,18 @@ +--- +title: 1.15.0 +--- + +:::caution NOTE +Docker 19.03 support is dropped with this release. +::: + +## Release date + +15 February 2022 + + +## Migration notes + +This release upgrades the base image from alpine3.13 to alpine3.15. **Please note that Docker 19.03 is no longer supported** as it is EOL and alpine3.15 requires Docker 20.10.0 or later (see point 2 in the `faccessat2` section of the [Alpine 3.14 release notes](https://wiki.alpinelinux.org/wiki/Release_Notes_for_Alpine_3.14.0#faccessat2) for more information). + +If you are already running PactFlow on Docker 20.10.0 or later, no action is required. Please update your PactFlow image version as normal. If you are running a version of Docker older than 20.10.0, please upgrade your Docker version to 20.10.0 or later before upgrading to PactFlow 1.15.0. diff --git a/website/docs/docs/on-premises-2x/releases/1.16.0.md b/website/docs/docs/on-premises-2x/releases/1.16.0.md new file mode 100644 index 00000000..8a4727ab --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.16.0.md @@ -0,0 +1,15 @@ +--- +title: 1.16.0 +--- + +## Release date + +18 February 2022 + +## Features + +* Added support for using AWS IAM authentication between the PactFlow application and an RDS Postgres instance. See documentation [here](/docs/on-premises-2x/database#aws-iam-authentication). + +## Migration notes + +N/A. \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/releases/1.17.0.md b/website/docs/docs/on-premises-2x/releases/1.17.0.md new file mode 100644 index 00000000..7ea5d873 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.17.0.md @@ -0,0 +1,15 @@ +--- +title: 1.17.0 +--- + +## Release date + +25 February 2022 + +## Features + +* Added support for server side session inactivity timeout, configurable via the environment variable [`PACTFLOW_SESSION_INACTIVITY_TIMEOUT`](/docs/on-premises-2x/environment-variables#pactflow_session_inactivity_timeout) + +## Migration notes + +By default, the `PACTFLOW_SESSION_INACTIVITY_TIMEOUT` will be set to the configured value of `PACTFLOW_SESSION_LENGTH`. This effectively disables the feature, for backwards compatibility purposes. If you would like to take advantage of this new feature, set the `PACTFLOW_SESSION_INACTIVITY_TIMEOUT` to the value of your choice. If you do not wish to use this feature, no change is required. diff --git a/website/docs/docs/on-premises-2x/releases/1.17.1.md b/website/docs/docs/on-premises-2x/releases/1.17.1.md new file mode 100644 index 00000000..12a9f10b --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.17.1.md @@ -0,0 +1,12 @@ +--- +title: 1.17.1 +--- + +## Release date + +10 March 2022 + +## Fixes + +* Upgrade busybox to fix CVE-2021-42377 +* Fix error returned when viewing OSS server side rendered UI. diff --git a/website/docs/docs/on-premises-2x/releases/1.17.2.md b/website/docs/docs/on-premises-2x/releases/1.17.2.md new file mode 100644 index 00000000..3dad692e --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.17.2.md @@ -0,0 +1,11 @@ +--- +title: 1.17.2 +--- + +## Release date + +28 March 2022 + +## Fixes + +* Ensure commas in database and basic auth credential configurations do not cause the values to be parsed as arrays. diff --git a/website/docs/docs/on-premises-2x/releases/1.17.3.md b/website/docs/docs/on-premises-2x/releases/1.17.3.md new file mode 100644 index 00000000..4785d60a --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.17.3.md @@ -0,0 +1,11 @@ +--- +title: 1.17.3 +--- + +## Release date + +12 April 2022 + +## Fixes + +* CVE-2018-25032 diff --git a/website/docs/docs/on-premises-2x/releases/1.18.0.md b/website/docs/docs/on-premises-2x/releases/1.18.0.md new file mode 100644 index 00000000..44d03d3e --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.18.0.md @@ -0,0 +1,28 @@ +--- +title: 1.18.0 +--- + + + + +## Release date + +31 May 2022 + +## Features + +* Enable [bi-directional contracts](https://pactflow.io/blog/introducing-bi-directional-contract-testing/) feature. +* Add support for monitoring with [New Relic](/docs/on-premises-2x/environment-variables#new_relic_agent_enabled). +* Require that the `PACTFLOW_BASE_URL` specifies a `https` URL (rather than `http`) unless [`PACTFLOW_REQUIRE_HTTPS`](/docs/on-premises-2x/environment-variables#pactflow_require_https) is set to false. +* Check for potential duplicate pacticipants in publish contracts endpoint. +* Timeout long running pact content diff requests. +* Improve error message when request has non UTF-8 characters. + +## Fixes + +* Matrix - fix performance issue when querying matrix with one selector +* Ensure cookie secret set via environment variable is not parsed as an array when it contains commas. +* CVE-2018-25032 +* CVE-2022-29824 +* CVE-2022-30122 + diff --git a/website/docs/docs/on-premises-2x/releases/1.19.0.md b/website/docs/docs/on-premises-2x/releases/1.19.0.md new file mode 100644 index 00000000..995b74c9 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.19.0.md @@ -0,0 +1,20 @@ +--- +title: 1.19.0 +--- + +## Release date + +1 August 2022 + +## Features + +* Return user email to ui for user with unknown names +* Allow configuration of [max_connections](https://docs.pactflow.io/docs/on-premises-2x/environment-variables/#pactflow_database_max_connections) and [pool_timeout](https://docs.pactflow.io/docs/on-premises-2x/environment-variables/#pactflow_database_pool_timeout) + +## Fixes + +* [Correctly apply the `deployment_and_release:record:team` permission](https://github.com/pactflow/roadmap/issues/71) when recording deployments and releases. +* Gracefully handle policy check when no contracts are defined in the request to publish contracts +* Apply the integrations limit to the publish contracts endpoint +* CVE-2022-30122 CVE-2022-30123 GHSA-cgx6-hpwq-fhv5 CVE-2022-29181 GHSA-xh29-r2w5-wx8m +* Update mechanize for CVE-2022-31033 diff --git a/website/docs/docs/on-premises-2x/releases/1.19.1.md b/website/docs/docs/on-premises-2x/releases/1.19.1.md new file mode 100644 index 00000000..be751823 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.19.1.md @@ -0,0 +1,12 @@ +--- +title: 1.19.1 +--- + +## Release date + +18 August 2022 + +## Fixes + +* Show correct cross contract comparison result in Matrix UI when comparisons exist for multiple consumer pacts +* Show correct contract deletion options in kebab menu when viewing the bi-directional contract details page \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/releases/1.19.2.md b/website/docs/docs/on-premises-2x/releases/1.19.2.md new file mode 100644 index 00000000..b6e8bcc3 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.19.2.md @@ -0,0 +1,11 @@ +--- +title: 1.19.2 +--- + +## Release date + +24 August 2022 + +## Fixes + +* Correctly use default value for PACTFLOW_SQL_LOG_LEVEL when the environment variable has not been set \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/releases/1.20.0.md b/website/docs/docs/on-premises-2x/releases/1.20.0.md new file mode 100644 index 00000000..3164c587 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.20.0.md @@ -0,0 +1,18 @@ +--- +title: 1.20.0 +--- + +## Release date + +2 September 2022 + +## Features + +* Added support for [demo authentication](/docs/on-premises-2x/authentication/demo). Note: using basic auth for demonstration mode is no longer supported. + +## Fixes + +* CVE-2020-36599 +* Fixed error message "unable to load resource, as it was not found" shown on user admin page. +* When deleting an integration, ensure a provider with an OAS is not deleted if another consumer has a pact with it. +* Correctly identify database version when schema_migrations table is empty. diff --git a/website/docs/docs/on-premises-2x/releases/1.21.0.md b/website/docs/docs/on-premises-2x/releases/1.21.0.md new file mode 100644 index 00000000..f368b014 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.21.0.md @@ -0,0 +1,16 @@ +--- +title: 1.21.0 +--- + +## Release date + +21 October 2022 + +## Features + +* Display license expiry notices in the UI when there are fewer than 30 days until expiry. +* Implement pending logic for provider branches. + +## Fix + +* Fix performance issue when calculating the work in progress pacts for the "pacts for verification" endpoint. diff --git a/website/docs/docs/on-premises-2x/releases/1.21.1.md b/website/docs/docs/on-premises-2x/releases/1.21.1.md new file mode 100644 index 00000000..efb40bfd --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.21.1.md @@ -0,0 +1,11 @@ +--- +title: 1.21.1 +--- + +## Release date + +4 Nov 2022 + +## Fix + +* Fix argument error when publishing pacts diff --git a/website/docs/docs/on-premises-2x/releases/1.22.0.md b/website/docs/docs/on-premises-2x/releases/1.22.0.md new file mode 100644 index 00000000..ecb36dbb --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.22.0.md @@ -0,0 +1,26 @@ +--- +title: 1.22.0 +--- + +## Release date + +13 Feb 2023 + +## Features + +* Pagination has been added to the Pacticipant end point +* Miscellaneous performance improvements + +## Fixes + +* Fix BDC incorrectly requiring consumer to be deployed to deploy the provider +* Restrict users from changing their own roles in PactFlow API +* Restrict users from updating their own roles via bulk actions +* Restrict users without required permissions from creating and updating other users +* Add validation to ensure an environment or to tag is specified for the /can-i-deploy endpoint +* Check that request body does not contain any invalid UTF-8 characters before JSON parsing + + +## Migration notes + +N/A. \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/releases/1.22.1.md b/website/docs/docs/on-premises-2x/releases/1.22.1.md new file mode 100644 index 00000000..56a561af --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.22.1.md @@ -0,0 +1,16 @@ +--- +title: 1.22.1 +--- + +## Release date + +23 Feb 2023 + +## Fixes + +* Fix error raised for clean task when one keep selector has a max age, and another keep selector has a max age and branch. +* Fix incorrect "no" response for can-i-deploy when a provider with a provider contract has multiple consumers. + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.23.0.md b/website/docs/docs/on-premises-2x/releases/1.23.0.md new file mode 100644 index 00000000..8cef25a7 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.23.0.md @@ -0,0 +1,16 @@ +--- +title: 1.23.0 +--- + +## Release date + +23 Feb 2023 + +## Features + +* Improve pre-calculation of pact/provider contract comparisons to reduce chance of missing comparison when can-i-deploy is run. +* Add db-clean entrypoint to PactFlow Docker image to support [database maintenance](/docs/on-premises-2x/maintenance/database). + +## Migration notes + +N/A. diff --git a/website/docs/docs/on-premises-2x/releases/1.23.1.md b/website/docs/docs/on-premises-2x/releases/1.23.1.md new file mode 100644 index 00000000..e86667d6 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.23.1.md @@ -0,0 +1,11 @@ +--- +title: 1.23.1 +--- + +## Release date + +22 May 2023 + +## Fixes + +* Fix vulnerabilities diff --git a/website/docs/docs/on-premises-2x/releases/1.24.0.md b/website/docs/docs/on-premises-2x/releases/1.24.0.md new file mode 100644 index 00000000..7f51a04a --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.24.0.md @@ -0,0 +1,25 @@ +--- +title: 1.24.0 +--- + +## Release date + +6 June 2023 + +## Features + +* Upgrade to Ruby 3.2 +* Execute missing pact/OAS comparisons asynchronously to prevent can-i-deploy HTTP requests timing out. See [blog post](https://pactflow.io/blog/resilient-builds-with-can-i-deploy-2/). +* Allow pacticipants to be searched by name using the query string `?q={term}` +* Add pagination to teams endpoint +* Compress response payloads with gzip +* Upgrade to latest swagger-mock-validator +* When comparing a pact and OAS for a bi-directional contract, select OAS response schema based on accept and request schema based on content-type headers +* When comparing a pact and OAS for a bi-directional contract, support comparisons for [Pact V4 bodies](https://github.com/pact-foundation/pact-specification/tree/version-4#bodies) rather than treating the section as JSON. + +## Fixes + +* Fix error raised when querying the matrix for an integration using bi-directional contracts with a single selector and no 'deploy to' selector (tag, environment, or branch). +* Fix error raised when updating a team with a team member that has been marked as inactive. +* SCIM - allow externalIdpId and externalIdpUsername fields to be writable in the create user endpoint, to ensure provisioned user details are correctly matched with the newly logged in user details. +* Add missing validation for the provider version branch when fetching pacts for verification, to ensure that empty strings are disallowed diff --git a/website/docs/docs/on-premises-2x/releases/1.25.0.md b/website/docs/docs/on-premises-2x/releases/1.25.0.md new file mode 100644 index 00000000..68542329 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.25.0.md @@ -0,0 +1,22 @@ +--- +title: 1.25.0 +--- + +## Release date + +28 June 2023 + +## Features + +* Add support for negative scenarios in bi-directional contracts. When the expected response code is >= 400, request parameters, headers, body and security requirements are ignored, and the expected response schema is selected for comparison. + +## Fixes + +* Address performance issues in the dashboard when large numbers of pacticipants are present. +* Improve performance of integrations list on dashboard by using pagination. +* Improve performance of API for network diagram by updating network discovery algorithm and limiting the number of applications that are included in the diagram. +* When deleting a team, disassociate webhooks and secrets to prevent foreign key errors. + +## Migration notes + +N/A diff --git a/website/docs/docs/on-premises-2x/releases/1.26.0.md b/website/docs/docs/on-premises-2x/releases/1.26.0.md new file mode 100644 index 00000000..30354c2c --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.26.0.md @@ -0,0 +1,51 @@ +--- +title: 1.26.0 +--- + +## Release date + +07 August 2023 + +## Features + +* Support application/problem+json error response format for all non-200 responses +* [Major version upgrade of AJV](https://docs.pactflow.io/docs/bi-directional-contract-testing/contracts/oas/changelog) from v6 to v8 and Improve support for allOf, anyOf, oneOf, including polymorphic inheritance. +* Add new SCIM role to be assigned to the System Account that is used to access the PactFlow SCIM API. + +## Fixes + +* Fix error occuring when can-i-deploy badge is requested and no version is found +* Fix incorrect decoding of pact v4 bodies +* OAS now supports `exclusiveMinimum` and `exclusiveMaximum` correctly in request and response bodies +* Fix null pointer in role users endpoint + +## Migration notes + +### SCIM role migration + +These migration steps are only relevant if the PactFlow SCIM API is in use. + +1. Identify the System Account that is being used to access the SCIM API. + * Login to PactFlow as an Administrator. + * Click the Settings icon in the top right. + * Click the `Users` link in the left menu. + * Select `System Accounts` in the drop down box above the User list. + * Identify the relevant System Account and note the name. +2. Ensure that no role called `SCIM` exists. + * From the PactFlow Settings page, click the `Roles` link. + * If a role called `SCIM` exists, click the `EDIT` button, change the name (eg. `SCIM (Deprecated)`), and click `SAVE` +3. Perform the release as normal. +4. Assign the new SCIM role to the System Account identified in step 1. + * Login to PactFlow as an Administrator. + * Click the Settings icon in the top right. + * Click the `Users` link in the left menu. + * Select `System Accounts` in the drop down box above the User list. + * Locate the relevant System Account in the list. + * Click the `...` icon at the right of the row for the relevant System Account. + * Select `Edit roles`. + * Deselect the existing role. + * Select `SCIM`. + * Click `OK` +5. If there was a custom role previously used for the SCIM System Account, delete it. + * From the PactFlow Settings page, click the `Roles` link. + * Click the `DELETE` button next to the custom role. diff --git a/website/docs/docs/on-premises-2x/releases/1.27.0.md b/website/docs/docs/on-premises-2x/releases/1.27.0.md new file mode 100644 index 00000000..4fb0acf0 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.27.0.md @@ -0,0 +1,27 @@ +--- +title: 1.27.0 +--- + +## Release date + +21 September 2023 + +## Features + +* Bi-directional contracts - add "all in one" endpoint for publishing provider contracts with branch and tags +* Bi-directional contracts Pact/OAS comparison tool (swagger-mock-validator) + * Support OAS schemas with nested `allOf` operators + * Set default `additionalProperties` in response to false + * Handle exclusiveMinimum/exclusiveMaximum in bodies + * Support polymorphic inheritance in request bodies + * Improve support for allOf, anyOf, oneOf +* Add branch endpoint supporting GET and DELETE +* Add pagination parameter validation to endpoints that support pagination. + +## Fixes + +* Do not raise an error when attempting to save a duplicate provider contract version +* Matrix - optimise long running query +* Bi-directional contracts Pact/OAS comparison tool (swagger-mock-validator) - correctly decode Pact v4 bodies + +## Migration notes diff --git a/website/docs/docs/on-premises-2x/releases/1.28.0.md b/website/docs/docs/on-premises-2x/releases/1.28.0.md new file mode 100644 index 00000000..3ed84761 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.28.0.md @@ -0,0 +1,27 @@ +--- +title: 1.28.0 +--- + +## Release date + +28 November 2023 + +## Features + +* Add endpoint to list branches +* Removed "generate project" links +* Allow additional sources to be added to the Content-Security-Policy +* Pagination parameters `pageSize` and `pageNumber` have been renamed to `size` and `page`, but the older name is retained for backward compatibility +* Support ignoring applications for "can-i-deploy" with bi-directional contracts + +## Fixes + +* Fixed an issue when trying to read individual system preferences +* Add index to fix performance issue when deleting versions with many deployed or released versions. +* Fix null pointer error raised when no matching environment found when querying environments by name + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.29.0.md b/website/docs/docs/on-premises-2x/releases/1.29.0.md new file mode 100644 index 00000000..230d9cd1 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.29.0.md @@ -0,0 +1,25 @@ +--- +title: 1.29.0 +--- + +## Release date + +31 January 2024 + +## Features + +* Add verification modes to the GET /integration endpoint +* Reduce time for a successful can-i-deploy result when using bi-directional contracts by reducing the number of historical branches to generate pact/OAS comparisons for + +## Fixes + +* Add validation to ensure a pacticipant cannot be created with an empty name when publishing a contract. +* Fix performance issues due to contention in the integrations table when publishing a large number of contracts (> 20) per request, in parallel +* Fix contention on the API tokens table when large numbers of parallel requests come in with the same token +* Correct the logic used to calculate the pactRevisionsPerConsumerVersion distribution in the metrics endpoint + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.30.0.md b/website/docs/docs/on-premises-2x/releases/1.30.0.md new file mode 100644 index 00000000..62b2de28 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.30.0.md @@ -0,0 +1,25 @@ +--- +title: 1.30.0 +--- + +## Release date + +10 April 2024 + +## Features + +* Add team-specific metric details via an endpoint `/metrics/teams` + +## Fixes + +* Fix bug where a user with `environment:team:read` permission received a 403 when performing a GET request for an individual environment +* Ensure matrix and can-i-deploy use the latest revision of the pact when using bi-directional contracts and the pact for a consumer version is modified +* Fix bug where searching integrations in the dashboard would only search from the first 1000 integrations +* Improved performance of the `/admin/users` endpoint +* Disables “dangerous contract modification” by default for new installations. Existing on-premises installations are unaffected. See https://docs.pactflow.io/docs/troubleshooting/disabling-dangerous-contract-modification/#on-premesis-1 for more, and how to disable it for existing installations. + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.31.0.md b/website/docs/docs/on-premises-2x/releases/1.31.0.md new file mode 100644 index 00000000..1824fccc --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.31.0.md @@ -0,0 +1,31 @@ +--- +title: 1.31.0 +--- + +## Release date + +22 August 2024 + +## Features + +* Added new `/labels` API that lists all labels + +## Fixes + +* Fixes an issue where the "next" embedded link was not documented in the response body of the `GET /audit` endpoint +* Fixes the `NoMethodError` for pacticipants PATCH request when request body contains embedded labels +* Documents the API `/pacticipants/:pacticipant_name/labels/:label_name` for managing labels for a pacticipant +* Fixed unique team name issue when updating team in settings +* Fix bug which caused a missing row in the matrix when there are a mix of classic Pact and bi-directional contracts +* Resolves the `UniqueConstraintViolation` issue when updating team users via a PUT request. +* Fixed incorrect type standardization for openapi -v 3.1.0 +* Team Administrators will now have permission to view environments +* Deprecated _embedded payload format in the team update APIs +* Fixes an issue where deleting an integration in the context of BDCT leads to the unintended deletion of provider contracts +* Added provider version number to webhook endpoint + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.32.0.md b/website/docs/docs/on-premises-2x/releases/1.32.0.md new file mode 100644 index 00000000..9ff3dcc1 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.32.0.md @@ -0,0 +1,25 @@ +--- +title: 1.32.0 +--- + +## Release date + +09 September 2024 + +## Features + +N/A + +## Fixes + +* fixed the situation when a consumer-provider pair has both an OAS and traditional pact containing both HTTP and message interactions. Message interactions that haven't been validated at comparison time or when `can-i-deploy` is called, returns a new Message Verification Missing reason. +* Fixed vulnerability GHSA-4xqq-m2hx-25v8 ( rexml ) +* Fixed vulnerability GHSA-vg3r-rm7w-2xgh ( rexml ) +* Fixed vulnerability GHSA-vmwr-mc7x-5vc3 ( rexml ) +* Fixed vulnerability CVE-2024-6119 ( openssl-dev, libssl-dev, libcrypto3 ) + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.33.0.md b/website/docs/docs/on-premises-2x/releases/1.33.0.md new file mode 100644 index 00000000..a6c57c5f --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.33.0.md @@ -0,0 +1,21 @@ +--- +title: 1.33.0 +--- + +## Release date + +18 September 2024 + +## Features + +N/A + +## Fixes + +* CVEs GHSA-cvp8-5r8g-fhvq, GHSA-jw9c-mfg7-9rx2, GHSA-r55c-59qm-vjw6, GHSA-5866-49gr-22v4, GHSA-vmwr-mc7x-5vc3 + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.34.0.md b/website/docs/docs/on-premises-2x/releases/1.34.0.md new file mode 100644 index 00000000..a57a6ad0 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.34.0.md @@ -0,0 +1,27 @@ +--- +title: 1.34.0 +--- + +## Release date + +22 October 2024 + +## Features + +N/A + +## Fixes +* updated packages to fix multiple CVEs + - webrick ( GHSA-6f62-3596-g6w7 ) + - wget ( CVE-2024-38428 ) + - puma ( GHSA-9hf4-67fc-4vf4 ) + - openssl-dev ( CVE-2024-9143 ) + - libssl3 ( CVE-2024-9143 ) + - openssl ( CVE-2024-9143 ) + - libcrypto3 ( CVE-2024-9143 ) + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.35.0.md b/website/docs/docs/on-premises-2x/releases/1.35.0.md new file mode 100644 index 00000000..c82b6214 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.35.0.md @@ -0,0 +1,29 @@ +--- +title: 1.35.0 +--- + +## Release date + +18 November 2024 + +## Features + +* using time based sort when combining BDCT + classic pacts +* upgraded to ruby 3.2.6 + +## Fixes + +* updated packages to fix multiple CVEs + - cross-spawn ( CVE-2024-21538 ) + - rexml (GHSA-2rxp-v6pw-ch6m) + - postgresql14-dev (CVE-2024-10979) + - libpq (CVE-2024-10979) + - libecpg-dev (CVE-2024-10979) + - libecpg (CVE-2024-10979) + - libpq-dev (CVE-2024-10979) + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.36.0.md b/website/docs/docs/on-premises-2x/releases/1.36.0.md new file mode 100644 index 00000000..35f3cd36 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.36.0.md @@ -0,0 +1,23 @@ +--- +title: 1.36.0 +--- + +## Release date + +17 January 2025 + +## Features + +* New AI user permission (NOTE: AI features are not yet available to on-premises customers) + +## Fixes + +* Added validation to publish provider contract endpoint to prevent invalid data +* Support x-www-form-urlencoded validation in bi-directional contract testing + + +## Migration notes + +N/A + + diff --git a/website/docs/docs/on-premises-2x/releases/1.4.0.md b/website/docs/docs/on-premises-2x/releases/1.4.0.md new file mode 100644 index 00000000..32f0aad7 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.4.0.md @@ -0,0 +1,10 @@ +--- +title: 1.4.0 +--- + +## Features + +* Provide an [API stub](https://pactflow.io/blog/hosted-stubs/) for every pact. +* Automatically assign first user to log in as the administrator. +* Allow administrators to assign and unassign the administrator role to other users. +* Allow administrators to disable and enable users. diff --git a/website/docs/docs/on-premises-2x/releases/1.4.1.md b/website/docs/docs/on-premises-2x/releases/1.4.1.md new file mode 100644 index 00000000..2d0bf290 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.4.1.md @@ -0,0 +1,7 @@ +--- +title: 1.4.1 +--- + +## Fixes + +* Fixed the users screen to not overflow text with long email addresses diff --git a/website/docs/docs/on-premises-2x/releases/1.5.0.md b/website/docs/docs/on-premises-2x/releases/1.5.0.md new file mode 100644 index 00000000..8a05a7fa --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.5.0.md @@ -0,0 +1,8 @@ +--- +title: 1.5.0 +--- + +## Features + +* Allow users and applications to be assigned to teams +* Allow applications on dashboard to be filtered by selecting a team diff --git a/website/docs/docs/on-premises-2x/releases/1.6.0.md b/website/docs/docs/on-premises-2x/releases/1.6.0.md new file mode 100644 index 00000000..ed55367e --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.6.0.md @@ -0,0 +1,10 @@ +--- +title: 1.6.0 +--- + +## Features + +- Add all new users and applications to a [Default team](/docs/user-interface/settings/teams#the-default-team). +- Support [Test Maintainer](/docs/permissions/predefined-roles#test-maintainer), [CI/CD](/docs/permissions/predefined-roles#cicd) and [Viewer](/docs/permissions/predefined-roles#viewer) roles. +- Add ["team" scoped permissions](/docs/permissions/#contract_datamanageteam) that allow a user to manage applications that are assigned to their team(s). +- Alter the "Test Maintainer" role to use the new "team" scoped permissions. diff --git a/website/docs/docs/on-premises-2x/releases/1.6.1.md b/website/docs/docs/on-premises-2x/releases/1.6.1.md new file mode 100644 index 00000000..aa0c452c --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.6.1.md @@ -0,0 +1,7 @@ +--- +title: 1.6.1 +--- + +## Fixes + +* Remove unused vulnerable version of Bundler from base Docker image diff --git a/website/docs/docs/on-premises-2x/releases/1.7.0.md b/website/docs/docs/on-premises-2x/releases/1.7.0.md new file mode 100644 index 00000000..49b45869 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.7.0.md @@ -0,0 +1,11 @@ +--- +title: 1.7.0 +--- + +## Release date + +8 December 2020 + +## Features + +* Allow configuration of [multiple SAML providers](/docs/on-premises-2x/authentication/saml#configuring-multiple-saml-providers) diff --git a/website/docs/docs/on-premises-2x/releases/1.8.0.md b/website/docs/docs/on-premises-2x/releases/1.8.0.md new file mode 100644 index 00000000..a502b0d0 --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.8.0.md @@ -0,0 +1,16 @@ +--- +title: 1.8.0 +--- + +## Release date + +18 December 2020 + +## Features + +* Add [menus](/docs/user-interface/dashboard/#version-tag-menus) to application version tags to allow copying of relevant URLs and deletion of associated resources. +* Add screens to display webhook execution logs. + +## Fixes + +* Fix vulnerabilities in base image. diff --git a/website/docs/docs/on-premises-2x/releases/1.9.0.md b/website/docs/docs/on-premises-2x/releases/1.9.0.md new file mode 100644 index 00000000..415bea5f --- /dev/null +++ b/website/docs/docs/on-premises-2x/releases/1.9.0.md @@ -0,0 +1,18 @@ +--- +title: 1.9.0 +--- + +## Release date + +1 February 2021 + +## Features + +* Support [deleting verification results](/docs/how_to#delete-verification-results) through the UI. +* Add Pact Broker/PactFlow version to UI. + +## Fixes + +* Fix cache poisoning vulnerability +* Updated JQuery and Bootstrap libraries +* Fix missing request path in audit logs diff --git a/website/docs/docs/on-premises-2x/scim.md b/website/docs/docs/on-premises-2x/scim.md new file mode 100644 index 00000000..c46ea17e --- /dev/null +++ b/website/docs/docs/on-premises-2x/scim.md @@ -0,0 +1,288 @@ +--- +title: On-Premises SCIM API +--- + +The PactFlow SCIM API can be added as a façade to your on-premises PactFlow instance. It runs in its own +docker container and access the PactFlow APIs using a system account API token. + +For details on the PactFlow SCIM API, refer to the [main SCIM documentation](/docs/scim/main). + +## Installation + +### First + +Before running the SCIM API, you must have a correctly running PactFlow instance that is version 1.26.0 or later. Follow the +[PactFlow On-Premises installation instructions](/docs/on-premises-2x/installation/checklist). + +### Then + +* Configure the SCIM Docker image to be pulled from Quay. Follow the [Docker image registry instructions](/docs/on-premises-2x/docker-image-registry) + to get access to the Quay registry and then run `docker pull quay.io/pactflow/scim-api` to pull down the latest SCIM API image. +* You can then deploy the docker container to your docker orchestration service (AWS ECS, K8, etc.). You need to provide the external URL of +your PactFlow instance as the `PACTFLOW_URL` environment variable to the running container. + +**NOTE: The SCIM API has to access your PactFlow instance using the URL/one of the URLs listed in the [PACTFLOW_BASE_URL](/docs/on-premises-2x/environment-variables#pactflow_base_url) environment variable used for the PactFlow application.** This is due to PactFlow using the HAL media format which uses embedded links in the responses. + +For instance, if your PactFlow instance is running as `https://pactflow.mycompany.com` then you need to the set the +`PACTFLOW_URL` environment variable for the SCIM API to that address. + +### Next + +You can now test the running SCIM API by using a tool like `curl`. First, login to your PactFlow instance and create [a +system account](/docs/user-interface/settings/users#system-accounts) with the [SCIM role](/docs/permissions/predefined-roles#scim) and then copy the system account API token. + +For instance, assuming your PactFlow instance is running as `https://pactflow.mycompany.com` and your SCIM API is +running as `https://pactflow-scim.mycompany.com` with its `PACTFLOW_URL` environment variable set to `https://pactflow.mycompany.com` and +you have copied the SCIM system account API token, you can then run `curl -H 'Authorization: Bearer ' https://pactflow-scim.mycompany.com/Users` +to fetch the users as a SCIM request. + +## Docker Compose example + +Here is an example docker compose setup (modified from the [PactFlow Docker Compose example](/docs/on-premises-2x/docker-compose-example)) +to show how the SCIM API can be setup alongside the PactFlow instance. Run through the [PactFlow Docker Compose example](/docs/on-premises-2x/docker-compose-example) +first, and when that is working you can use this docker compose file to add SCIM as a façade. + +### 1. Authenticating to Quay.io + +Authenticate to Quay.io so that the docker engine is able to fetch our images. + +``` +docker login -u="" -p="" quay.io +docker pull quay.io/pactflow/scim-api +``` + +### 2. Startup PactFlow with SCIM API + +Save the below file as `docker-compose.yml` into a temporary directory and then run `docker-compose up`. Make sure you +have setup the PactFlow license file correctly as per [2. PactFlow license file](/docs/on-premises-2x/docker-compose-example#2-pactflow-license-file). + +```yaml +version: "3" + +services: + simplesaml: + image: kristophjunge/test-saml-idp + logging: + driver: none # comment out the logging config to see the SAML server logs + ports: + - "8080:8080" + - "8443:8443" + environment: + - SIMPLESAMLPHP_SP_ENTITY_ID=https://pactflow.io + - SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://localhost/auth/saml/callback + + pactflow: + image: quay.io/pactflow/enterprise:2.0.0 + depends_on: + - postgres + - redis + environment: + # This is set to localhost for this example but in a real deployment, this needs to be set to the actual URL of the application + - PACTFLOW_BASE_URL=http://localhost + # Insecure setting only for the purposes of this demo! Not to be used in production. + - PACTFLOW_DATABASE_SSLMODE=disable + # Insecure setting only for the purposes of this demo! Not to be used in production. + - PACTFLOW_REQUIRE_HTTPS=false + # Demo auth should only be used for demo purposes. Not to be used in production. + - PACTFLOW_DEMO_AUTH_ENABLED=true + # 'Allow all' for the webhook host whitelist should only be used for demo purposes. See docs for configuring this in production. + - PACTFLOW_WEBHOOK_HOST_WHITELIST=/.*/ + - PACTFLOW_HTTP_PORT=9292 + # Link to the postgres database + - PACTFLOW_DATABASE_URL=postgres://postgres:password@postgres/postgres + - PACTFLOW_LOG_LEVEL=info + - PACTFLOW_ADMIN_API_KEY=admin + - PACTFLOW_MASTER_ENCRYPTION_KEY=thisissomerandombytes + - PACTFLOW_COOKIE_SECRET=at-least-64-char-secret---------at-least-64-char-secret--------- + - PACT_BROKER_ADMIN_API_KEY=admin + - PACTFLOW_HTTP_LOGGING_ENABLED=true + # Link to the redis cache + - REDIS_URL=redis://redis:6379 + # SAML settings + - PACTFLOW_SAML_AUTH_ENABLED=true + - PACTFLOW_SAML_IDP_NAME=Simple SAML + - PACTFLOW_SAML_IDP_SSO_TARGET_URL=http://localhost:8080/simplesaml/saml2/idp/SSOService.php + - PACTFLOW_SAML_IDP_CERT_FINGERPRINT=11:9B:9E:02:79:59:CD:B7:C6:62:CF:D0:75:D9:E2:EF:38:4E:44:5F + - PACTFLOW_SAML_IDP_ID_ATTRIBUTE=uid + - PACTFLOW_SAML_EMAIL_ATTRIBUTE=email + ports: + - "80:9294" + healthcheck: + test: ["CMD", "supervisorctl", "status", "haproxy", "marko", "pactflow"] + interval: 30s + timeout: 10s + retries: 3 + volumes: + - ./pactflow-onprem.lic:/home/pactflow-onprem.lic + ports: + - "80:9292" + healthcheck: + test: ["CMD", "wget", "-nv", "-t1", "--spider", "http://localhost:9292/diagnostic/status/heartbeat"] + interval: 30s + timeout: 10s + retries: 3 + entrypoint: dockerize + command: -wait tcp://postgres:5432 docker-entrypoint + volumes: + - ./pactflow-onprem.lic:/home/pactflow-onprem.lic + + postgres: + image: postgres + healthcheck: + test: psql postgres --command "select 1" -U postgres + ports: + - "5432:5432" + volumes: + - postgres-volume:/var/lib/postgresql/data + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: password + POSTGRES_DB: postgres + + scim-api: + image: quay.io/pactflow/scim-api + depends_on: + - pactflow + environment: + PACTFLOW_URL: "http://pactflow:9292" + LOGGING_LEVEL_ROOT: DEBUG + LOGGING_LEVEL_ORG_APACHE_HC_CLIENT5_HTTP_WIRE: INFO + ports: + - "8100:8080" + + redis: + image: redis:latest + +volumes: + postgres-volume: + +``` + +## 3. Login to PactFlow + +Head to http://localhost in your browser, and choose to login with "SIMPLE SAML", with the username `user1` and password `user1pass`. +Then go to Settings -> API Tokens and COPY an API token. + +## 4. Use Curl and JQ to test access to the SCIM API + +Replace `` below with the API token copied from the last step. + +```console +❯ curl -H 'Authorization: Bearer ' http://localhost:8100/scim/Users | jq + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 1530 100 1530 0 0 3026 0 --:--:-- --:--:-- --:--:-- 3029 +{ + "schemas": [ + "urn:ietf:params:scim:api:messages:2.0:ListResponse" + ], + "totalResults": 2, + "Resources": [ + { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "61cfa5ff-1be6-4e7e-a620-7efac4a370df", + "meta": { + "created": "2022-12-06T03:49:22Z", + "lastModified": "2022-12-06T03:49:29Z", + "resourceType": "User", + "location": "http://localhost:8100/scim/Users/61cfa5ff-1be6-4e7e-a620-7efac4a370df" + }, + "name": { + "formatted": "SCIM" + }, + "displayName": "SCIM", + "userType": "System Account", + "active": true, + "groups": [ + { + "value": "4ac05ed8-9e3b-4159-96c0-ad19e3b93658", + "display": "Default", + "type": "direct", + "$ref": "Groups/4ac05ed8-9e3b-4159-96c0-ad19e3b93658" + } + ], + "roles": [ + { + "value": "c1878b8e-d09e-11ea-8fde-af02c4677eb7", + "display": "CI/CD", + "type": "CI/CD" + }, + { + "value": "cf75d7c2-416b-11ea-af5e-53c3b1a4efd8", + "display": "Administrator", + "type": "Administrator" + } + ] + }, + { + "schemas": [ + "urn:ietf:params:scim:schemas:core:2.0:User" + ], + "id": "aaa3e1a2-3648-4453-b3a6-2195b6822e2d", + "meta": { + "created": "2022-12-06T00:25:56Z", + "lastModified": "2022-12-06T00:25:56Z", + "resourceType": "User", + "location": "http://localhost:8100/scim/Users/aaa3e1a2-3648-4453-b3a6-2195b6822e2d" + }, + "userType": "User", + "active": true, + "emails": [ + { + "value": "user1@example.com", + "primary": true + } + ], + "groups": [ + { + "value": "4ac05ed8-9e3b-4159-96c0-ad19e3b93658", + "display": "Default", + "type": "direct", + "$ref": "Groups/4ac05ed8-9e3b-4159-96c0-ad19e3b93658" + } + ], + "roles": [ + { + "value": "e9282e22-416b-11ea-a16e-57ee1bb61d18", + "display": "User", + "type": "User" + }, + { + "value": "cf75d7c2-416b-11ea-af5e-53c3b1a4efd8", + "display": "Administrator", + "type": "Administrator" + } + ] + } + ] +} +``` + +## Configuration + +### PactFlow URL (Required) + +**Variable:** `PACTFLOW_URL`
+ +This sets the URL that the PactFlow instance is accessed from. + +### Log Level + +**Variable:** `LOGGING_LEVEL_ROOT`
+**Default:** `INFO`
+**Allowed values:** `DEBUG`, `INFO`, `WARN`, `ERROR`
+ +This sets the base log level for the SCIM API container. + +**WARNING: Setting the log level to `DEBUG` will cause all HTTP interactions between the SCIM API and PactFlow to be be logged, +which will include the API tokens in clear text.** To disable logging of the HTTP interactions, set +`LOGGING_LEVEL_ORG_APACHE_HC_CLIENT5_HTTP_WIRE` to `INFO` or greater. + +### Context Path + +**Variable:** `SERVER_SERVLET_CONTEXT_PATH`
+**Default:** `/scim`
+ +This sets the context path that the SCIM API is mounted at. diff --git a/website/docs/docs/on-premises-2x/security-audit-report.md b/website/docs/docs/on-premises-2x/security-audit-report.md new file mode 100644 index 00000000..fb44053f --- /dev/null +++ b/website/docs/docs/on-premises-2x/security-audit-report.md @@ -0,0 +1,199 @@ +--- +title: Security audit report +--- + +## Vulnerability scanning + +PactFlow uses the following tools to ensure the On-Premises image is kept as secure as possible. + +* Bundler Audit +* NPM audit +* Trivy +* Quay Security Scanner +* Amazon ECR Image scanning + +## Reporting vulnerabilities + +To report a vulnerability, please [contact security](https://smartbear.com/security/) and ensure you include the relevant CVE, and the name and/or path to the vulnerable component. + +## Identifying the correct Ruby version + +Many scanning tools have trouble identifying the correct version of Ruby installed on an image because Ruby stores its gems in a directory path that uses the minor version of Ruby (eg. `2.7.0`) rather than the patch version (eg. `2.7.6`). This can be demonstrated by running the following command: + +```shell +docker run --rm -it --entrypoint gem quay.io/pactflow/enterprise:latest environment +``` + +Example output (note the `RUBY VERSION` of `2.7.6` while the `GEM PATHS` use `2.7.0`): + +```shell +RubyGems Environment: + - RUBYGEMS VERSION: 3.1.6 + - RUBY VERSION: 2.7.6 (2022-04-12 patchlevel 219) [x86_64-linux-musl] + - INSTALLATION DIRECTORY: /usr/local/bundle + - USER INSTALLATION DIRECTORY: /root/.gem/ruby/2.7.0 + - RUBY EXECUTABLE: /usr/local/bin/ruby + - GIT EXECUTABLE: + - EXECUTABLE DIRECTORY: /usr/local/bundle/bin + - SPEC CACHE DIRECTORY: /root/.gem/specs + - SYSTEM CONFIGURATION DIRECTORY: /usr/local/etc + - RUBYGEMS PLATFORMS: + - ruby + - x86_64-linux-musl + - GEM PATHS: + - /usr/local/bundle + - /root/.gem/ruby/2.7.0 + - /usr/local/lib/ruby/gems/2.7.0 + - GEM CONFIGURATION: + - :update_sources => true + - :verbose => true + - :backtrace => false + - :bulk_threshold => 1000 + - "install" => "--no-document" + - "update" => "--no-document" + - REMOTE SOURCES: + - https://rubygems.org/ + - SHELL PATH: + - /usr/local/bundle/bin + - /usr/local/sbin + - /usr/local/bin + - /usr/sbin + - /usr/bin + - /sbin + - /bin +``` + +The difficulty that tools have in identifying the correct version of Ruby can lead to false positives being reported. Please check the version of Ruby before submitting a vulnerability report. + +## Identifying the installed gem versions + +To list the gems installed on the PactFlow image run: + +``` +docker run --rm -it --entrypoint gem quay.io/pactflow/enterprise:latest "list" +``` + +## Known vulnerabilities + +### CVE-2015-9284 + +#### Component + +omniauth gem + +#### CVE + +[https://nvd.nist.gov/vuln/detail/CVE-2015-9284](https://nvd.nist.gov/vuln/detail/CVE-2015-9284) + +#### Detectable in versions of PactFlow + +All. + +#### Status + +Non-exploitable. + +#### Notes + +This CVE is a CSRF vulnerability during sign in. This vulnerability is only exploitable if the initial request from the service provider to the identify provider is vulnerable to a CSRF attack because it uses a GET request without any CSRF protection. In PactFlow, this is not possible as PactFlow uses a POST request method with a CSRF token for the initial request to the IDP, as per the mitigation instructions [here](https://github.com/omniauth/omniauth/wiki/Resolving-CVE-2015-9284). + +This can be observed by viewing the source of the login form. + +```html +
+ + +
+``` + +### CVE-2022-2625 + +#### Description + +Given certain prerequisites, this vulnerability allows arbitrary code to be run. + +#### Component + +postgresql14-dev package for Alpine + +#### CVE + +[https://nvd.nist.gov/vuln/detail/CVE-2022-2625](https://nvd.nist.gov/vuln/detail/CVE-2022-2625) + +#### Status + +Non-exploitable. + +#### Notes + +This vulnerability applies to the PostgreSQL server only. The PactFlow Docker image only uses the PostgreSQL client, and hence is not affected by this vulnerability. + +### CVE-2022-37434 + +#### Description + +A heap-based buffer over-read or buffer overflow in inflate in inflate.c via a large gzip header extra field. + +#### Component + +zlib package for Alpine + +#### CVE + +[https://nvd.nist.gov/vuln/detail/CVE-2022-37434](https://nvd.nist.gov/vuln/detail/CVE-2022-37434) + +#### Affected versions of PactFlow + +All. + +#### Status + +Unfixed. + +#### Notes + +As of 24 August 2022, there is no fix available. A patch release of PactFlow will be put out as soon as a fix is available. + +### CVE-2021-41816 + +#### Component + +The cgi library included in Ruby before 2.7.5 and 3.x before 3.0.3, and the [cgi gem](https://rubygems.org/gems/cgi) before 0.3.1. + +#### CVE + +[https://nvd.nist.gov/vuln/detail/CVE-2021-41816](https://nvd.nist.gov/vuln/detail/CVE-2021-41816) + +#### Status + +False positive. + +#### Notes + +This vulnerability only affects platforms that use a 4 byte long data type, typically Windows. The PactFlow base image uses 64 bit Alpine Linux, which uses an [8 byte long](https://www.ibm.com/docs/en/ibm-mq/9.0?topic=platforms-standard-data-types-unix-linux-windows). + +### CVE-2020-36599 + +#### Description + +lib/omniauth/failure_endpoint.rb in OmniAuth before 1.9.2 (and before 2.0) does not escape the message_key value. + +#### Component + +omniauth gem + +#### Status + +Non-exploitable. + +#### Detectable in versions of PactFlow + +Up to and including 1.19.2. + +#### Fixed versions + +1.19.3 and later. + +#### Notes + +PactFlow uses a custom failure endpoint so the vulnerable code is never executed. diff --git a/website/docs/docs/on-premises-2x/support-policy.md b/website/docs/docs/on-premises-2x/support-policy.md new file mode 100644 index 00000000..456b1f17 --- /dev/null +++ b/website/docs/docs/on-premises-2x/support-policy.md @@ -0,0 +1,58 @@ +--- +title: Support policy +--- + +## Versioning + +PactFlow On-Premises follows a [semantic versioning](https://semver.org/) policy for API changes. + +Further to this, any changes to the database schema or configuration that are backwards incompatible (eg. addition of a mandatory configuration setting with no default, or the deletion of a table) will only be introduced in a major version. Migration documentation will be included in the release notes for any major version, and any minor version that introduces optional configuration. + +### Base image upgrades + +Upgrades of the Docker base image will be performed in minor releases (eg. from `alpine3.14` to `alpine 3.15`). PactFlow images will only be supported for Docker versions that are currently [in support](https://docs.docker.com/engine/install/#support) themselves (20.10.0 and later). + +## Support period + +PactFlow application bug fixes will be applied to the latest minor release only. + +Minor versions will receive patches for security vulnerabilities for a period 9 months from the release date. + +## Releases + +Minor version releases are performed at 1-2 month intervals. Major and patch version releases are performed as required according to our versioning policy. + +## Subscribing to updates + +Subscribe to our [RSS](/notices/rss.xml), [Atom](/notices/atom.xml) or [JSON](/notices/feed.json) feeds for updates on new on-premises releases and important security announcements. + +## Asking for help + +Current customers may open a [support ticket](https://support.smartbear.com/pactflow/message/) with the following information: + +* The current version of your PactFlow instance (the version of your application is displayed in the footer. If the application is not able to start, the version of the docker image you are running is sufficient) +* A detailed description of what you're trying to achieve, what your expected outcome is, and what the actual behaviour is. +* The current configuration given to your application +* A log file taken from when the problem occurred, where the application log level has been set to `DEBUG` +* If you're trying to demonstrate a problem or diagnose a bug, the best possible thing you can do is provide a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example). +* Any other information you think could help us diagnose the issue + +### Scope of PactFlow support + +PactFlow is distributed via an industry standard Docker image, meaning that it can be deployed to a wide variety of orchestration tools such as Kubernetes and OpenShift, and runtime environments such as AWS, GCP or Azure. + +Given this flexibility, we are unable to provide support for components that live outside of the PactFlow application as there are too many factors outside of our control to be able to advise you appropriately. + +**Examples of things we can help you with** + +* Application configuration issues +* Interpreting and clarifying application logs +* Diagnosing issues with the application behaviour + +**Examples of things we can't help you with** + +* Networking issues +* Docker orchestration setup (e.g. Helm charts, EKS) +* Cloud or infrastructure automation tools (e.g. Cloudformation, Terraform, Ansible) + +Of course, there are areas where the boundaries are not so clear - such as security reports highlighted by an infosec tool, or issues relating to your IDP or database. This is an area of our shared responsibility and we will do our best to support you. \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/system-requirements.md b/website/docs/docs/on-premises-2x/system-requirements.md new file mode 100644 index 00000000..e5f2b2d8 --- /dev/null +++ b/website/docs/docs/on-premises-2x/system-requirements.md @@ -0,0 +1,135 @@ +--- +title: System requirements +--- + +## Application server instance + +### OS + +Linux + +### Minimum CPU/Memory + +4.0 GiB Memory, 4 vCPUs + +### Disk space usage + +4.0 GiB + +### Docker version + +20.10.0 or later + +## Postgres database instance + +### HA Configuration + +### Configuration + +We would recommend running Postgres as an Active/Passive setup with [streaming replication](https://wiki.postgresql.org/wiki/Replication,_Clustering,_and_Connection_Pooling), or Active/Active setup for the best availability. + +For reference, pactflow.io runs on AWS RDS in [active/passive mode across multiple logical networks](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html), and fails over to the replica when in a failure mode. + +### Minimum CPU/Memory + +4.0 GiB Memory, 4 vCPUs + +### Storage + +5GiB (minimum) +25GiB (recommended) + +### I/O Performance + +* 10 read/s +* 25 write/s + +## Load Balancing + +We recommend running PactFlow on load-balanced infrastructure in at least a 2 node setup to enable high availability and greater throughput. So for clarity, we would recommend running two servers both with 4GiB memory and 4 CPUs for a total capacity of 8GiB Memory and 8 CPUs. + +The PactFlow application is stateless, and therefore sticky sessions do not need to be configured. Use round-robin or least outstanding requests to route to the application servers. + +_NOTE_: Most Pact tooling has retries built-in to handle minor outages communicating to a broker. + +## Scaling and Monitoring + +Below are the key scaling considerations. + +First, make sure you've identified the baseline load and have performed a [load test](installation/load-testing). This will help you to set you boundaries for your scale out and scale in parameters. + +PactFlow is a database intensive application, with the I/O performance of the database being the most critical factor in determining overall system performance. You should setup monitoring for the following metrics: + +* CPU +* Memory +* I/O latency +* Query latency +* Remaining storage space + +Application servers tend to be more CPU bound, but you should look to monitor and scale at least: + +* CPU +* Memory + + +## Benchmarking and Forecasting + +The usage patterns of every customer is different. For example, we have several customers who are among top users of our SaaS platform with less than 30 integrations. + +Things that will affect how the system scales include: + +* Concurrent usage i.e. requests per second (usually by automation systems such as CI/CD) +* CI implementation patterns (e.g. integrations to PactFlow, the use of polling vs webhooks) +* Developer habits (continuous check-in vs bigger commits) causing more or less builds +* Whether you run regular database cleanups (to reduce database storage requirements, and speed up queries) +* The size, variation and stability of contracts +* The interconnectedness of your system +* Database growth + +and so on. These types of data are very hard to collect, measure and predict. + +For forecasting purposes we've created a standard model you can use for projecting storage and compute costs as you grow, which is based on the number of active users* you have on the system. + +_NOTE_: We still recommend using the monitoring and scaling approach (defined above) to automatically scale up/down your system as required. + +_* Active users is defined as a developer that either logs into PactFlow daily or commits code that would trigger a CI build that integrates with Pactflow_ +### Standard Units + +* 1 `compute unit` = 1 CPU, 256 MiB memory +* 1 `database unit` = 1 CPU, 256 MiB memory, 1 GiB storage (per week), 25 writes/s, 10 read/s + +For each 500 active users*, you should increment your total compute capacity by one (1) unit, and _each_ database server capacity by one (1) unit. + + +### Examples + +_**Scenario 1**: 1000 users in year 1_ + +Assuming our database uses active/passive mode and replication. + +Baseline capacity should be 2 x Application Servers each with 4 CPU and 4GiB memory, and a two Postgres database instances (one for the active and passive) each with 4CPU, 4GiB memory, 25GiB volume and 25/10 write/read per second. + +To calculate the number of standard units you need to add: + +``` +new units = expected users / 500 + = 1000 / 500 + = 2 units +``` + +You should therefore add 2 CPUs and 512 MiB to your total compute budget, and add 2 CPUs, 512 MiB of memory and 104 GiB storage capacity to each of your database instances in year 1, for a total budget: + +* **Compute**: 10 CPU, 8.5 GiB RAM (measured by total resources and not physical instances) +* **Database**: 2 x database servers each with 6 CPU, 4.5 GiB RAM, 75 writes/s, 30 read/s, 129 GiB storage + +_**Scenario 2**: Additional 1300 users in year 2_ + +``` +new units = expected users / 500 + = 1300 / 500 + = 3 units (rounded) +``` +You should therefore add 3 CPUs and 768 MiB to your total compute budget, and add 3 CPUs, 768 MiB of memory and 156 GiB storage capacity to each of your database instances in year 2, for a total budget: + +* **Compute**: 13 CPU, 9.25 GiB RAM (measured by total resources and not physical instances) +* **Database**: 2 x database servers each with 9 CPU, 5.25 GiB RAM, 150 writes/s, 60 read/s, 285 GiB storage \ No newline at end of file diff --git a/website/docs/docs/on-premises-2x/troubleshooting.md b/website/docs/docs/on-premises-2x/troubleshooting.md new file mode 100644 index 00000000..39c6c557 --- /dev/null +++ b/website/docs/docs/on-premises-2x/troubleshooting.md @@ -0,0 +1,47 @@ +--- +title: Troubleshooting +--- + +## Manually creating a new administrator + +It happens to the best of us. Perhaps you're locked out because your only Administrator has left, or maybe you disabled them. Whatever it is, here's how you can get back on track: + +1. Login to your Postgres database with the credentials you've setup +2. Find the ID of the user you wish to make an Administrator: + + `select * from saas_users;` + +Grab the ID for the user(s) you wish to make an Administrator. It may be simpler to just initially assign yourself as an Administrator, and then add others via the UI. + +3. Grab the ID of the Administrator role. It should have an ID of 1 and a uuid of `cf75d7c2-416b-11ea-af5e-53c3b1a4efd8`, but best to be sure: + + `select * from pactflow_roles;` + +4. Add a role mapping for the user: + + `insert into pactflow_user_roles ("user_id","role_id") values (, );` + +You are now an Administrator and - assuming you didn't tell anyone - have spared yourself shame and embarrassment. + +## Segmentation fault on launch + +```shell +/home/pact_broker_fork/lib/pact_broker/version.rb:2: [BUG] Segmentation fault at 0x00007efdfbffa000 +ruby 2.7.6p219 (2022-04-12 revision c9c2245c0a) [x86_64-linux-musl] +-- Control frame information ----------------------------------------------- +c:0052 p:---- s:0316 e:000315 CFUNC :RGLoader_load +c:0051 p:0193 s:0311 e:000310 TOP /home/pact_broker_fork/lib/pact_broker/version.rb:2 [FINISH] +``` + +This most frequently happens when your license file isn't mounted correctly. ie. you're trying to mount a **file** as a **folder**, or vice-versa. Be sure to mount your license **file** as a **file** inside the running container. For example, in Docker Compose, you need to have: + +``` +version: "3" +services: + pactflow: + image: quay.io/pactflow/enterprise + volumes: + - ./pactflow-onprem.lic:/home/pactflow-onprem.lic +``` + +Adjust accordlingy depending on your container runtime. diff --git a/website/docs/docs/on-premises-2x/upgrading.md b/website/docs/docs/on-premises-2x/upgrading.md new file mode 100644 index 00000000..ef4886a7 --- /dev/null +++ b/website/docs/docs/on-premises-2x/upgrading.md @@ -0,0 +1,5 @@ +--- +title: Docker image +--- + +TBC diff --git a/website/docs/docs/on-premises-2x/upgrading/database-migrations.md b/website/docs/docs/on-premises-2x/upgrading/database-migrations.md new file mode 100644 index 00000000..df31afaa --- /dev/null +++ b/website/docs/docs/on-premises-2x/upgrading/database-migrations.md @@ -0,0 +1,70 @@ +--- +title: Database migrations +--- + +## Auto migration + +Schema migrations are run automatically on start up, unless the [PACTFLOW_DATABASE_AUTO_MIGRATE](../environment-variables#pactflow_database_auto_migrate) environment variable is set to `false`. Data migrations are also run automatically on start up, after the schema migrations, and ensure that any data inserted into the database by a previous version of the application are migrated. This allows you to perform no-downtime, rolling upgrades across your cluster, ensuring any data inserted into latest database schema by the nodes running the previous version of the application are safely migrated. + +Each schema migration will only ever be applied to the database once. Each data migration is executed during every application start up, as this provides the simplest mechanism for ensuring that all data is correctly migrated during rolling deployments. If this is undesirable, then manual migrations can be performed. + +## Manual migration + +The migrations can be run manually against the database before upgrading the PactFlow Docker image if desired. The `db-migrate` entrypoint will run both the schema and the data migrations. + +```sh +docker pull quay.io/pactflow/enterprise + +# Identify the current version before migrating, in case a rollback is required +docker run --rm \ + --env PACTFLOW_DATABASE_URL="postgres://username:password@host:port/database" \ + --entrypoint db-version \ + quay.io/pactflow/enterprise + +# Perform the migrations +docker run --rm \ + --env PACTFLOW_DATABASE_URL="postgres://username:password@host:port/database" \ + --entrypoint db-migrate \ + quay.io/pactflow/enterprise +``` + +To perform a manual no-downtime deployment that does not rely on the "auto migrate" feature: + +1. Execute the `db-migrate` entrypoint from the Docker image of the desired version. This will run both the schema and data migrations. +2. In the Pactflow application environment variables, set the `PACTFLOW_DATABASE_AUTO_MIGRATE` environment variable to `false`, and update the Pactflow image version to the desired tag. Allow your container management system to apply the rollout of the new Docker image. +3. Execute the `db-migrate` entrypoint again. This will run only the data migrations, as the schema migrations have already run. It is necessary to run the data migrations again to ensure that any data that was inserted into the new schema via the old API (during the rolling upgrade) is correctly migrated. + + +## Rollback + +To perform a manual rollback, first identify the number of the migration target using the PactFlow image with the tag you wish to rollback to. + +```sh +TAG="" +docker run --rm \ + --entrypoint /bin/sh \ + --volume $PWD/pactflow-onprem.lic:/home/pactflow-onprem.lic \ + quay.io/pactflow/enterprise:${TAG} \ + -c "ls /home/pact_broker_fork/db/migrations | grep \d | sort | tail -n 1 | cut -d '_' -f1" +``` + +Then, perform the rollback using the PactFlow image that belongs to the database version currently deployed. + +```sh +TAG="" +docker run --rm \ + --volume $PWD/pactflow-onprem.lic:/home/pactflow-onprem.lic \ + --env PACTFLOW_DATABASE_URL="postgres://username:password@host:port/database" \ + --env PACTFLOW_DATABASE_MIGRATION_TARGET="" \ + --entrypoint db-migrate \ + quay.io/pactflow/enterprise:${TAG} +``` + +## Minor and patch version upgrades + +Upgrades between any minor or patch versions with the same major versions do not need any migration path. + +## Major version upgrades + +For major version upgrades, please upgrade to the most recent patch version of the previous major version before upgrading to the next major version. + diff --git a/website/docs/docs/on-premises/releases/2.0.0.md b/website/docs/docs/on-premises/releases/2.0.0.md new file mode 100644 index 00000000..ee56092c --- /dev/null +++ b/website/docs/docs/on-premises/releases/2.0.0.md @@ -0,0 +1,43 @@ +--- +title: 2.0.0 +--- + +## Release date + +27 June 2025 + +## Introduction + +This major release introduces significant architectural changes and new features, including: + +1. A redesigned user interface +2. Migration to an Ubuntu Linux base image +3. Updated architecture using `HAProxy` for traffic routing and `supervisord` for process management +4. New caching and session management layers requiring a Redis-compatible service +5. Many additional features, fixes, and improvements + +For full details, including installation instructions, refer to the [2.x.x documentation](/docs/on-premises-2x). + +## Features + +- **Major UI update** + - Learn more about PactFlow's redesigned interface and improved navigation in the [UI migration guide](/docs/user-interface/migration/new). + +- **Bi-Directional Contract Testing** + - A new [comparison engine](https://github.com/pactflow/openapi-pact-comparator/) delivers up to 100× faster performance than the [previous engine](https://github.com/pactflow/swagger-mock-validator/). + - Support added for [configurable behavior](/docs/bi-directional-contract-testing/contracts/oas/configuration.md). + +- **Stub server updates** + - Now supports the Pact specification up to version 4. + - Includes additional [configuration options](/docs/stubs). + +## Migration notes + +Please review the following updates when migrating to version 2.0.0: + +1. A [Redis-compatible data store](/docs/on-premises-2x/redis) is now required. +2. `PACTFLOW_COOKIE_SECRET` must now be at least 64 characters. [More info](/docs/on-premises-2x/environment-variables#pactflow_cookie_secret). +3. The `PACTFLOW_LOG_FORMAT` environment variable is deprecated and has no effect. All logs are now output in JSON only. +4. The base image has changed from Alpine Linux to Ubuntu 24.04. If you have customized the image, review your setup and update any installed tools or libraries accordingly. + +> **Note:** There are no breaking API or database changes in this release. All existing API calls, SDKs, and CLI integrations will continue to work as expected. diff --git a/website/notices/2025-06-27-on-premises-2.0.0.md b/website/notices/2025-06-27-on-premises-2.0.0.md new file mode 100644 index 00000000..02761950 --- /dev/null +++ b/website/notices/2025-06-27-on-premises-2.0.0.md @@ -0,0 +1,7 @@ +--- +slug: 2025-06-27-on-premises-2.0.0 +title: On-premises release v2.0.0 +tags: [on-premises, release] +--- + +A new PactFlow on-premises release (2.0.0) is now available ([see details](/docs/on-premises/releases/2.0.0)). \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index ad85c6a8..020eaa02 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -370,7 +370,7 @@ module.exports = { onprem: [ { type: "category", - label: "On-Premises", + label: "On-Premises 1.x", items: [ { type: "category", @@ -438,12 +438,73 @@ module.exports = { type: "category", label: "Troubleshooting", items: ["docs/on-premises/troubleshooting"], + } + ], + }, + { + type: "category", + label: "On-Premises 2.x", + items: [ + { + type: "category", + label: "Installation", + items: [ + "docs/on-premises-2x", + "docs/on-premises-2x/system-requirements", + "docs/on-premises-2x/docker-image-registry", + "docs/on-premises-2x/network-configuration", + "docs/on-premises-2x/installation/migrating", + "docs/on-premises-2x/database", + "docs/on-premises-2x/redis", + "docs/on-premises-2x/logging", + { + type: "category", + label: "Authentication", + items: [ + "docs/on-premises-2x/authentication/demo", + "docs/on-premises-2x/authentication/saml", + ], + }, + { + type: "category", + label: "Application configuration", + items: [ + "docs/on-premises-2x/environment-variables", + "docs/on-premises-2x/environment-variables/templates", + "docs/on-premises-2x/environment-variables/timezones", + "docs/on-premises-2x/license", + ], + }, + "docs/on-premises-2x/docker-compose-example", + "docs/on-premises-2x/installation/load-testing", + "docs/on-premises-2x/installation/checklist", + ], }, { type: "category", - label: "Releases", + label: "Upgrading", + items: ["docs/on-premises-2x/upgrading/database-migrations"], + }, + { + type: "category", + label: "Operation", + items: ["docs/on-premises-2x/authentication"], + }, + { + type: "category", + label: "Maintenance", + items: ["docs/on-premises-2x/maintenance/database"], + }, + { + type: "category", + label: "SCIM", + items: ["docs/on-premises-2x/scim"], + }, + { + type: "category", + label: "Security and support", items: [ - //on-prem-release-placeholder + 'docs/on-premises/releases/2.0.0', 'docs/on-premises/releases/1.36.1', "docs/on-premises/releases/1.36.0", "docs/on-premises/releases/1.35.0", @@ -500,7 +561,73 @@ module.exports = { "docs/on-premises/releases/1.4.0", ], }, + { + type: "category", + label: "Troubleshooting", + items: ["docs/on-premises-2x/troubleshooting"], + }, ], }, + { + type: "category", + label: "Releases", + items: [ + //on-prem-release-placeholder + "docs/on-premises/releases/2.0.0", + "docs/on-premises/releases/1.36.0", + "docs/on-premises/releases/1.35.0", + "docs/on-premises/releases/1.34.0", + "docs/on-premises/releases/1.33.0", + "docs/on-premises/releases/1.32.0", + "docs/on-premises/releases/1.31.0", + "docs/on-premises/releases/1.30.0", + "docs/on-premises/releases/1.29.0", + "docs/on-premises/releases/1.28.0", + "docs/on-premises/releases/1.27.0", + "docs/on-premises/releases/1.26.0", + "docs/on-premises/releases/1.25.0", + "docs/on-premises/releases/1.24.0", + "docs/on-premises/releases/1.23.1", + "docs/on-premises/releases/1.23.0", + "docs/on-premises/releases/1.22.1", + "docs/on-premises/releases/1.22.0", + "docs/on-premises/releases/1.21.1", + "docs/on-premises/releases/1.21.0", + "docs/on-premises/releases/1.20.0", + "docs/on-premises/releases/1.19.2", + "docs/on-premises/releases/1.19.1", + "docs/on-premises/releases/1.19.0", + "docs/on-premises/releases/1.18.0", + "docs/on-premises/releases/1.17.3", + "docs/on-premises/releases/1.17.2", + "docs/on-premises/releases/1.17.1", + "docs/on-premises/releases/1.17.0", + "docs/on-premises/releases/1.16.0", + "docs/on-premises/releases/1.15.0", + "docs/on-premises/releases/1.14.8", + "docs/on-premises/releases/1.14.7", + "docs/on-premises/releases/1.14.6", + "docs/on-premises/releases/1.14.5", + "docs/on-premises/releases/1.14.4", + "docs/on-premises/releases/1.14.3", + "docs/on-premises/releases/1.14.2", + "docs/on-premises/releases/1.14.1", + "docs/on-premises/releases/1.14.0", + "docs/on-premises/releases/1.13.1", + "docs/on-premises/releases/1.13.0", + "docs/on-premises/releases/1.12.0", + "docs/on-premises/releases/1.11.1", + "docs/on-premises/releases/1.11.0", + "docs/on-premises/releases/1.10.0", + "docs/on-premises/releases/1.9.0", + "docs/on-premises/releases/1.8.0", + "docs/on-premises/releases/1.7.0", + "docs/on-premises/releases/1.6.1", + "docs/on-premises/releases/1.6.0", + "docs/on-premises/releases/1.5.0", + "docs/on-premises/releases/1.4.1", + "docs/on-premises/releases/1.4.0", + ], + }, ], }; diff --git a/website/static/img/saas-architecture-2x.png b/website/static/img/saas-architecture-2x.png new file mode 100644 index 00000000..5c00b981 Binary files /dev/null and b/website/static/img/saas-architecture-2x.png differ