Distr – Unified Distribution & Visibility Layer

Distr is an open-source platform for distributing applications & artifacts across heterogeneous customer or internal environments (fully self-managed, BYOC, air‑gapped, and edge) while retaining centralized visibility, governance, and lifecycle control. This tutorial paraphrases and expands upon the official docs: https://distr.sh/docs/getting-started/what-is-distr/ (see source for authoritative reference).

1. Why Distr Matters

Modern software vendors and platform teams must ship containerized applications, Helm charts, configuration bundles, and model/AI artifacts into customer-controlled infrastructure that may be:

Scenario	Challenges	Distr Value
Fully Self-Managed	Customer networks, varied Kubernetes/Docker maturity	Unified packaging, health telemetry
BYOC (Bring Your Own Cloud)	Multi-cloud permutations, IAM variance	Consistent release + license gating
Air-Gapped	No outbound internet, controlled ingress	Offline sync, token-based artifact pulls
Edge Deployments	Constrained compute, intermittent links	Lightweight agent, staged rollouts
Enterprise Internal Distribution	Multiple internal clusters / business units	Central catalog & policy enforcement

2. Core Concepts

Concept	Description
Vendor Portal	Control plane where publishers onboard apps, manage versions, policies, licenses.
Customer Portal	White-labeled interface for end users to deploy, update, view health & status.
Deployment Agent	Component installed in target environment (cluster/host) that pulls instructions and reports status.
Artifact Registry	OCI-compliant storage (container images, Helm charts, Compose bundles, generic assets).
Distribution Models	Modes: fully self-managed, assisted self-managed, BYOC, air-gapped, edge.
Package Formats	Docker images, Helm charts, Docker Compose, generic OCI artifacts.
Licensing & Access Control	Fine-grained entitlement by version/tag or application component.
Observability	Centralized aggregation of deployment status, versions, health metrics.
Branding	White-label customization for customer-facing portal.
API & SDK	Programmatic automation of onboarding, licensing, deployments.

3. High-Level Architecture

          +---------------------+              +------------------------+
          |   Vendor Portal     |              |   Customer Portal      |
          |  (Mgmt UI + API)    |              | (Tenant-scoped UI)     |
          +----------+----------+              +-----------+------------+
                     |                                   |
                     | (Publish, license, assign)        | (Deploy, monitor)
                     v                                   v
              +-------------+                     +-------------+
              | Registry /  |<-(OCI pulls, auth)->| Deployment  |
              | Artifact DB |                     |  Agents     |
              +------+------+                     +------+------+ 
                        ^                                 |
                        | (Health / status callbacks)     |
                        +---------------------------------+

Key flows:

1. Publish: Vendor pushes artifacts (images, charts) & metadata.
2. Entitle: Apply license + access rules per customer or group.
3. Deploy: Customer portal / agent retrieves approved versions.
4. Report: Agents send version, health, consumption metrics.
5. Govern: Vendor monitors fleet state; triggers rollouts or revocations.

4. Supported Distribution Models

Model	Notes	Typical Use
Fully Self-Managed	Customer runs entire stack	Regulated industries
Assisted Self-Managed	Vendor helps bootstrap	Complex enterprise onboarding
BYOC	Artifacts delivered into customer cloud accounts	Cloud neutrality
Air-Gapped	Offline sync (portable media or internal mirror)	Defense, critical infra
Edge	Agents at remote/branch sites	IoT / low-latency workloads

5. Use Cases

Persona	Outcome
ISV / SaaS vendor	Standardize release & license gating across hybrid customers
AI platform	Distribute model servers, vector DB plugins, evaluation bundles
Internal platform team	Curate internal service catalog with lifecycle tracking
Ops / SRE	Fleet upgrade coordination & version drift reporting

6. Installation & Deployment Approaches

Exact commands depend on self-hosting vs SaaS; adapt to official quickstart if deploying production-grade.

