Skip to content
Big Picture

Distributing Artifacts

This workflow covers distributing software artifacts to clients through Big Picture. Artifacts are distributed via signed update decisions and can be served from managed storage or external URLs.

Prerequisites

Section titled “Prerequisites”
  • A published release with verified artifacts
  • Artifacts accessible via URL (managed storage or external)
  • Clients configured to query update decisions
  • Network access between clients and artifact storage

Understanding Distribution Methods

Section titled “Understanding Distribution Methods”

Big Picture supports two distribution methods:

  1. Managed storage — Artifacts stored in Big Picture’s object storage
  2. External references — Artifacts hosted externally (S3, GCS, JFrog, etc.)

Both methods work with the same update decision API. Clients receive artifact URLs in signed decisions.

Step 1: Ensure Artifacts Are Accessible

Section titled “Step 1: Ensure Artifacts Are Accessible”

Verify artifacts are accessible at their URLs:

For external artifacts:

Terminal window
curl -I "https://artifacts.example.com/releases/v1.0.0/installer.msi"

For managed artifacts:

Terminal window
curl -I "${BP_BASE_URL}/v1/artifacts/art_abc123/download"

Ensure:

  • URLs are accessible from client networks
  • HTTPS is enabled
  • Authentication is configured if required

Step 2: Publish Release

Section titled “Step 2: Publish Release”

Publish a release with artifacts. Clients query update decisions to receive artifact URLs:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/releases" \
  -H "Authorization: Bearer $BP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_xyz789",
    "version": "1.0.0",
    "channel": "stable",
    "artifacts": [
      {
        "artifact_id": "art_abc123",
        "platform": "windows",
        "arch": "x86_64",
        "installer_type": "msi",
        "requires_admin": true
      }
    ]
  }'

Step 3: Clients Query Update Decisions

Section titled “Step 3: Clients Query Update Decisions”

Clients query the update decision API to receive artifact URLs:

Terminal window
curl -X POST "${BP_BASE_URL}/v1/decision" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "product_id": "prod_xyz789",
        "current_version": "0.9.0",
        "channel": "stable",
        "tenant_id": "tenant_abc123",
        "platform": "windows",
        "arch": "x86_64"
      }
    ]
  }'

Response:

{
  "decisions": [
    {
      "product_id": "prod_xyz789",
      "action": "INSTALL",
      "version": "1.0.0",
      "artifact_ref": "art_abc123",
      "artifact_url": "https://artifacts.example.com/releases/v1.0.0/installer.msi",
      "artifact_sha256": "a1b2c3d4e5f6...",
      "platform": "windows",
      "arch": "x86_64",
      "rationale": "Policy: AUTO_INSTALL",
      "signature": "v4.public.eyJ..."
    }
  ],
  "signed_at": "2024-01-15T10:30:00Z"
}

Clients verify the signature before downloading artifacts.

Step 4: Clients Download Artifacts

Section titled “Step 4: Clients Download Artifacts”

Clients download artifacts from the provided URL:

Terminal window
curl -O "https://artifacts.example.com/releases/v1.0.0/installer.msi"

Clients verify the SHA-256 hash matches before installing.

Distribution via Mirrors

Section titled “Distribution via Mirrors”

For regulated environments, use vendor-controlled mirrors:

  1. Generate snapshot — See Generating Snapshots
  2. Mirror syncs snapshot — Mirror pulls snapshot and artifacts
  3. Clients query mirror — Clients query local mirror instead of cloud

Mirrors provide the same update decision API but serve artifacts locally.

Configuring External Artifact Storage

Section titled “Configuring External Artifact Storage”

When using external storage, ensure:

Access control:

  • URLs are publicly accessible or use pre-signed URLs
  • Authentication tokens are included if required
  • CORS is configured for browser-based clients

Performance:

  • Use CDN for global distribution
  • Enable compression (gzip, brotli)
  • Configure caching headers

Security:

  • Use HTTPS for all artifact URLs
  • Verify artifact hashes match
  • Sign artifacts with code signing certificates

Configuring Managed Storage

Section titled “Configuring Managed Storage”

When using managed storage:

Storage backend:

  • Configure object storage (S3, GCS, Azure Blob)
  • Set up access policies
  • Configure lifecycle rules

Access URLs:

  • Managed artifacts are served via Big Picture API
  • URLs include authentication tokens
  • URLs expire after a set period

Monitoring Distribution

Section titled “Monitoring Distribution”

Monitor artifact distribution:

Check download metrics:

Terminal window
curl "${BP_BASE_URL}/v1/artifacts/art_abc123/metrics" \
  -H "Authorization: Bearer $BP_API_TOKEN"

Monitor decision API:

  • Track decision API requests
  • Monitor download success rates
  • Alert on distribution failures

Troubleshooting

Section titled “Troubleshooting”

Clients cannot download artifacts:

  • Verify artifact URLs are accessible
  • Check network connectivity
  • Verify authentication if required

Hash mismatches:

  • Re-verify artifact hashes
  • Check for corruption during transfer
  • Re-upload artifacts if needed

Slow downloads:

  • Use CDN for external artifacts
  • Optimize artifact sizes
  • Enable compression

Best Practices

Section titled “Best Practices”

Use CDN: Distribute artifacts via CDN for better performance.

Verify hashes: Always verify artifact hashes before installing.

Monitor distribution: Track download metrics and success rates.

Use mirrors: Use mirrors for regulated or air-gapped environments.

Secure storage: Use HTTPS and secure authentication for artifact storage.

Next Steps

Section titled “Next Steps”