### Install and Run Docker Agent Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/docker-agent.mdx Installs the agent by fetching a Docker Compose file from the Distr Hub and starting it. Ensure you replace ``, ``, and `` with your specific values. ```bash curl "https:///api/v1/connect?targetId=&targetSecret=" | docker compose -f - up -d ``` -------------------------------- ### Run Distr for Development Source: https://github.com/distr-sh/distr/blob/main/CONTRIBUTING.md Start the necessary containers and the Distr Hub for local development. Ensure Docker and mise are installed. ```shell # Start the database and a mock SMTP server docker compose up -d # Start Distr Hub mise watch serve -r ``` -------------------------------- ### Generate Distr Agent Setup Command Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/tutorials/agents/agents-tutorial.component.html Execute this command in your terminal to start the Distr agent and connect it to the Distr Hub. The command contains sensitive information and is shown only once. ```bash `{{ connectCommand }}` ``` -------------------------------- ### Install Dependencies with Mise Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/support/vulnerability-scanning.mdx Use 'mise install' to set up the necessary tools for local vulnerability scanning if you are managing your environment with Mise. ```bash mise install ``` -------------------------------- ### Docker Config JSON Example Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/setup-on-macos.mdx An example of the Docker `config.json` file after removing the `credStore` line. Ensure no trailing comma is left. ```json { "auths": {} } ``` -------------------------------- ### Conditional Display for MFA Setup Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/user-settings/user-settings.component.html Displays QR code and manual setup key information when MFA setup data is available. ```html @else if (mfaSetupData(); as mfaSetupData) { Scan the QR code below with your authenticator app and enter the generated code to enable MFA. Setup key for manual configuration: `{{ mfaSetupData.secret }}` Enable } ``` -------------------------------- ### Install Kubernetes Agent Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/kubernetes-agent.mdx Apply the manifests to install the Distr Kubernetes agent. Ensure the namespace exists and replace placeholders with your target ID and secret. ```bash kubectl apply -n -f "https:///api/v1/connect?targetId=&targetSecret=" ``` -------------------------------- ### Install Distr SDK for JavaScript Source: https://github.com/distr-sh/distr/blob/main/README.md Install the Distr SDK for JavaScript using npm. This is the first step to interacting with Distr from your application code. ```shell npm install --save @distr-sh/distr-sdk ``` -------------------------------- ### Push Hello-World Image to OCI Registry Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/artifacts/artifacts/artifacts.component.html Example commands to pull, tag, and push the 'hello-world' image to your OCI registry. Ensure you are logged in first. ```bash docker pull hello-world ``` ```bash docker tag hello-world {{ host }}/{{ slug }}/hello-world:v1.0.0 ``` ```bash docker push {{ host }}/{{ slug }}/hello-world:v1.0.0 ``` -------------------------------- ### Example GitHub Actions Output Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/integrations/github-actions.md This is an example of the output you might see in your GitHub Actions logs when the Distr action runs, showing which deployments were updated and which were skipped. ```text Updating all deployments to the new version... Updated 3 deployment target(s) Skipped 2 deployment target(s): - Customer A Production: Already on target version - Customer B Testing: Application not deployed on this target ``` -------------------------------- ### Start Docker Service Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/setup-on-windows-wsl.mdx Start the Docker service within your WSL distribution if it's not already running. ```sh sudo service docker start ``` -------------------------------- ### Example Docker Compose File Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/integrations/github-actions.md A sample docker-compose.yaml file for defining your application services, including image references and environment variables. ```yaml services: web: image: ghcr.io/yourorg/your-app:${VERSION} ports: - '8080:8080' environment: - DATABASE_URL=${DATABASE_URL} - SECRET_KEY=${SECRET_KEY} ``` -------------------------------- ### Verify Docker Installation Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/setup-on-windows-wsl.mdx Run these commands to verify that Docker is installed and functioning correctly within WSL. ```sh docker run hello-world ``` ```sh docker compose version ``` ```sh docker ps ``` -------------------------------- ### Example Curl Command for Support Bundle Collection Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/customer-portal/customer-portal-support.mdx This is an example of the one-time curl command generated by Distr after creating a support bundle. It is valid for 24 hours and is used to initiate the data collection process on the affected deployment host. ```bash curl -sSL https://distr.example.com/api/v1/support/collect/a1b2c3d4e5f67890 | bash -s -- --bundle-id a1b2c3d4e5f67890 ``` -------------------------------- ### Install Distr Helm Chart Source: https://github.com/distr-sh/distr/blob/main/deploy/charts/distr/README.md Use this command to install or upgrade the Distr Helm chart. It specifies the namespace, chart source, version, and enables PostgreSQL and RustFS. ```shell helm upgrade --install --wait --namespace distr --create-namespace \ distr oci://ghcr.io/distr-sh/charts/distr --version 1.11.0 \ --set postgresql.enabled=true --set rustfs.enabled=true ``` -------------------------------- ### Self-hosting Distr with Docker Compose Source: https://github.com/distr-sh/distr/blob/main/README.md Quickly set up Distr by downloading and extracting the Docker Compose deployment files, then starting the services. Ensure to modify the .env file as needed. ```shell mkdir distr && cd distr && curl -fsSL https://github.com/distr-sh/distr/releases/latest/download/deploy-docker.tar.bz2 | tar -jx # make necessary changes to the .env file docker-compose up -d ``` -------------------------------- ### docker-compose.yaml (bind mount) Source: https://github.com/distr-sh/distr/blob/main/website/src/content/blog/2026-04-15-docker-compose-mount-config-files.mdx Example Docker Compose file demonstrating how to bind-mount a postgresql.conf file from the host into the container. This allows the PostgreSQL instance to use a custom configuration. ```yaml services: postgres: image: postgres:15 ports: - "5432:5432" environment: POSTGRES_PASSWORD: "mysecretpassword" volumes: - "pgdata:/var/lib/postgresql/data" - "./postgresql.conf:/etc/postgresql/postgresql.conf:ro" command: "postgres -c config_file=/etc/postgresql/postgresql.conf" volumes: pgdata: ``` -------------------------------- ### Example Registry, Repository, and Image Naming Source: https://github.com/distr-sh/distr/blob/main/website/src/content/glossary/oci-container-artifact-registry.mdx Illustrates the hierarchical naming convention for registries, repositories, and specific application images, including tags and digests. ```text - Registry: registry.example.com - Repository: registry.example.com/my-repository - Application (image): registry.example.com/my-repository/my-app - Application (image) with tag: registry.example.com/my-repository/my-app:v1.2.0 - Application (image) with digest: registry.example.com/my-repository/my-app@sha256:abc123... ``` -------------------------------- ### Example Environment Template Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/integrations/github-actions.md An optional env.template file to specify environment variables that customers need to configure for your application. ```env # Database connection string DATABASE_URL=postgresql://user:password@localhost:5432/dbname # Secret key for encryption (generate a random string) SECRET_KEY= ``` -------------------------------- ### Example Image Tagging Strategies Source: https://github.com/distr-sh/distr/blob/main/website/src/content/glossary/oci-container-artifact-registry.mdx Illustrates common strategies for tagging container images, including semantic versioning, Git commit references, and environment-specific labels. ```shell myapp:1.2.3 myapp:1.2 myapp:1 myapp:latest ``` ```shell myapp:sha-7f8d92a myapp:pr-456 myapp:dev-7f8d92a ``` ```shell myapp:production myapp:staging myapp:development ``` -------------------------------- ### Installing Distr with Helm Chart Source: https://github.com/distr-sh/distr/blob/main/README.md Install Distr in a Kubernetes cluster using the official Helm chart. This command enables PostgreSQL and Distr's Rust file system. Review values.yaml for production configurations. ```shell helm upgrade --install --wait --namespace distr --create-namespace \ distr oci://ghcr.io/distr-sh/charts/distr \ --set postgresql.enabled=true --set rustfs.enabled=true ``` -------------------------------- ### Initialize Docker Swarm Source: https://github.com/distr-sh/distr/blob/main/website/src/content/blog/distr-docker-swarm.mdx Run this command to enable Swarm mode on your local Docker installation. Replace '...' with your computer's IP address. ```bash docker swarm init --advertise-addr ... ``` -------------------------------- ### Install Kubernetes Agent Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/kubernetes-agent.mdx Apply the agent configuration to the specified namespace. The agent will then discover tracking secrets and adopt existing Helm releases. ```bash kubectl apply -n -f "" ``` -------------------------------- ### Kubernetes Values Template Example Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/applications/application-version-detail-modal.component.html Shows how to use user-provided values in a Kubernetes base values template. Use `{{ .Values.app.ingress.hostname }}` to dynamically insert the hostname. ```html @if (versionDetail(); as detail) { @if (detail.application.type === 'kubernetes') { Version Link Template You can use the Go template language to get a dynamic link based on user provided values (`{{ .Values.app.ingress.hostname }}`). } } ``` -------------------------------- ### Docker Environment File Template Example Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/applications/application-version-detail-modal.component.html Illustrates how to use environment variables in a Docker Compose file template. Use `{{ .Env.HOSTNAME }}` to dynamically insert the hostname. ```html @if (versionDetail(); as detail) { @if (detail.application.type === 'docker') { Version Link Template You can use the Go template language to get a dynamic link based on environment variables (`{{ .Env.HOSTNAME }}`). } } ``` -------------------------------- ### Client Constructor Source: https://github.com/distr-sh/distr/blob/main/sdk/js/docs/classes/Client.md Initializes a new instance of the Client with the provided configuration. ```APIDOC ## Constructor ### new Client(config: ConditionalPartial) Initializes a new Client instance. #### Parameters * **config** (ConditionalPartial) - Configuration object for the client, including an optional `apiBase` property. ``` -------------------------------- ### Support Bundle Configuration Prompt Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/support-bundles/list/support-bundle-list.component.html Displays a message and prompts for configuration if the user is a vendor, loading is complete, and configuration does not exist. ```HTML @if (auth.isVendor() && !loading() && !configExists()) { Support bundle configuration has not been set up yet. Configure the environment variables that should be collected from the host and Docker containers when customers create support bundles. Configure } ``` -------------------------------- ### Example JSON Payload 1 Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/licenses/license-keys.mdx A simple JSON object for custom claims, specifying seats and plan. ```json {"seats": 25, "plan": "pro"} ``` -------------------------------- ### Build Hub (Community Edition) Source: https://github.com/distr-sh/distr/blob/main/CLAUDE.md Builds the community edition of the hub, which includes the frontend build. Binaries are output to `dist/`. ```bash mise run build:hub:community ``` -------------------------------- ### Remove Distr Docker Volume Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/setup-on-macos.mdx Run this command to delete the `distr_scratch` volume if it exists from a previous failed installation. ```sh docker volume rm distr_scratch ``` -------------------------------- ### CVE Identifier Format Source: https://github.com/distr-sh/distr/blob/main/website/src/content/glossary/cve-common-vulnerabilities-and-exposures.mdx A CVE ID follows the format CVE-YEAR-NUMBER. Examples include Log4Shell, Heartbleed, and Spectre. ```text CVE-2021-44228 CVE-2014-0160 CVE-2017-5715 ``` -------------------------------- ### Get WSL IP Address Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/overview/setup-on-windows-wsl.mdx Retrieve the IP address of your WSL instance. This is needed for configuring port forwarding. ```sh hostname -I ``` -------------------------------- ### Run Support Bundle Collection Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/support/support-bundles.mdx Execute this `curl` command on the deployment host to initiate the collection of diagnostic data for a support bundle. Ensure the URL and token are correctly provided. ```bash curl -X POST https://support.distr.sh/api/v1/support-bundles/{{support_bundle_id}}/collect \ -H "Authorization: Bearer {{token}}" ``` -------------------------------- ### Generate SBOM with SPDX SBOM Generator Source: https://github.com/distr-sh/distr/blob/main/website/src/content/glossary/sbom-software-bill-of-materials.mdx Install and use the SPDX SBOM Generator for Node.js projects to create an SBOM. ```shell npm install -g @spdx/spdx-sbom-generator spdx-sbom-generator -p ./ ``` -------------------------------- ### Build Agent (Kubernetes) Source: https://github.com/distr-sh/distr/blob/main/CLAUDE.md Builds the agent for Kubernetes deployment. Binaries are output to `dist/`. ```bash mise run build:agent:kubernetes ``` -------------------------------- ### Basic Variable Substitution with Port Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/configuration/application-links.mdx Combine environment variables for host and port to construct a URL. Ensure both HOST and PORT are defined in the .env file. ```go-template https://{{ .Env.HOST }}:{{ .Env.PORT }} ``` -------------------------------- ### Example License Key Payload Source: https://github.com/distr-sh/distr/blob/main/website/src/content/blog/2026-03-12-license-key.mdx Define the claims for your license key in a JSON payload. This structure dictates what your application will enforce at runtime. ```json { "seats": 25, "plan": "pro", "modules": ["analytics", "reporting"] } ``` -------------------------------- ### Building Distr Hub and Docker Images from Source Source: https://github.com/distr-sh/distr/blob/main/README.md Build the Distr control plane and all associated Docker images using `mise` for dependency management. Ensure `mise.toml` is present for build task definitions. ```shell # Build the control plane mise run build:hub # Build all docker images mise run "docker-build:**" ``` -------------------------------- ### Example JSON Payload 2 Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/licenses/license-keys.mdx A more complex JSON object for custom claims, including instance count, modules, and an expiration notice period. ```json { "instances": 3, "modules": ["analytics", "reporting"], "expires_notice_days": 30 } ``` -------------------------------- ### Conditional Complete Tutorial Button Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/tutorials/branding/branding-tutorial.component.html Shows a 'Complete Tutorial' button if the tutorial has not been completed. ```html @else { Complete Tutorial } ``` -------------------------------- ### Build Agent (Docker) Source: https://github.com/distr-sh/distr/blob/main/CLAUDE.md Builds the agent for Docker deployment. Binaries are output to `dist/`. ```bash mise run build:agent:docker ``` -------------------------------- ### Check Minimum Docker CLI Version Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/agents/configuration/preflight-checks.md Ensures the Docker CLI meets a minimum version requirement. Exits with an error if Docker is not installed or the version is too low. ```bash #!/bin/bash set -e REQUIRED_VERSION="24.0.0" if ! command -v docker &> /dev/null; then echo "FAIL: Docker is not installed." exit 1 fi DOCKER_VERSION=$(docker version --format '{{.Client.Version}}' 2>/dev/null || echo "0.0.0") version_ge() { printf '%s\n%s' "$2" "$1" | sort -V -C } if ! version_ge "$DOCKER_VERSION" "$REQUIRED_VERSION"; then echo "FAIL: Docker version $DOCKER_VERSION is below the required minimum $REQUIRED_VERSION." exit 1 fi echo "OK: Docker version $DOCKER_VERSION meets the minimum requirement ($REQUIRED_VERSION)." ``` -------------------------------- ### Build and Push to Distr Workflow Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/integrations/github-actions.md This workflow first builds and pushes Docker images for backend, frontend, and proxy services, then creates a new Distr version and updates deployments. The `needs` clause ensures build jobs complete before the Distr action runs. ```yaml name: Build and Push to Distr on: push: tags: - '*' jobs: build-backend: runs-on: ubuntu-latest steps: # ... build and push backend image build-frontend: runs-on: ubuntu-latest steps: # ... build and push frontend image build-proxy: runs-on: ubuntu-latest steps: # ... build and push proxy image push-to-distr: needs: [build-backend, build-frontend, build-proxy] runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Create Distr Version and Update Deployments uses: distr-sh/distr-create-version-action@v1 with: api-token: ${{ secrets.DISTR_API_TOKEN }} application-id: ${{ vars.DISTR_APPLICATION_ID }} version-name: ${{ github.ref_name }} compose-file: ${{ github.workspace }}/deploy/docker-compose.yaml template-file: ${{ github.workspace }}/deploy/env.template update-deployments: true ``` -------------------------------- ### Fetch Public Key using curl Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/licenses/license-keys.mdx Demonstrates how to fetch the public key using curl. Replace 'https://your-distr-hub.example.com' with your actual Distr Hub URL. ```shell curl https://your-distr-hub.example.com/api/public/v1/license-keys/public-key ``` -------------------------------- ### Docker Compose File with Version Placeholders Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/integrations/github-actions.md Example docker-compose.yaml file showing service images with version placeholders. These are typically updated by release automation tools. ```yaml services: backend: image: ghcr.io/distr-sh/hello-distr/backend:0.2.1 # x-release-please-version frontend: image: ghcr.io/distr-sh/hello-distr/frontend:0.2.1 # x-release-please-version proxy: image: ghcr.io/distr-sh/hello-distr/proxy:0.2.1 # x-release-please-version ``` -------------------------------- ### Kubernetes Deployment Manifest Source: https://github.com/distr-sh/distr/blob/main/website/src/content/blog/2025-11-17-docker-compose-vs-kubernetes.md Example of a Kubernetes Deployment manifest using Helm templating for configuration. This defines how to deploy and manage an application within a Kubernetes cluster. ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: {{ .Release.Name }} spec: replicas: {{ .Values.replicas }} template: spec: containers: - name: app image: {{ .Values.image.repository }}:{{ .Values.image.tag }} env: - name: DATABASE_URL valueFrom: secretKeyRef: name: {{ .Release.Name }}-secrets key: database-url ``` -------------------------------- ### Create and Push Release Tag (Manual Tags) Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/integrations/github-actions.md Create a Git tag for a new release and push it to the origin. This action manually triggers the deployment workflow. ```bash git tag 0.1.0 git push origin 0.1.0 ``` -------------------------------- ### Forward Stripe Webhook Events Source: https://github.com/distr-sh/distr/blob/main/CONTRIBUTING.md Configure the Stripe CLI to forward webhook events to your local Distr Hub instance. Ensure the Stripe CLI is installed and authenticated. ```shell stripe listen --forward-to localhost:8080/api/v1/webhook/stripe ``` -------------------------------- ### Display Support Bundle Collection Command Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/support-bundles/detail/support-bundle-detail.component.html If the bundle is initialized, the user has appropriate roles, and is a customer, this section displays the command to collect and upload the support bundle. ```html @if ( bundle.collectCommand && bundle.status === 'initialized' && auth.isCustomer() && auth.hasAnyRole('read_write', 'admin') ) { Collect Command --------------- Run this command on the target system to collect and upload the support bundle: `{{ bundle.collectCommand }}` } ``` -------------------------------- ### Verify License Token with Node.js Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/licenses/license-keys.mdx Example of verifying a license token using the Node.js 'jose' library. Ensure you have the public key in PEM format and the token to verify. ```javascript import {importSPKI, jwtVerify} from 'jose'; const publicKey = await importSPKI(PUBLIC_KEY_PEM, 'EdDSA'); const {payload} = await jwtVerify(token, publicKey, { audience: 'license-key', }); console.log(payload.seats); // your custom claim ``` -------------------------------- ### Create Kubernetes Application Version with Resources using Distr SDK Source: https://github.com/distr-sh/distr/blob/main/website/src/content/docs/docs/platform/support/kubernetes-compatibility-matrix.mdx Use the Distr SDK to programmatically create a new Kubernetes application version, attaching version resources like compatibility matrices. Set the `visibleToCustomers` flag to control portal visibility. ```typescript import {DistrService} from '@distr-sh/distr-sdk'; const distr = new DistrService({ apiKey: process.env.DISTR_API_TOKEN, }); await distr.createKubernetesApplicationVersion(appId, '1.5.0', { chartType: 'oci', chartUrl: 'oci://ghcr.io/yourorg/your-chart', chartVersion: '1.5.0', resources: [ { name: 'Kubernetes Compatibility Matrix', content: compatibilityMatrixMarkdown, visibleToCustomers: true, }, { name: 'Internal Release Notes', content: '# Internal Notes\n\nThis version includes...', visibleToCustomers: false, }, ], }); ``` -------------------------------- ### No Support Bundles Yet - Vendor View Source: https://github.com/distr-sh/distr/blob/main/frontend/ui/src/app/support-bundles/list/support-bundle-list.component.html Informs vendors that no support bundles have been created yet and explains the feature's prerequisites. ```HTML @else if (auth.isVendor()) { No support bundles have been created yet. Customers with the support bundles feature enabled can create support bundles. } ``` -------------------------------- ### Generate Support Bundle Curl Command Source: https://github.com/distr-sh/distr/blob/main/website/src/content/blog/2026-03-30-support-bundles.mdx This is an example of a one-time curl command generated by Distr for customers to initiate the support bundle collection. It is valid for 24 hours. ```bash curl https://distr.example.com/support-bundle/abcdef123456 --output distr-bundle.sh chmod +x distr-bundle.sh ./distr-bundle.sh ``` -------------------------------- ### Approach 1: Lightweight Scheduler with Crontab Source: https://github.com/distr-sh/distr/blob/main/website/src/content/blog/2026-02-03-docker-compose-cron-jobs.mdx This approach uses a lightweight scheduler by directly adding a crontab file to the Docker image. It's suitable for simple scheduling needs within a single service. ```dockerfile FROM alpine:latest RUN apk add --no-cache dcron COPY crontab /etc/crontabs/root RUN crond -f -L /dev/stdout # Your application code here COPY app /app WORKDIR /app CMD ["/bin/sh", "-c", "./your_app.sh"] ``` ```crontab * * * * * /app/your_script.sh >> /var/log/cron.log 2>&1 ``` ```yaml version: '3.8' services: app: build: context: ./approach-1 volumes: - ./approach-1/crontab:/etc/crontabs/root restart: always ```