Installing Big Picture

This guide covers installing and configuring Big Picture for different deployment models.

Deployment Models

Big Picture supports three primary deployment models:

1. SaaS (Vendor-Hosted) — Multi-tenant service operated by the vendor
2. Vendor Self-Hosted — Single-tenant deployment in vendor infrastructure
3. Local License Server — Air-gapped or regulated customer deployments

Choose the model that fits your requirements.

SaaS (Vendor-Hosted)

If you’re using Big Picture as a SaaS service, installation is handled by your vendor. You’ll receive:

• Control plane endpoint URL
• API credentials or OAuth configuration
• Tenant ID and access scope

Configuration:

1. Obtain your API credentials from your vendor
2. Configure your base URL: https://api.bigpicture.io (or vendor-provided endpoint)
3. Set up OAuth2 client credentials or service account authentication
4. Begin using the API

No server installation required — the vendor manages infrastructure, signing keys, and artifact storage.

Vendor Self-Hosted

Self-host Big Picture in your own infrastructure for full control over keys and data.

Requirements

• Kubernetes cluster (recommended) or VM infrastructure
• PostgreSQL database (version 13+)
• Object storage (GCS, S3, MinIO, or filesystem)
• Key management (Vault, HSM, or file-backed keys)

Installation Steps

1. Prepare Infrastructure

Database:

# Create PostgreSQL database
createdb bigpicture

# Run migrations (provided by Big Picture)
bigpicture migrate --database-url "postgresql://user:pass@host/bigpicture"

Storage: Configure object storage for artifacts. Options:

• Google Cloud Storage (GCS)
• Amazon S3
• MinIO (self-hosted S3-compatible)
• Local filesystem (development only)

Key Management: Set up signing key storage:

• Cloud KMS (GCP, AWS)
• HashiCorp Vault
• Hardware Security Module (HSM)
• File-backed keys (development/testing only)

2. Configure Big Picture

Create a configuration file or set environment variables:

# Deployment mode
export BP_MODE=self_hosted

# Database
export BP_DATABASE_URL="postgresql://user:pass@host/bigpicture"

# Object storage
export BP_STORAGE_TYPE=s3
export BP_STORAGE_BUCKET=bigpicture-artifacts
export BP_STORAGE_REGION=us-east-1

# Key management
export BP_SIGNER_TYPE=vault
export BP_SIGNER_VAULT_ADDR=https://vault.example.com
export BP_SIGNER_KEY_ID=bigpicture-signing-key

# Authentication
export BP_AUTH_PROVIDER=oidc
export BP_OIDC_ISSUER=https://accounts.google.com
export BP_OIDC_CLIENT_ID=your-client-id

3. Deploy the Binary

Kubernetes:

# Deploy using Helm chart (if available)
helm install bigpicture ./helm-chart \
  --set config.databaseUrl=$BP_DATABASE_URL \
  --set config.storageType=$BP_STORAGE_TYPE

# Or use raw manifests
kubectl apply -f k8s/

VM Deployment:

# Download and extract binary
wget https://releases.bigpicture.io/bigpicture-latest.tar.gz
tar xzf bigpicture-latest.tar.gz

# Run as systemd service
sudo cp bigpicture /usr/local/bin/
sudo cp bigpicture.service /etc/systemd/system/
sudo systemctl enable bigpicture
sudo systemctl start bigpicture

4. Verify Installation

Check health endpoint:

curl https://your-bigpicture-instance.com/health

Test API access:

curl -H "Authorization: Bearer $BP_API_TOKEN" \
  https://your-bigpicture-instance.com/v1/products

Configuration Options

Note: Feature flags are not available in V1. These features are enabled by default based on deployment mode. Managed artifacts, snapshots, and licensing are core features that are always available when the deployment mode supports them.

Performance:

• BP_WORKER_THREADS=4 — HTTP worker threads
• BP_DB_POOL_SIZE=10 — Database connection pool size

See Configuration Options for complete reference.

Local License Server (Air-Gapped)

For regulated customers requiring air-gapped operation, deploy a local license server.

Requirements

• LAN-accessible server (VM or container)
• Local signing key (issued by vendor)
• Optional: Outbound entitlement sync capability

Installation Steps

1. Obtain Mirror Credentials

Request mirror credentials from your vendor:

• Mirror credential token
• Allowed channels
• Vendor base URL (for optional sync)

2. Deploy License Server Binary

The license server uses the same binary as the control plane, configured in license-server mode:

# Download binary
wget https://releases.bigpicture.io/bigpicture-latest.tar.gz
tar xzf bigpicture-latest.tar.gz

# Configure license server mode
export BP_MODE=license_server
export BP_LICENSE_SERVER_TENANT_ID=your-tenant-id
export BP_LICENSE_SERVER_SIGNING_KEY_PATH=/path/to/local-key.pem
export BP_LICENSE_SERVER_VENDOR_URL=https://vendor-bigpicture-instance.com  # Optional

3. Configure Local Storage

License servers require minimal storage for lease tokens:

export BP_LICENSE_SERVER_STORAGE_PATH=/var/lib/bigpicture/licenses
mkdir -p $BP_LICENSE_SERVER_STORAGE_PATH

4. Start License Server

# Run as service
sudo systemctl start bigpicture-license-server

# Verify it's running
curl http://localhost:8080/health

Clients configured to use the local license server will request leases from this endpoint instead of the cloud service.

Optional: Outbound Entitlement Sync

If your environment allows outbound HTTPS, configure periodic entitlement sync:

export BP_LICENSE_SERVER_SYNC_ENABLED=true
export BP_LICENSE_SERVER_SYNC_INTERVAL=1h
export BP_LICENSE_SERVER_VENDOR_CREDENTIAL=your-mirror-credential

The license server will periodically sync entitlement changes from the vendor while remaining outbound-only.

Post-Installation

After installation:

1. Create your first product — See Creating Your First Release
2. Configure authentication — Set up OAuth2 or API keys for CI/CD
3. Set up artifact storage — Configure managed storage or external references
4. Import licenses — See Importing Your First License

Troubleshooting

Database connection errors: Verify PostgreSQL is running and accessible. Check connection string format.

Key management errors: Ensure signing keys are accessible and have correct permissions. For cloud KMS, verify IAM roles.

Storage errors: Verify object storage credentials and bucket permissions. Test with a simple upload.

Authentication failures: Check OIDC issuer URL and client configuration. Verify token audience matches your deployment.

Missing Information

The following areas need additional documentation or clarification:

• Helm chart details — Specific Helm chart values and deployment examples
• VM installer — Details on VM-based installation packages mentioned in distribution.md
• Mirror relay setup — Step-by-step guide for setting up vendor-controlled mirrors (separate from license server)
• Key rotation procedures — How to rotate signing keys without breaking existing signatures
• Backup and recovery — Database backup strategies and disaster recovery procedures
• Monitoring and observability — Recommended metrics, logging, and alerting setup