Quickstart (Docker)

Get Develocity Provenance Governor running locally in under 10 minutes using Docker.

Prerequisites:

Docker installed
macOS or Linux (for bash commands)
jq installed (used in Step 10 to format JSON responses)
Your Develocity license file saved as develocity.license in your current directory
A reachable Develocity instance URL and access key (required by Step 10)

On Apple Silicon (M1/M2/M3), the provenance-governor image runs under Rosetta emulation because it is published for linux/amd64. Docker Desktop handles this automatically; expect slower startup on first run.

This quickstart creates a local, non-production environment with HTTP-only access for testing. For production deployments, see the complete Docker Deployment Guide.

Looking for a Kubernetes-based quickstart? See the Kubernetes Quickstart.

Step 1: Authenticate with the Container Registry

cat ./develocity.license | docker login registry.gradle.com -u user --password-stdin

Expected output: Login Succeeded

--password-stdin avoids Docker’s insecure-password warning and keeps the license out of your shell history.

Step 2: Create the Configuration Directory Structure

Develocity Provenance Governor reads configuration from files mounted into the container. Create the required directory structure.

mkdir -p ./dpg-config/license ./dpg-config/secrets ./dpg-config/properties ./dpg-config/policies

Step 3: Add the License File

Copy your Develocity license into the configuration directory.

cp ./develocity.license ./dpg-config/license/develocity.license

Step 4: Create a Docker Network

Create a Docker network so the Develocity Provenance Governor container can communicate with LocalStack (used for S3 attestation storage in this quickstart).

docker network create dpg-network

Step 5: Start LocalStack for S3 Attestation Storage

Develocity Provenance Governor requires an attestation store (S3 or Artifactory) to function. For this quickstart, we use LocalStack to simulate an S3 bucket.

Start LocalStack

docker run -d \
  --name localstack \
  --network dpg-network \
  -p 4566:4566 \
  localstack/localstack:3.0.0

Wait for LocalStack to be ready

until curl -sf http://localhost:4566/_localstack/health > /dev/null; do
  echo "Waiting for LocalStack..."
  sleep 2
done

Create an S3 bucket

docker run --rm --network dpg-network \
  -e AWS_ACCESS_KEY_ID=test \
  -e AWS_SECRET_ACCESS_KEY=test \
  -e AWS_REGION=us-east-1 \
  amazon/aws-cli \
  --endpoint-url=http://localstack:4566 \
  s3 mb s3://dpg-bucket

Expected output: make_bucket: dpg-bucket

Step 6: Configure the Application

Create configuration files for Develocity integration, S3 storage, and basic authentication.