6.1 SaaS (Hosted)

1. Sign up on official portal.
2. Create organization / vendor account.
3. Add first application (image + metadata).
4. Invite test customer / internal tenant.

6.2 Self-Hosting (Docker Compose)

Example (simplified skeleton — replace images with real tags and add persistence):

docker-compose.yml

services:
  distr-server:
    image: ghcr.io/glasskube/distr:latest
    environment:
      - DATABASE_URL=postgres://distr:secret@db/distr
      - REGISTRY_URL=http://registry:5000
    ports:
      - "8080:8080"
    depends_on: [db, registry]
  registry:
    image: registry:2
    ports:
      - "5000:5000"
  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=distr
      - POSTGRES_USER=distr
      - POSTGRES_PASSWORD=secret
    volumes:
      - dbdata:/var/lib/postgresql/data
volumes:
  dbdata: {}

6.3 Kubernetes

Use official Helm chart (outline):

helm repo add distr https://distr.sh/helm
helm install distr-platform distr/platform \
  --set registry.enabled=true \
  --set postgres.auth.password=secret

6.4 Air-Gapped Strategy

1. Mirror required container images into internal registry.
2. Export Helm chart + manifests bundle.
3. Transfer via approved medium (e.g., signed USB, secure gateway).
4. Import & deploy using local registry endpoints.

7. Onboarding an Application

Workflow:

1. Prepare OCI image (or Helm chart).
2. Push artifact to Distr-managed or external registry.
3. Define metadata (name, description, category, version constraints).
4. Attach licensing / access tags.
5. Publish version; optionally mark as beta or stable.

Example: Registering via CLI / API (Pseudo)

distr app create --name payment-gateway --display "Payment Gateway" \
  --category core --license-tier enterprise

distr artifact push --app payment-gateway --type helm \
  --file charts/payment-gateway-1.2.0.tgz --version 1.2.0 --channel stable

8. Licensing & Entitlements

Mechanism	Purpose
Version-based licensing	Allow only specific versions per contract
Tag-based access	Grant features via artifact tags (e.g., llm-addon)
Expiration policies	Auto-revoke after term unless renewed
Audit logs (enterprise)	Trace who accessed / deployed what

Policy example (conceptual YAML):

licenses:
  - customer: acme
    app: payment-gateway
    allowed_versions: ["1.2.x", "1.3.x"]
    features: ["analytics", "llm-addon"]
    expires: 2025-12-31

9. Deployment Agents

Agents run in target clusters / hosts to:

• Authenticate & pull approved artifacts
• Apply deployments (Helm install / Docker Compose up)
• Collect status (version, health, last heartbeat)
• Report metrics back (optionally anonymized usage)

Kubernetes example (conceptual):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: distr-agent
spec:
  replicas: 1
  selector: { matchLabels: { app: distr-agent } }
  template:
    metadata:
      labels: { app: distr-agent }
    spec:
      serviceAccountName: distr-agent
      containers:
        - name: agent
          image: ghcr.io/glasskube/distr-agent:latest
          env:
            - name: DISTR_SERVER_URL
              value: https://vendor.example.com
            - name: DISTR_TOKEN
              valueFrom:
                secretKeyRef:
                  name: distr-agent-secret
                  key: token

10. Release & Version Management

Practice	Benefit
Semantic version channels (alpha/beta/stable)	Controlled rollout & feedback cycles
Canary subset of customers	Early detection of regressions
Forced minimum version (security patch)	Reduce vulnerable fleet exposure
Deprecation scheduling	Communicate upgrade timelines

11. Observability & Fleet Visibility

Collected signals (conceptual):

Signal	Use
Deployed version	Drift & compliance tracking
Health status (OK/Warn/Fail)	Rollout gating
Last check-in timestamp	Detect offline agents
Error categories	Prioritize backlog (network vs config)
License consumption	Renewal & upsell analytics

