# Distr: a self-hosted control plane for shipping software into customer infrastructure

> Distr is an Apache-2.0 Go control plane that pushes Docker Compose, Docker Swarm and Helm applications into customer-managed environments, with agents, a white-label portal and a built-in OCI registry. It fits vendors with self-managed or BYOC customers, and it is heavier than a plain registry.

**distr-sh/distr** — The Open Source control plane for self-hosted, BYOC, and on-prem deployments. Everything you need to distribute applications to self-hosted customers out of the box. Supporting Docker Compose, Docker Swarm and Helm based applications.

- Repository: https://github.com/distr-sh/distr
- Website: https://distr.sh/docs/
- Stars: 1,233 · Forks: 53
- Language: Go
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/distr-sh-distr

## The problem Distr solves: software that has to run on someone else's servers

Selling software that customers install themselves turns a product company into a distribution company. Every customer needs the artifact, a version that matches their contract, installation instructions for their platform, and a way to send you logs when something breaks. Most teams handle this with a container registry, a wiki page and email. Distr replaces that combination with one control plane.

The README names the target audience directly: software and AI companies that distribute applications to self-managed customers. The listed use cases are on-premises, VPC and self-managed deployments, BYOC automation, and edge or fleet management. That is a specific shape of customer. If your users sign up on your website and never see a server, Distr has nothing to do for you.

The features that matter for that audience are license management (distributing specific versions to specific customers), a white-label customer portal so customers control their own deployments, and a built-in OCI registry with access control and analytics. Each of those maps to a task that would otherwise be a bespoke script or a support ticket.

## How the Hub, agents and the OCI registry fit together

The repository README includes a Mermaid architecture diagram, and it is the clearest statement of the design. The control plane side contains four pieces: the Distr Hub itself, PostgreSQL, Loki for log storage, and the Distr OCI registry backed by object storage. That is one deployment, either Distr's hosted service or your own.

On the customer side the diagram splits into two groups. In the first, a Distr Agent runs inside the customer cloud and talks to the Hub; the agent is what actually manages your application. In the second, a fully self-managed customer uses a plain OCI client against the registry and runs no agent at all. That second path is the important one commercially: a customer who refuses to install an agent can still pull images and charts, and you still know which version they were granted.

Agents are optional, per the README, which describes them as prebuilt Helm and Docker agents that manage deployments, collect logs and metrics, and allow remote troubleshooting. Without an agent you get artifact distribution and licence control. With an agent you get the deployment automation and the observability loop. The Go module list in go.mod backs this up: it depends on compose-spec/compose-go, docker/compose, containers/image and the moby client, so the agent really does drive Docker and Compose rather than shelling out to a wrapper.

## Installing the Hub with Docker Compose

The README documents a tarball-based quickstart for Docker. The command downloads the latest release's quickstart bundle and unpacks it into a new directory. After it runs you should see a deploy directory containing a .env file and a Compose file; the README tells you to make the necessary changes to .env before starting.

```bash
mkdir distr && cd distr && curl -fsSL https://github.com/distr-sh/distr/releases/latest/download/deploy-quickstart.tar | tar -x
# make necessary changes to the .env file
docker compose up -d
```

Once the stack is up, the README says to register the first account at http://localhost:8080/register. That port is the Hub's web UI and API entry point in the quickstart deployment.

The repository also carries a docker-compose.yaml for local development, and it is worth reading before you plan a production deployment, because it shows what the Hub expects to sit next to it: PostgreSQL 18, a RustFS object store, Grafana Loki in monolithic mode, and Mailpit for outbound mail. The Loki service comment states that it stores deployment and deployment target log records and persists chunks and a TSDB index into a rustfs bucket named loki, created by a pre_start init container that requires Docker Compose 5.3.0 or newer. If your Compose version is older than that, the log storage will not come up cleanly.

## Installing on Kubernetes and registering a first artifact

For Kubernetes the README gives a single Helm command against the OCI chart in ghcr.io. The --wait flag makes Helm block until the release is ready, and the two --set flags turn on the bundled PostgreSQL and RustFS object storage so a test install works without external dependencies.

```bash
helm upgrade --install --wait --namespace distr --create-namespace \
  distr oci://ghcr.io/distr-sh/charts/distr \
  --set postgresql.enabled=true --set rustfs.enabled=true
```

The README is explicit that this default is for testing only: for production you should revisit all available configuration values, which are listed in the chart's values.yaml on Artifact Hub. Treat the two --set flags as a starting point, not a deployment plan.

After the Hub is reachable, the workflow the README implies is: connect a customer, create an artifact version, and either let an agent deploy it or hand the customer registry credentials. The README does not walk through artifact creation step by step, so the quickstart at distr.sh/docs/quickstart/ is the place to look for that sequence. For CI, the project publishes a GitHub Action at distr-sh/distr-create-version-action that automates artifact version creation, which is the piece that keeps version numbers in the Hub aligned with your build pipeline.

If you would rather drive the Hub from code, the REST API reference lives at app.distr.sh/docs and the first-party SDK is published on npm.

```bash
npm install --save @distr-sh/distr-sdk
```

The README states the SDK is currently available for JavaScript only, with more languages on the roadmap.

## Where Distr is the wrong tool, and what the README does not cover

The clearest limitation is operational weight. A Distr Hub is a Go service plus PostgreSQL, plus Loki, plus object storage, plus an OCI registry, and the customer side may add an agent. If your product is a single binary that customers run on one VM, you are trading a download link and a changelog for a four-service stack. That is a bad trade unless you have enough customers that manual distribution hurts.