You must substitute a reachable Develocity instance URL and a valid Develocity access key in the two files below. The placeholder values (https://develocity.example.com, YOUR_DEVELOCITY_ACCESS_KEY) cause DNS-resolution and access-token errors in the logs and prevent Step 10 from succeeding.

Create properties configuration (replace https://develocity.example.com with your Develocity instance URL)

cat > ./dpg-config/properties/application.yml <<'EOF'
develocity:
  instances:
    main:
      uri: "https://develocity.example.com"

s3:
  instances:
    local-s3:
      region: "us-east-1"
      endpoint: "http://localstack:4566"
      bucket-name: "dpg-bucket"
      path-style-access: true
EOF

Create secrets configuration (replace YOUR_DEVELOCITY_ACCESS_KEY with your actual key)

cat > ./dpg-config/secrets/application.yml <<'EOF'
develocity:
  instances:
    main:
      access-key: "YOUR_DEVELOCITY_ACCESS_KEY"

s3:
  instances:
    local-s3:
      access-key-id: "test"
      secret-access-key: "test"

basic:
  identities:
    admin: "{noop}admin"  # {noop} is Spring Security's "no-op" prefix meaning the password is stored in plain text — only suitable for local testing
EOF

Create access control and build policies

cat > ./dpg-config/policies/access-control.yaml <<'EOF'
apiVersion: policy.gradle.com/v1
kind: AccessControl
metadata:
  name: admin-full-access
spec:
  identityMatchingStrategy:
    withBasicIdentity:
      - withName: "admin"
  canPerform:
    - publish-attestations
    - publish-policy-scans
    - read-attestations
  withResources:
    - "s3:local-s3/*"
    - "pkg:maven/*/*"  # Matches any Maven package (namespace + artifact). "pkg:maven/*" alone does not match namespaced coordinates like pkg:maven/com.example/my-app.
EOF

cat > ./dpg-config/policies/scan-build.yaml <<'EOF'
apiVersion: policy.gradle.com/v1
kind: PolicyScanDefinition
metadata:
  name: build
spec:
  description: Validate the software package against the build gate policies.
  policy-selector:
    match-labels:
      gate: build
EOF

cat > ./dpg-config/policies/policy-require-build-tool.yaml <<'EOF'
apiVersion: policy.gradle.com/v1
kind: AttestationsExist
metadata:
  name: require-build-tool
  labels:
    gate: build
spec:
  description: Ensure Build Tool attestation exists
  remediation: Fix build
  matchingStrategy: must-match
  expectedPredicates:
    - https://gradle.com/attestation/build-tool/v1
EOF

Step 7: Start Develocity Provenance Governor

Run the Develocity Provenance Governor container with the configuration directories mounted. Two ports are exposed: 8080 serves the application API, and 9090 serves the Spring Boot Actuator endpoints (health, readiness, liveness, and Prometheus metrics).

docker run -d \
  --name provenance-governor \
  --network dpg-network \
  -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.6.0

Step 8: Verify the Installation

Check the application logs to confirm startup

docker logs provenance-governor 2>&1 | head -n 50

Confirm these startup messages appear:

Develocity license enabled - License loaded
Develocity support enabled - Develocity integration active
S3 support enabled - S3 storage configured
Basic Identity support enabled - Authentication active

If you did not replace the placeholder Develocity URL and access key in Step 6, you will also see recurring DnsResolveContext retries and DevelocityAccessTokenManager: Error refreshing access tokens errors. These are expected with placeholder values and will stop once the URL and access key in ./dpg-config/properties/application.yml and ./dpg-config/secrets/application.yml point to a real Develocity instance. Restart the container after editing: docker restart provenance-governor.

Step 9: Test the Endpoint

Verify the service is accessible on port 8080.

curl -i http://localhost:8080

Expected output:

HTTP/1.1 401 Unauthorized
...

A 401 Unauthorized response means the service is running correctly. You just need to provide credentials in the next steps.

Step 10: Test Attestation Publishing and Build Gate Verification

Now, publish an attestation and run the build Policy Scan™. This simulates a "Build Gate" check. If the scan passes (meaning the require-build-tool policy is satisfied), a Verification Summary Attestation (VSA) will be automatically generated and published.

Replace YOUR_BUILD_SCAN_ID with a valid Build Scan ID from your Develocity instance (e.g., 3skbdg5fgcgha). The SHA256_DIGEST can be any 64-character hex string for this test, but you must use the same value in both the attestation publishing and Policy Scan steps below.

The final command pipes the response through jq to pretty-print it — install jq first if you haven’t already (see Prerequisites).

Publish an attestation

SHA256_DIGEST="73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497" # Placeholder
BUILD_SCAN_ID="YOUR_BUILD_SCAN_ID" # Replace with a real ID like 3skbdg5fgcgha
DPG_URL="http://localhost:8080"

curl -v -u admin:admin \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "sha256=$SHA256_DIGEST" \
  -d "repositoryUrl=repo.example.com/maven2" \
  -d "buildScan.ids=$BUILD_SCAN_ID" \
  "$DPG_URL/packages/maven/com.example/my-app/1.0.0/attestations"

Expected output: Look for HTTP/1.1 200 OK and a JSON response detailing successes for attestation storage.

Run the 'build' Policy Scan

SHA256_DIGEST="73f482a2296dcc654c380979aae3916a1925ff906b1c43a0659f97fd56e44497" # Must match above
DPG_URL="http://localhost:8080"

# Run the 'build' policy scan.
# If successful, this will generate a VSA confirming the package passed the build gate.
POLICY_SCAN_RESULT=$(curl -v -u admin:admin \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "sha256=$SHA256_DIGEST" \
  -d "repositoryUrl=repo.example.com/maven2" \
  "$DPG_URL/packages/maven/com.example/my-app/1.0.0/policy-scans/build")

echo "$POLICY_SCAN_RESULT" | jq .

Expected output: The JSON response will include a PolicyScanDefinition result. If the scan passed, it will contain an attestationUri pointing to the newly generated Verification Summary Attestation (VSA).

Success!

Your Develocity Provenance Governor instance is now running locally with Docker.

What’s Next?

Essential Configuration

To make your instance production-ready, configure these key features:

Feature	Description	Guide
Authentication	Add Basic Auth or OIDC to secure your instance	Configure Auth
Signing Keys	Enable cryptographic signing of attestations	Setup Keys
Policies	Define access control and verification rules	Create Policies
Integrations	Connect to Develocity and Artifactory instances	Develocity / Artifactory
HTTPS/TLS	Secure communication with a reverse proxy	Setup TLS

Feature

Description

Guide

Authentication

Add Basic Auth or OIDC to secure your instance

Configure Auth

Signing Keys

Enable cryptographic signing of attestations

Setup Keys

Policies

Define access control and verification rules

Create Policies

Integrations

Connect to Develocity and Artifactory instances

Develocity / Artifactory

HTTPS/TLS

Secure communication with a reverse proxy

Setup TLS

Need Help?

Full Documentation: Complete Docker Deployment Guide
Troubleshooting: Check logs with docker logs provenance-governor

Clean Up: Stop and remove containers, and optionally the configuration directory and pulled images:

# Required: remove containers and network
docker rm -f provenance-governor localstack
docker network rm dpg-network

# Optional: remove the local configuration directory
rm -rf ./dpg-config

# Optional: remove the pulled images
docker rmi registry.gradle.com/develocity/provenance-governor:1.6.0 \
           localstack/localstack:3.0.0 \
           amazon/aws-cli