# Distr

> Distr is an open source platform for distributing applications to self-managed customers. The vendor runs Distr in the cloud or self-hosts it, a Distr Controller in each customer environment deploys Docker Compose or Helm applications and an OCI-compatible registry serves the artifacts.

Distr suits software vendors whose customers run the software on their own infrastructure: fully or assisted self-managed, BYOC, air-gapped and edge deployments. A vendor whose software runs only as their own SaaS does not need it.

- Start with the quickstart to run Distr locally with Docker Compose.
- Every Distr instance serves an interactive API reference on `/docs` and the OpenAPI specification on `/docs/openapi.json`, for Distr Cloud at [app.distr.sh/docs](https://app.distr.sh/docs) and [app.distr.sh/docs/openapi.json](https://app.distr.sh/docs/openapi.json).
- Automate Distr with the REST API on `/api/v1`, authenticated with a personal access token, or with the JavaScript SDK `@distr-sh/distr-sdk`.

## Documentation Sets

- [Abridged documentation](https://distr.sh/llms-small.txt): a compact version of the documentation for Distr, with non-essential content removed
- [Complete documentation](https://distr.sh/llms-full.txt): the full documentation for Distr

## Notes

- The complete documentation includes all content from the official documentation
- The content is automatically generated from the same source as the official documentation

## Optional

- [API reference](https://app.distr.sh/docs): the interactive reference of the Distr REST API on Distr Cloud
- [OpenAPI specification](https://app.distr.sh/docs/openapi.json): the machine-readable specification of the Distr REST API on Distr Cloud
- [Nuon Alternative: Distr vs Nuon](https://distr.sh/compare/nuon/): Compare Distr and Nuon for BYOC infrastructure provisioning, application delivery, OpenTofu, Kubernetes, licensing, air-gapped environments and day-two operations.
- [Replicated Alternative 2026: Distr vs Replicated](https://distr.sh/compare/replicated/): Distr is an open-source Replicated alternative for Docker Compose and Kubernetes distribution, offline licensing, air-gapped environments and self-hosting.
- [What is Distr?](https://distr.sh/docs/): Distr is an open source software distribution platform. Software vendors use it to distribute, deploy and manage their software in self-managed, BYOC, air-gapped and edge environments, with visibility and control for both the vendor and the end customer.
- [Core Concepts](https://distr.sh/docs/core-concepts/): Distr's core concepts, including the distribution models it supports, the vendor and customer portals, the artifact registry, deployment controllers, and extensibility through the Distr REST API and SDK.
- [Quickstart](https://distr.sh/docs/quickstart/): Complete three interactive tutorials to set up your registry, deploy your first application, and onboard your first customer.
- [Deployment Controllers](https://distr.sh/docs/controllers/): Overview of Distr deployment controllers: what they are, how they work, and how to manage them from the Vendor Portal.
- [Alerts](https://distr.sh/docs/controllers/alerts/): Monitor deployments and receive email notifications when status changes or resource usage exceeds thresholds.
- [Application](https://distr.sh/docs/controllers/application/): Learn how to create Docker and Helm applications in Distr, add versions, and manage your application templates.
- [Application Links](https://distr.sh/docs/controllers/application-links/): Create dynamic links to deployed applications using environment variables and Helm values as template variables.
- [Deployment](https://distr.sh/docs/controllers/deployment/): Learn how to create deployments for Docker and Helm applications, including the updated deployment flow with customer selection and entitlement management.
- [Run Distr Controllers on macOS](https://distr.sh/docs/controllers/distr-on-macos/): To run Distr controllers on macOS, configure Docker Desktop and reset the Docker context to default. Docker Swarm deployments also need a change to your Docker config.
- [Run Distr Controllers on Windows with WSL2](https://distr.sh/docs/controllers/distr-on-windows-wsl/): Run Distr's Docker controller on Windows by using WSL2 and Docker Engine inside WSL, with optional Windows port forwarding for web-facing applications.
- [Docker Blue-Green Deployments](https://distr.sh/docs/controllers/docker-blue-green-deployments/): Ship downtime-free deployments on Docker. Run two versions of an application side by side on one deployment target, shift traffic between them by weight and roll back instantly.
- [Docker Compose Secrets](https://distr.sh/docs/controllers/docker-compose-secrets/): Use Docker's native secrets mechanism to deliver sensitive values as files inside containers rather than as environment variables.
- [Docker Controller](https://distr.sh/docs/controllers/docker-controller/): How the Distr Docker Compose controller works: installation, core loop, OCI registry authentication, self-updates, Docker Swarm support, and uninstallation.
- [Docker Environment Variables](https://distr.sh/docs/controllers/docker-env/): Create customizable environment variable templates for your Docker applications and let customers configure them before deployment.
- [Helm Chart Registry Authentication](https://distr.sh/docs/controllers/helm-registry-auth/): Configure your Helm charts to support authenticated image pulls from the Distr registry by correctly using imagePullSecrets which enables controller-based credential injection.
- [Infrastructure Controllers](https://distr.sh/docs/controllers/infrastructure-controllers/): Distr infrastructure controllers provision and reconcile cloud infrastructure in customer environments. The OpenTofu controller runs your Terraform configuration as a regular Distr application, for BYOC and any other Terraform use case.
- [Kubernetes Controller](https://distr.sh/docs/controllers/kubernetes-controller/): How the Distr Kubernetes controller works: installation, core loop, OCI registry authentication, self-updates, migrating existing releases, and uninstallation.
- [Logs & Metrics](https://distr.sh/docs/controllers/logs-and-metrics/): Monitor deployment health with controller logs, container logs, deployment status indicators, and host metrics collection in Distr.
- [Pre-Flight Checks](https://distr.sh/docs/controllers/preflight-checks/): Validate target environments before deployment by checking Docker or Kubernetes version, CPU, RAM, disk space and more with custom pre-flight check scripts.
- [Secrets Management](https://distr.sh/docs/controllers/secrets/): Store sensitive configuration values centrally in Distr and reference them in Docker and Kubernetes deployments using template syntax.
- [Update Notifications](https://distr.sh/docs/controllers/update-notifications/): Notify users by email when a new application version or a new artifact version becomes available.
- [FAQs](https://distr.sh/docs/faqs/): Information about the Distr frequently asked questions
- [Free Trial](https://distr.sh/docs/free-trial/): Learn how Distr's 30-day Pro Trial works, what happens when it expires, and how to select a subscription plan.
- [Integrations](https://distr.sh/docs/integrations/): Connect Distr with your existing tools and workflows through our API, SDKs, and integrations.
- [Distr API](https://distr.sh/docs/integrations/api/): The Distr REST API lets you manage your software distribution programmatically, from publishing artifacts and creating customers to triggering deployment updates. It's the same API that powers the Vendor and Customer Portals.
- [Deploying to Amazon ECS](https://distr.sh/docs/integrations/aws-ecs/): Run your application on Amazon ECS in your customers' AWS accounts, with container images pulled straight from the Distr registry and access controlled by artifact entitlements and license keys.
- [GitHub Actions](https://distr.sh/docs/integrations/gh-action/): Automatically create new application versions in Distr whenever you push a release to GitHub, supporting both Docker and Helm applications.
- [Automatic Deployments from GitHub](https://distr.sh/docs/integrations/github-actions/): Automatically create new versions and update customer deployments whenever you push a release to GitHub using the Distr GitHub Action.
- [Creating a Personal Access Token](https://distr.sh/docs/integrations/personal-access-token/): Generate secure access tokens to authenticate with Distr's Registry, API and SDK.
- [Distr SDK](https://distr.sh/docs/integrations/sdk/): Integrate Distr into your applications with our TypeScript/JavaScript SDK for programmatic access to deployments, registries, and more.
- [Air-Gapped Deployments with Distr and Zarf](https://distr.sh/docs/integrations/zarf/): Package your application, Helm chart, and all container images into a single Zarf package, publish it to the Distr registry as an OCI artifact, and let customers deploy it into air-gapped Kubernetes clusters.
- [Distribution Platform](https://distr.sh/docs/platform/): Manage licenses, entitlements, customer access and compliance tools for your software distribution.
- [Application Entitlements](https://distr.sh/docs/platform/application-entitlements/): Learn how to create and manage Application Entitlements to control which application versions your customers can access and deploy.
- [Artifact Entitlements](https://distr.sh/docs/platform/artifact-entitlements/): Learn how to create and manage Artifact Entitlements to control which artifacts and tags your customers can access in your registry.
- [Auto-add Regex](https://distr.sh/docs/platform/auto-add-regex/): Learn how an auto-add regex adds new application versions and artifact tags to an entitlement automatically.
- [Branding](https://distr.sh/docs/platform/branding/): Apply custom branding and content to the Customer Portal, allowing end users to view release notes, deployment instructions, and operational guidance in a vendor-branded interface.
- [Custom Identity Provider](https://distr.sh/docs/platform/custom-identity-provider/): Let your team, your customer portal, or an individual customer sign in to Distr with your own OpenID Connect identity provider (single sign-on), with optional automatic account provisioning.
- [Customer Management](https://distr.sh/docs/platform/customer-management/): A detailed guide to the Customers section of the Vendor Portal: create customers, invite users, manage secrets, and control features per customer.
- [Customer Portal](https://distr.sh/docs/platform/customer-portal/): A white-labeled customer-facing UI for managing deployments, pulling artifacts, viewing licenses, creating support bundles, and managing secrets.
- [Customer Portal Deployments](https://distr.sh/docs/platform/customer-portal/deployments/): Guide for end customers on deploying and managing applications with Distr controllers from the Customer Portal.
- [Customer Portal Licenses](https://distr.sh/docs/platform/customer-portal/licenses/): View and use license keys issued by your vendor directly from the Customer Portal.
- [Customer Portal Artifact Registry](https://distr.sh/docs/platform/customer-portal/registry/): Guide for end customers on using the Customer Portal to access and pull artifacts from the Distr registry.
- [Customer Portal Secrets](https://distr.sh/docs/platform/customer-portal/secrets/): Manage deployment secrets from the Customer Portal to securely store sensitive configuration values.
- [Customer Portal Support Bundles](https://distr.sh/docs/platform/customer-portal/support/): Create and manage support bundles to share diagnostic data with your vendor from the Customer Portal.
- [Kubernetes Compatibility Matrix](https://distr.sh/docs/platform/kubernetes-compatibility-matrix/): Validate your Helm charts against multiple Kubernetes versions in CI/CD, generate compatibility reports, and share them with customers as version resources using the Distr GitHub Action.
- [License Keys](https://distr.sh/docs/platform/license-keys/): Create and manage License Keys to issue signed JWT tokens your application can verify to enforce usage limits, seat counts, and feature access.
- [License Management](https://distr.sh/docs/platform/license-management/): Control which versions of your software each customer can access, enforce usage limits, and generate signed license tokens using Distr's licensing system.
- [Role-Based Access Control (RBAC)](https://distr.sh/docs/platform/rbac/): Understand user roles and permissions, invite users with specific roles, manage access control, and learn how roles differ across subscription plans.
- [Support Bundles](https://distr.sh/docs/platform/support-bundles/): Let customers collect and share diagnostic data with your support team directly from within Distr.
- [Vulnerability Management](https://distr.sh/docs/platform/vulnerability-management/): Track security issues from triage through disclosure, mark the versions they affect, see which customers are impacted and publish security advisories to your customers from within Distr.
- [Vulnerability Scanning](https://distr.sh/docs/platform/vulnerability-scanning/): Scan your application's source dependencies and container images for known vulnerabilities in CI/CD, generate severity-classified reports, and share them with customers as version resources using the Distr GitHub Action.
- [Artifact Registry](https://distr.sh/docs/registry/): The Artifact Registry is a private, OCI-compliant registry built into Distr for publishing container images, Helm charts, and other artifacts to self-managed environments. It includes tag-based access control, a registry UI, and detailed usage insights per customer.
- [Artifact Download Analytics](https://distr.sh/docs/registry/analytics/): Track and analyze artifact pulls across your customer base with filtering by customer, user, IP address, artifact, and version, plus CSV export for reporting.
- [Registry Configuration](https://distr.sh/docs/registry/configuration/): Set up your registry, push your first artifact, and start distributing your software to customers with fine-grained access control.
- [Pull-Through Cache](https://distr.sh/docs/registry/pull-through-cache/): Configure the Distr registry to proxy and cache artifact tags from an upstream OCI-compatible registry.
- [Self-Hosting Distr](https://distr.sh/docs/self-hosting/): Distr can be easily self-hosted in your own environment to use it as an internal software distribution platform and artifact registry.
- [Configuration Reference](https://distr.sh/docs/self-hosting/configuration/): Complete reference of all environment variables used to configure a self-hosted Distr instance, grouped by area.
- [Docker Compose](https://distr.sh/docs/self-hosting/docker/): Run Distr with Docker Compose, from an all-in-one stack for trying it out locally to production reference stacks for AWS and GCP with managed PostgreSQL and object storage.
- [Feature Flags](https://distr.sh/docs/self-hosting/feature-flags/): Enable beta features and customize your Distr instance by managing feature flags in your PostgreSQL database.
- [Kubernetes](https://distr.sh/docs/self-hosting/kubernetes/): Deploy Distr in your Kubernetes cluster with our Helm chart, from a local test install with bundled PostgreSQL and RustFS to production values for EKS on AWS and GKE on GCP.
- [Maintenance Jobs](https://distr.sh/docs/self-hosting/maintenance/): Configure automated cleanup jobs to prune metrics, logs, registry blobs, deleted organizations, orphaned user accounts and unreferenced files from your Distr database and storage.
- [Prometheus Integration](https://distr.sh/docs/self-hosting/prometheus/): Monitor your Distr instance with Prometheus by scraping built-in metrics for deployments, organizations and Go runtime data.
- [Security & Encryption](https://distr.sh/docs/self-hosting/security/): How a self-hosted Distr instance protects the key material it holds, how to rotate it and how to keep it out of your configuration with AWS KMS or GCP Cloud KMS.
- [System Requirements](https://distr.sh/docs/self-hosting/system-requirements/): Distr is written in Go and highly resource efficient. Learn about the recommended resources for self-hosting Distr, the registry and the log processing backend, and what to plan for in production.
- [Choosing a Plan](https://distr.sh/docs/subscription/): Learn which Distr subscription plan is right for you: distributing and operating customer installs, scaling your distribution operation, or building a complete commercial self-hosted delivery suite.
- [Subscription Management](https://distr.sh/docs/subscription-management/): Manage your Distr subscription, add or remove users and customers, view invoices, and handle billing through the Vendor Portal and Stripe.
- [Air-Gapped Deployments](https://distr.sh/docs/use-cases/air-gapped-deployments/): Ship into true air-gapped and restricted networks with Distr. For Kubernetes, build a Zarf package in CI, publish it to Distr, transfer it across the gap, and deploy offline. Docker Compose can follow the same offline transfer pattern.
- [Assisted Self-Managed Deployments](https://distr.sh/docs/use-cases/assisted-self-managed/): Distr controllers assist by running in end-customer environments, they pull application updates, apply configuration changes, report deployment statuses and authenticate automatically to the Distr registry, without granting vendor access to the target environment.
- [Bring Your Own Cloud (BYOC)](https://distr.sh/docs/use-cases/byoc-bring-your-own-cloud/): In BYOC deployments the Distr OpenTofu infrastructure controller provisions and reconciles the infrastructure in the end customer's cloud account, deployed as a regular Distr application. The Distr Kubernetes controller then deploys, manages and updates your application in the cluster it creates.
- [Edge Deployments](https://distr.sh/docs/use-cases/edge-deployments/): Deploy Distr controllers to IoT devices and specialized hardware, once installed, each edge device can be centrally managed and monitored via the vendor portal.
- [Fully Self-Managed Deployments](https://distr.sh/docs/use-cases/fully-self-managed/): In fully self-managed deployments, customers use access tokens to pull artifacts directly from Distr’s private OCI-compliant registry, with a built-in UI in the Customer Portal that displays all available artifacts, no controllers or external dependencies required.
- [Vendor Portal](https://distr.sh/docs/vendor-portal/): Manage your self-managed software distribution from a single control plane with full visibility into deployments, artifacts, licenses, customers, users, and customer portal customization.