---
component: provenance-governor
version: "1.7"
slug: provenance-governor/setup-deploy-docker
canonical_url: "https://docs.gradle.com/develocity/provenance-governor/1.7/setup-deploy-docker/"
title: "Deployment (Docker)"
description: "Docker deployment instructions for Develocity Provenance Governor."
keywords:
- "installation"
- "configuration"
- "standalone"
status: current
---
# Deployment (Docker)
Develocity Provenance Governor is provided as a container image that can be run directly with Docker. Make sure you have the prerequisites detailed in [Prerequisites](https://docs.gradle.com/develocity/provenance-governor/1.7/setup-prerequisites/) before proceeding.
> [!TIP]
> Looking for Kubernetes deployment? See the Kubernetes Deployment Guide.
## Audience
This guide is written for a Platform / Infrastructure Engineer. It assumes:
* Basic familiarity with Docker (containers, volumes, networks)
* Ability to obtain a Develocity license file (`develocity.license`)
* Access to a Develocity instance and an attestation storage backend (Artifactory or Amazon S3)
* (Optional) Ability to configure a reverse proxy for TLS termination
## Quickstart
Want to get started quickly with a local Docker deployment?
See the [Docker Quickstart Guide](https://docs.gradle.com/develocity/provenance-governor/1.7/quickstart-docker/) for condensed setup instructions.
The quickstart will guide you through:
* Authenticating with the container registry
* Running Develocity Provenance Governor with Docker
* Configuring a local S3 store and Develocity integration
* Verifying the deployment
After completing the quickstart, return to the sections below to configure additional features like signing keys, OIDC authentication, and policies.
## Deployment Flow Overview
The recommended order is:
1. [Authenticate with the container registry](#registry-authentication)
2. [Create the configuration directory structure](#directory-structure)
3. [Add the license file](#license-setup)
4. [Run the container](#run-container)
5. [Verify rollout & logs](#verification)
6. [Configure Develocity instance(s)](#develocity-deploy) (required)
7. [Configure attestation storage](#attestation-storage-deploy) — S3 or Artifactory (required)
8. [Enable authentication](#authentication-deploy) (required for API access)
9. [Configure signing keys](#signing-keys-deploy) (recommended)
10. [Define policies](#policies-deploy)
11. [Configure TLS with a reverse proxy](#tls-reverse-proxy) (recommended for production)
Estimated setup time:
* **Local Docker (Quickstart)**: 15-30 minutes
* **Production setup with all integrations**: 1-3 hours (depending on external service coordination and TLS setup)
## Authenticate with the Container Registry
Log in to `registry.gradle.com` to pull the product image. Your Develocity license file is used for authentication.
```bash
cat ./develocity.license | docker login registry.gradle.com -u user --password-stdin
```
`--password-stdin` avoids Docker’s insecure-password warning and keeps the license out of shell history.
## Create the Configuration Directory Structure
Develocity Provenance Governor reads configuration from four directories mounted into the container:
| Directory | Purpose | Required |
| --- | --- | --- |
| license/ | Develocity product license file | Yes |
| secrets/ | Sensitive values (access tokens, private keys) | Yes |
| properties/ | Non-sensitive configuration (URIs, public keys) | Yes |
| policies/ | Policy manifests (YAML) | No |
Create the directory structure:
```bash
mkdir -p ./dpg-config/license ./dpg-config/secrets ./dpg-config/properties ./dpg-config/policies
```
Each directory is mounted into the container at `/workspace/config/`. Configuration files placed in these directories use the same property key formats described in the [Application Configuration](https://docs.gradle.com/develocity/provenance-governor/1.7/app-config-overview/) section.
## Add the License File
Copy your Develocity license into the license directory.
```bash
cp ./develocity.license ./dpg-config/license/develocity.license
```
## Run the Container
Start Develocity Provenance Governor with the configuration directories mounted as read-only volumes.
```bash
docker run -d \
--name provenance-governor \
-p 8080:8080 \
-p 9090:9090 \
-v "$(pwd)/dpg-config/license:/workspace/config/license:ro" \
-v "$(pwd)/dpg-config/secrets:/workspace/config/secrets:ro" \
-v "$(pwd)/dpg-config/properties:/workspace/config/properties:ro" \
-v "$(pwd)/dpg-config/policies:/workspace/config/policies:ro" \
registry.gradle.com/develocity/provenance-governor:1.7.1
```
Port mappings:
* **8080** - Main API port (application traffic)
* **9090** - Monitoring port (actuator health, readiness, liveness, and Prometheus metrics)
**Verify Startup:**
```
docker logs provenance-governor 2>&1 | grep -i license
```
**Expected log lines:**
```
Develocity license enabled, with license [...]
Started ProvenanceGovernor in ...
```
If startup fails:
* Verify the license file exists at `./dpg-config/license/develocity.license`
* Check `docker logs provenance-governor` for detailed error messages
## Verify the Deployment
**Check container status:**
```
docker ps --filter name=provenance-governor
```
You should see the container in a `Up` state.
**Check application logs:**
```
docker logs provenance-governor --tail=50
```
Look for messages indicating:
* License loaded successfully
* Integrations enabled (e.g., "Develocity support enabled", "Artifactory support enabled")
* Policies loaded (if configured)
* No error messages
**Test API accessibility:**
```
curl -i http://localhost:8080
```
You should receive a `401 Unauthorized` response, which confirms the application is running and authentication is required.
> [!NOTE]
> The actuator endpoints (health, readiness, liveness, prometheus) are exposed on port 9090. Develocity Provenance Governor also exposes /livez and /readyz endpoints on the main application port (8080) for health checking.
## Configure Develocity Instances
Develocity Provenance Governor uses Develocity Build Scan data to generate attestations. At least one Develocity instance must be configured.
Add Develocity configuration to your properties and secrets files.
**Add Develocity URI to ./dpg-config/properties/application.yml:**
```
develocity:
instances:
MY_INSTANCE: (1)
uri: "https://develocity.example.com"
```
1. MY_INSTANCE is an identifier you choose. Use alphanumeric characters, dashes, or underscores.
**Add Develocity access key to ./dpg-config/secrets/application.yml:**
```
develocity:
instances:
MY_INSTANCE:
access-key: "DEVELOCITY_ACCESS_KEY"
```
**Restart to apply configuration:**
```
docker restart provenance-governor
```
**Verify:**
```
docker logs provenance-governor 2>&1 | grep -i "Develocity support enabled"
```
Expected log:
```text
Develocity support enabled, for instance [MY_INSTANCE:https://develocity.example.com]
```
Troubleshooting: Repeated `Retrying [n/10] request …` indicates connectivity or credential issues.
See [Develocity Instance Configuration](https://docs.gradle.com/develocity/provenance-governor/1.7/app-config-develocity/) for advanced options.
## Configure Attestation Storage
Develocity Provenance Governor requires at least one attestation storage backend. You can use **Amazon S3**, **JFrog Artifactory**, or both simultaneously.
### Amazon S3
Add S3 configuration to your properties and secrets files.
**Add S3 properties to ./dpg-config/properties/application.yml:**
```
s3:
instances:
MY_S3: (1)
region: "us-east-1"
bucket-name: "acme-attestations-bucket"
```
1. MY_S3 is an identifier you choose for this S3 instance.
**Add S3 credentials to ./dpg-config/secrets/application.yml:**
```
s3:
instances:
MY_S3:
access-key-id: "AKIA..."
secret-access-key: "..."
```
> [!NOTE]
> Static credentials are shown for simplicity. For production use, you can also configure IAM role assumption or use environment-based credentials by passing AWS environment variables to the container (e.g., -e AWS\_ROLE\_ARN=…). See S3 Configuration for all authentication options.
### JFrog Artifactory
Add Artifactory configuration to your properties and secrets files.
**Add Artifactory URI to ./dpg-config/properties/application.yml:**
```
artifactory:
instances:
MY_ARTIFACTORY: (1)
uri: "https://artifactory.example.com"
```
1. MY_ARTIFACTORY is an identifier you choose for this Artifactory instance.
**Add Artifactory token to ./dpg-config/secrets/application.yml:**
```
artifactory:
instances:
MY_ARTIFACTORY:
access-token: "ARTIFACTORY_ACCESS_TOKEN"
```
**Restart and verify:**
```
docker restart provenance-governor
docker logs provenance-governor 2>&1 | grep -i "support enabled"
```
Expected log lines (depending on which backends are configured):
```text
Develocity support enabled, for instance [MY_INSTANCE:https://develocity.example.com]
S3 support enabled, for instance [MY_S3:...]
Artifactory support enabled, for instance [MY_ARTIFACTORY:https://artifactory.example.com]
```
See [Attestation Storage Configuration](https://docs.gradle.com/develocity/provenance-governor/1.7/app-config-attestation-storage/) for advanced options.
## Authentication
Supported schemes:
* [RFC9110 Basic](https://datatracker.ietf.org/doc/html/rfc9110#section-11.1)
* [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) + [OAuth 2.0](https://openid.net/specs/openid-connect-core-1_0.html#RFC6749)
### Enable Basic Authentication
Add identities to the secrets configuration file.
**Add a Basic Identity to ./dpg-config/secrets/application.yml:**
```
basic:
identities:
some-user: "{noop}some-pass"
```
Recommendation: Replace `{noop}` with `{bcrypt}` and supply a bcrypt-hashed password for production.
**Restart and verify:**
```
docker restart provenance-governor
docker logs provenance-governor 2>&1 | grep -i "Basic Identity support"
```
**Expected log line:**
```
Basic Identity support enabled, for identity [some-user]
```
### Enable OIDC Authentication
OIDC Providers are dynamically discovered based on token issuers specified in policies. See the [Policies](#policies-deploy) section for examples.
## Configure Signing Keys
Attestations are wrapped in a [Dead Simple Signing Envelope (DSSE)](https://github.com/secure-systems-lab/dsse/blob/master/background.md) signed by a key pair.
### Create Ed25519 Key Pair
Recommended (128-bit security, small key sizes/signatures).
```bash
openssl genpkey -algorithm Ed25519 -out private-key.pem
openssl pkey -in private-key.pem -pubout -out public-key.pem
```
### Add Keys to Configuration
The private key goes in secrets and the public key goes in properties.
You can add signing keys as individual files (one file per key) using the property key naming convention.
**Add private key to secrets:**
```
cp private-key.pem ./dpg-config/secrets/signing.key.FRIENDLY_KEY_NAME.private-pem
```
**Add public key to properties:**
```
cp public-key.pem ./dpg-config/properties/signing.key.FRIENDLY_KEY_NAME.public-pem
```
Choose a naming convention like `_YYYY-MM-DD` for rotation clarity.
**Restart and verify:**
```
docker restart provenance-governor
docker logs provenance-governor 2>&1 | grep -i "Signature support enabled"
```
**Expected log:**
```
Signature support enabled, for key pair [name:FRIENDLY_KEY_NAME:keyid:XXXXXX:signing-algorithm:ed25519]
```
Key ID is a 6-character abbreviation of the SHA-256 digest of the public key.
### Other Supported Algorithms
Elliptic Curve (ECDSA) and RSA are also supported. Substitute commands below; follow the same secrets/properties procedure.
#### Elliptic Curve (prime256v1)
```bash
openssl ecparam -name prime256v1 -genkey -noout -out ec_private.key
openssl pkcs8 -topk8 -inform PEM -in ec_private.key -outform PEM -nocrypt -out private-key.pem
openssl ec -in ec_private.key -pubout -out public-key.pem
```
Expected log algorithm: `SHA256withECDSA`.
#### RSA (2048)
```bash
openssl genrsa -out private-key.pem 2048
openssl rsa -in private-key.pem -pubout -out public-key.pem
```
Expected log algorithm: `SHA256withRSA`.
## Policies
Policies are YAML documents stored as files in the `policies` directory. Each file should end with `.yaml`.
### Access Control Policies
Define who can do what on which resources.
`identityMatchingStrategy` supported:
* `withBasicIdentity` — must match a key under `basic.identities.` in secrets
* `withOidc` — relies on issuer discovery; ensure network accessibility
`canPerform` supported actions:
* `publish-attestations` - publish DSSE-wrapped attestations to an Attestation Store (e.g., Artifactory)
* `publish-policy-scans` - publish Policy Scan™ results to an Attestation Store
`withResources` supported patterns:
* `pkg:pkg-type/pkg-namespace/pkg-name@pkg-version` - specific Package URL pattern to match or use wildcards:
* `pkg:maven/**/**` - all Maven packages (both namespace and artifact name wildcarded)
* `pkg:oci/**/**` - all OCI packages (container images)
* `pkg:maven/org.example/**@**` - all Maven packages in `org.example` namespace and any version
* `pkg:maven/org.example/acme-app@1.0.0` - specific Maven package
* `pkg:oci/image-name@v1*` - specific OCI image with wildcard version
* `dv:REPLACE_WITH_DV_INSTANCE_NAME/*` - allow reading build scans from the Develocity instance to source data for attestations.
af:REPLACE\_WITH\_ARTIFACTORY\_INSTANCE\_NAME/ - allow publishing attestations to the Artifactory instance. Replace the trailing with a repository name to restrict access further.* `s3:REPLACE_WITH_S3_INSTANCE_NAME/*` - allow publishing attestations to the S3 instance.
To grant an identity access to every configured resource (not recommended for production), enumerate all four resource types explicitly:
```yaml
withResources:
- "pkg:*/*/*"
- "dv:*/*"
- "af:*/*"
- "s3:*/*"
```
#### Basic Identity Policy Example
**Create ./dpg-config/policies/basic-identity-some-user-full-access.yaml:**
```
apiVersion: policy.gradle.com/v1
kind: AccessControl
metadata:
name: basic-identity-some-user-full-access
spec:
identityMatchingStrategy:
withBasicIdentity:
- withName: "some-user"
canPerform:
- publish-attestations
- publish-policy-scans
withResources:
- "pkg:*/*/*"
- "dv:*/*"
- "af:*/*"
- "s3:*/*"
```
#### OIDC Policy Example (GitHub Actions)
**Create ./dpg-config/policies/oidc-github-action-full-access.yaml:**
```
apiVersion: policy.gradle.com/v1
kind: AccessControl
metadata:
name: oidc-github-action-full-access
spec:
identityMatchingStrategy:
withOidc:
- fromIssuerUri: https://token.actions.githubusercontent.com
withClaims:
job_workflow_ref: org/automation-repo/.github/workflows/build-image.yml@*
canPerform:
- publish-attestations
- publish-policy-scans
withResources:
- "pkg:*/*/*"
- "dv:*/*"
- "af:*/*"
- "s3:*/*"
```
### Public Key Verification Policy Example
**Create ./dpg-config/policies/public-key-verification-policy.yaml:**
```
apiVersion: policy.gradle.com/v1
kind: TrustedPublicKeys
metadata:
name: public-keys
spec:
resultsLabels: []
description: Public keys trusted for attestations.
remediation: Update the list of trusted public keys to ensure only verified attestations are accepted.
keys:
DEPLOYMENT_KEY_2025_10_01:
pem: |
-----BEGIN PUBLIC KEY-----
....
-----END PUBLIC KEY-----
```
Replace `DEPLOYMENT_KEY_2025_10_01` and the PEM block with your actual trusted public keys, for example the ones used to sign attestations.
**Restart and verify:**
```
docker restart provenance-governor
docker logs provenance-governor 2>&1 | grep -i "Loading Policy Resource from file"
```
**Expected log lines:**
```
Loading Policy Resource from file [/workspace/config/policies/public-key-verification-policy.yaml]
```
## TLS with a Reverse Proxy
For production environments, place a TLS-terminating reverse proxy in front of the Develocity Provenance Governor container. Common options include:
* **nginx** or **Caddy** as a reverse proxy
* A cloud load balancer (e.g., AWS ALB, GCP Cloud Load Balancing)
**Example: nginx reverse proxy configuration:**
```
server {
listen 443 ssl;
server_name provenance-governor.example.com;
ssl_certificate /etc/nginx/ssl/cert.pem;
ssl_certificate_key /etc/nginx/ssl/key.pem;
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### Honoring Forwarded Headers
When Develocity Provenance Governor runs behind a reverse proxy or tunnel, you must configure it to honor the proxy’s `Forwarded` and `X-Forwarded-*` headers so generated URLs reflect the public-facing address. This matters most for the `verifier` field that Develocity Provenance Governor records on every Verification Summary Attestation. Without this setting, the `verifier` field reports the internal container address and downstream consumers cannot distinguish a legitimate public-URL attestation from one carrying an internal address.
Add the `SERVER_FORWARD_HEADERS_STRATEGY=NATIVE` environment variable to the `docker run` command:
```bash
docker run -d \
--name provenance-governor \
-p 8080:8080 \
-p 9090:9090 \
-e SERVER_FORWARD_HEADERS_STRATEGY=NATIVE \
-v "$(pwd)/dpg-config/license:/workspace/config/license:ro" \
-v "$(pwd)/dpg-config/secrets:/workspace/config/secrets:ro" \
-v "$(pwd)/dpg-config/properties:/workspace/config/properties:ro" \
-v "$(pwd)/dpg-config/policies:/workspace/config/policies:ro" \
registry.gradle.com/develocity/provenance-governor:1.7.1
```
> [!NOTE]
> This step is not required when running on Kubernetes. Every Kubernetes pod receives a KUBERNETES\_SERVICE\_HOST environment variable that triggers forwarded-header handling automatically.
#### Verify Forwarded Headers Are Honored
After adding the environment variable and restarting the container, issue a request through the reverse proxy’s public URL that triggers Policy Scan™ evaluation, then inspect the resulting Verification Summary Attestation. The `verifier` field must reflect the public-facing scheme and host, not the internal container address.
#### Trust Boundary
Setting `SERVER_FORWARD_HEADERS_STRATEGY=NATIVE` tells Develocity Provenance Governor to trust every `Forwarded` and `X-Forwarded-*` header it receives. The reverse proxy in front of Develocity Provenance Governor must:
* Strip any inbound `Forwarded` and `X-Forwarded-*` headers that arrived from the external client (those are untrusted and can be used to spoof the recorded `verifier` field)
* Add its own `Forwarded` or `X-Forwarded-*` headers reflecting the actual client connection
Develocity Provenance Governor does not perform trusted-proxy validation by IP or any other means. Every major reverse-proxy product (nginx, Traefik, AWS ALB, Kubernetes ingresses, Cloudflare Tunnel, ngrok) supports the header-stripping configuration; consult the proxy’s documentation for the specific directive.
## Troubleshooting
### Container Fails to Start
**Check logs for startup errors:**
```
docker logs provenance-governor
```
Common issues:
* **Missing license**: Ensure `./dpg-config/license/develocity.license` exists and is mounted correctly.
* **Invalid configuration**: Check for YAML syntax errors in your configuration files.
* **Port conflicts**: If port 8080 or 9090 is already in use, map to different host ports (e.g., `-p 9080:8080`).
### Configuration Changes Not Taking Effect
Configuration files are read at startup. After modifying any files in `./dpg-config/`, restart the container:
```bash
docker restart provenance-governor
```
**Verify the restart:**
```
docker logs provenance-governor --tail=20
```
### Container Cannot Reach External Services
If the container cannot connect to Develocity, Artifactory, or S3:
* Verify the URIs in your properties configuration
* If using Docker networks, ensure the container is on the correct network
* Check DNS resolution inside the container:
```bash
docker exec provenance-governor nslookup develocity.example.com
```
### Configuration Error Example
```text
***************************
APPLICATION FAILED TO START
***************************
Failed to bind properties under 'artifactory.instances.INSTANCE_NAME_GOES_HERE' ... Reason: java.lang.IllegalArgumentException: uri must not be null
```
Remediation:
* Missing URI — add the URI to `./dpg-config/properties/application.yml`
* Missing token — add the token to `./dpg-config/secrets/application.yml`
After fixing, restart:
```bash
docker restart provenance-governor
```
## Verification and Next Steps
After completing the deployment, verify that Develocity Provenance Governor is running correctly:
1. **Check Container Status**
```bash
docker ps --filter name=provenance-governor
```
You should see the container in `Up` state.
2. **Check Application Logs**
```bash
docker logs provenance-governor --tail=50
```
Look for messages indicating: **License loaded successfully** Integrations enabled (e.g., "Develocity support enabled", "Artifactory support enabled") **Policies loaded (if configured)** No error messages
3. **Test API Accessibility**
```bash
curl -i http://localhost:8080
```
You should receive a `401 Unauthorized` response, which confirms the application is running and authentication is required.
4. **Verify Integration Configuration**
Check that your configured integrations were loaded:
```bash
docker logs provenance-governor 2>&1 | grep "support enabled"
```
> [!TIP]
> Successfully deployed? If all verification steps passed and you’re ready to start using Develocity Provenance Governor, proceed to Publishing Attestations to learn how to publish attestations and evaluate policies.
**What to Do Next:**
* **Configure Signing Keys** — If you haven’t already, set up signing keys for attestation integrity. See [Configure Signing Keys](#signing-keys-deploy).
* **Write Your First Policy** — Define policies for your software supply chain governance. See [Writing Policies](https://docs.gradle.com/develocity/provenance-governor/1.7/writing-policies/).
* **Publish Test Attestations** — Try publishing attestations for a test package. See [Publishing Attestations](https://docs.gradle.com/develocity/provenance-governor/1.7/publishing-attestations/).
* **Integrate with CI/CD** — Add Develocity Provenance Governor to your build and deployment pipelines. See [GitHub Actions](https://docs.gradle.com/develocity/provenance-governor/1.7/ci-cd-integration/#github-actions) or [CI/CD Integration](https://docs.gradle.com/develocity/provenance-governor/1.7/ci-cd-integration/).
If you encounter issues, consult the [Troubleshooting](https://docs.gradle.com/develocity/provenance-governor/1.7/troubleshooting/) section.
## Summary Cheat Sheet
| Integration | Secrets File Key | Properties File Key | Required | Notes |
| --- | --- | --- | --- | --- |
| License | (file) develocity.license | n/a | Yes | Placed in license/ directory |
| Develocity Instance | develocity.instances..access-key | develocity.instances..uri | Yes | Multiple supported |
| Attestation Storage (S3) | s3.instances..access-key-id + s3.instances..secret-access-key | s3.instances..region + s3.instances..bucket-name | At least one storage backend required | Or use IAM/env credentials |
| Attestation Storage (Artifactory) | artifactory.instances..access-token | artifactory.instances..uri | At least one storage backend required | Token preferred |
| Signing Key (Private) | signing.key..private-pem | n/a | Recommended | PEM file |
| Signing Key (Public) | n/a | signing.key..public-pem | Recommended | PEM file |
| Basic Identity | basic.identities. | n/a | Yes (for API access) | {bcrypt} recommended |
| Policies | n/a | n/a (files in policies/ directory) | Recommended | YAML files |