Dashboards highlight % of customers on latest patch, upgrade velocity, error clusters.

12. Security & Compliance

Area	Control
AuthN/AuthZ	Tokens, role-based vendor vs customer scopes
Supply Chain	OCI digests, SBOM attach, signature verification (cosign)
Data Residency	Self-host variant for jurisdiction constraints
Air-Gapped Integrity	Signed bundles, offline verification steps
Secrets Handling	Use K8s secrets or external vault providers

13. Air-Gapped Workflow Deep Dive

Steps:

1. Generate artifact export manifest (includes digests + license file).
2. Export OCI images via skopeo copy or oras pull to tar archives.
3. Transport offline => target network.
4. Rehydrate registry: skopeo copy docker-archive:img.tar docker://registry.local/repo:tag.
5. Apply manifests referencing local registry endpoints.
6. Agent operates in offline heartbeat mode, buffering status until connectivity path (if any) is restored or using manual sync packages.

14. Edge Deployment Considerations

Constraint	Strategy
Limited bandwidth	Delta updates (pull new layers only), schedule off-peak
Intermittent connectivity	Retry with exponential backoff, local caching
Small storage	Multi-stage builds, prune old versions post-upgrade
Latency sensitivity	Co-locate inference/model services at edge site

15. Integration Points

Tool	Integration Idea
GitHub Actions	Auto-publish new image + call Distr API to promote channel
Helm	Charts reference private registry credentials injected by Distr
Docker Compose	Bundle + license gate optional services (e.g., premium module)
SBOM Tools (Syft/Grype)	Attach scan results as artifact metadata
LLM Model Serving	Distribute model weight packages & inference sidecars

16. Automation Pipeline Example

flowchart LR
  A[CI Build] --> B[Security Scan]
  B --> C[Push OCI Artifacts]
  C --> D[Call Distr API: publish]
  D --> E[License Assignment]
  E --> F[Customer Agents Pull]
  F --> G[Health Metrics Return]
  G --> H[Rollout Dashboard]

17. Comparison Snapshot (Conceptual)

Feature	Distr	Generic Registry	Helm Repo Only
Multi Deployment Models	✅	❌	❌
Licensing / Entitlements	✅	❌	❌
Customer Portal	✅	❌	❌
Fleet Health Visibility	✅	❌	❌
Edge / Air-Gap Workflows	✅	Manual	Manual
Branding / White-label	✅	❌	❌

18. Troubleshooting

Symptom	Possible Cause	Action
Agent not reporting	Token invalid / network block	Rotate token, check outbound firewall
Version drift persists	Customer pinned version	Communicate & enforce min version policy
License not applied	Tag mismatch	Verify license spec & artifact tags
Slow air-gap import	Large images unoptimized	Use multi-stage builds & layer reuse
Digest mismatch error	Integrity check fail	Re-export bundle & verify signatures

19. Best Practices

1. Standardize semantic versioning; use channels for progressive rollout.
2. Attach SBOM + signature to every release artifact.
3. Instrument agents with minimal but actionable health metrics (avoid sensitive PII).
4. Keep license definitions declarative (YAML in version control) for change auditing.
5. Automate revocation when security CVEs trigger forced patch policy.
6. Provide sandbox tenants for new customers to shorten onboarding.
7. Maintain compatibility matrix doc (K8s versions, runtime assumptions).
8. Test air-gap export monthly; treat as disaster recovery drill.

20. Learning & Next Steps

• Explore official Core Concepts and Quickstart for hands-on specifics.
• Prototype a minimal self-host (Compose) + single agent cluster.
• Integrate CI pipeline to auto-publish & license new builds.
• Design a rollout policy (alpha → beta → stable) with metrics gating.

---

Attribution: Concepts adapted & paraphrased from the official Distr documentation (see original site for exact wording & updates).
Last reviewed: 2025-09-17

Have org-specific distribution patterns? Add a section or open a PR.