The second limitation is platform coverage. The README points macOS users at a dedicated macOS guide and Windows users at a WSL2 guide for agents. That phrasing suggests agents are native to Linux environments and that other platforms go through a documented workaround. If your customers run Windows Server without WSL2, check the agent documentation before assuming support.

The third is versioning of the project itself. The repository's package.json declares version 4.0.0 while the most recent published releases are 3.5.1, 3.5.0 and 3.4.2, all from early September 2026. That gap is normal in a repository that builds community and enterprise frontend configurations from one tree, but it means the npm package version and the release tag you install from ghcr.io do not move in lockstep. Pin the chart or image tag you tested rather than following latest.

Finally, the README does not document data export, a migration path off the Hub, or rollback of a failed agent-driven deployment. Those may exist in the docs site, but nothing in the repository material confirms them, so treat them as open questions to answer before you commit.

## Distr compared with a plain OCI registry plus scripts

The obvious alternative is the combination most teams already have: a container registry such as Harbor or GHCR for artifacts, a config management tool or a Helm repository for installation, and a spreadsheet for entitlements. The difference in approach is that a registry is stateless with respect to your customers. It stores bytes and answers pull requests; it does not know which customer is entitled to which version, and it cannot tell you whether the deployment succeeded.

Distr puts a database and an agent between the artifact and the customer. The registry inside Distr still speaks OCI, which is why a fully self-managed customer with no agent can pull from it, but the Hub records the grant. That is what makes licence management and per-customer version pinning possible at all.

The cost of that difference is that Distr becomes part of your delivery path. If the Hub is down, agents cannot reconcile and customers cannot fetch new versions. A plain registry has the same failure mode for pulls, but no state to lose. If your distribution needs are simply "publish an image and let anyone pull it", a registry plus a well-written install script is less to operate and less to break.

## Licence, maintenance and what upgrading actually involves

Distr is licensed under Apache-2.0, and the LICENSE file sits at the repository root. That is a permissive licence, so you can self-host, modify and redistribute the Hub, and the README separately points to a hosted version and enterprise plans at distr.sh/pricing/. The practical question for a commercial user is which parts of the codebase are compiled into the community build versus the enterprise build, because package.json defines separate production-community and production-enterprise Angular configurations. The README does not enumerate the difference, so read the pricing page and the build configurations before you assume a feature is in the open source build. This is a description of the licence text, not legal advice.

On maintenance, the repository is not archived and the last push was on 2026-09-10, with release 3.5.1 tagged the day before. Releases arrive frequently, and the repository carries release-please configuration and a Renovate config, which indicates automated dependency updates and changelog generation. The CHANGELOG.md at the root is generated by that tooling.

Upgrade cost depends on which install path you chose. With Helm, the upgrade is the same command you installed with, pointed at a new chart version, and the --wait flag will surface a failed rollout. With Docker Compose, you replace the bundle and run docker compose up -d again. Either way you are upgrading a stateful system: PostgreSQL migrations are handled by golang-migrate, which appears in go.mod, and schema migrations are the part of an upgrade that is hardest to reverse. Take a database dump before you move between minor versions, and test the migration against a copy of production data rather than against the quickstart's empty database.

## Conclusion

Adopt Distr if your customers run their own infrastructure and you are tired of hand-written install guides, one-off upgrade emails and a spreadsheet of who runs which version. Do not adopt it if you only ship a SaaS product, or if you cannot operate PostgreSQL, object storage and Loki alongside it, because the Hub is not a single static binary. Before committing, verify three things: whether the agent-based automation covers your target platform (the README points macOS and Windows WSL2 users at separate guides), what the community build leaves out relative to the enterprise build, and how you will export your data if you move off it, since the README does not document a migration or export path.

## FAQ

### What is Distr and who is it for?

Distr is an Apache-2.0 software distribution platform that lets software and AI companies distribute applications to self-managed customers. It is aimed at teams shipping into on-premises, VPC, BYOC or edge environments rather than at teams running a pure SaaS product.

### How do I install Distr?

The README gives two paths. For Docker, download the deploy-quickstart.tar release asset, unpack it, edit the .env file and run docker compose up -d. For Kubernetes, install the OCI Helm chart from ghcr.io/distr-sh/charts/distr, optionally with postgresql.enabled and rustfs.enabled set to true for a test setup.

### Which deployment formats does Distr support?

The repository description names Docker Compose, Docker Swarm and Helm based applications, and the README describes optional prebuilt Helm and Docker agents that manage deployments and collect logs and metrics.

### Does Distr require an agent in the customer environment?

No. The architecture diagram shows two customer paths: one where a Distr Agent runs in the customer cloud and manages the application, and one where a fully self-managed customer uses a plain OCI client against the registry with no agent. Agents are described as optional in the README.

### What is the Distr SDK available for?

The README states the first-party SDK is currently available for JavaScript only and installs from npm as @distr-sh/distr-sdk, with more languages on the roadmap. A REST API reference is also published at app.distr.sh/docs.

## Sources

- [distr-sh/distr on GitHub](https://github.com/distr-sh/distr)
- [License: Apache-2.0](https://github.com/distr-sh/distr/blob/main/LICENSE)
- [Project website](https://distr.sh/docs/)
- [README](https://github.com/distr-sh/distr/blob/main/README.md)
- [Releases](https://github.com/distr-sh/distr/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/distr-sh-distr