---
component: provenance-governor
version: "1.7"
slug: provenance-governor/quickstart-docker
canonical_url: "https://docs.gradle.com/develocity/provenance-governor/1.7/quickstart-docker/"
title: "Quickstart (Docker)"
description: "Get Develocity Provenance Governor running locally in under 10 minutes using Docker."
keywords:
  - "installation"
  - "configuration"
  - "standalone"
status: current
---

<!-- llms-index: https://docs.gradle.com/develocity/llms.txt -->

# Quickstart (Docker)

<a id="preamble"></a>

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

> [!NOTE]
> 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.

> [!TIP]
> 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.

<a id="step-1-authenticate-with-the-container-registry"></a>

## Step 1: Authenticate with the Container Registry

Log in to the Gradle container registry using your Develocity license file.

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

Expected output: `Login Succeeded`

> [!TIP]
> \--password-stdin avoids Docker’s insecure-password warning and keeps the license out of your shell history.

<a id="step-2-create-the-configuration-directory-structure"></a>

## Step 2: Create the Configuration Directory Structure

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

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

<a id="step-3-add-the-license-file"></a>

## Step 3: Add the License File

Copy your Develocity license into the configuration directory.

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

<a id="step-4-create-a-docker-network"></a>

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

```bash
docker network create dpg-network
```

<a id="step-5-start-localstack-for-s3-attestation-storage"></a>

## 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`

<a id="step-6-configure-the-application"></a>

## Step 6: Configure the Application

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

> [!IMPORTANT]
> 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/acme-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
```

<a id="step-7-start-develocity-provenance-governor"></a>

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

```bash
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.7.1
```

> [!TIP]
> Running behind a reverse proxy or tunnel (ngrok, Cloudflare Tunnel, nginx)? Add -e SERVER\_FORWARD\_HEADERS\_STRATEGY=NATIVE to the docker run command above. Without this, Develocity Provenance Governor records the internal container address on every Verification Summary Attestation instead of the public-facing URL. See TLS with a Reverse Proxy for the full deployment guidance, including trust-boundary expectations.

<a id="step-8-verify-the-installation"></a>

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

> [!NOTE]
> 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.

<a id="step-9-test-the-endpoint"></a>

## Step 9: Test the Endpoint

Verify the service is accessible on port 8080.

```bash
curl -i http://localhost:8080
```

Expected output:

```text
HTTP/1.1 401 Unauthorized
...
```

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

<a id="step-10-test-attestation-publishing-and-build-gate-verification"></a>

## 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/acme-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/acme-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).

<a id="success"></a>

## Success!

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

<a id="whats-next"></a>

## What’s Next?

<a id="essential-configuration"></a>

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

<a id="need-help"></a>

### Need Help?

*   **Full Documentation**: [Complete Docker Deployment Guide](https://docs.gradle.com/develocity/provenance-governor/1.7/setup-deploy-docker/)
    
*   **Troubleshooting**: Check logs with `docker logs provenance-governor`
    
*   **Clean Up**: Stop and remove containers, and optionally the configuration directory and pulled images:
    
    ```bash
    # 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.7.1 \
               localstack/localstack:3.0.0 \
               amazon/aws-cli
    ```