Skip to main content

Pluggedspace Registry — Customer Documentation

Welcome to the Pluggedspace License & Artifact Registry customer guide. This documentation explains how entitled organizations acquire, verify, deploy, and maintain software distributed through the Pluggedspace platform (including BorderCash).

1. Core Principles​

The Pluggedspace platform operates on two fundamental engines:

  1. The License Engine: Determines WHO is entitled to WHAT.

    • Validates active contracts, plan entitlements, node deployment quotas, and maintenance coverage dates.
    • Issues cryptographically signed (Ed25519) license certificates.

  2. The Artifact Engine: Determines HOW an entitled customer receives the software.

    • Builds canonical release manifests and tailor-made docker-compose.yml configurations.
    • Secures and delivers container images and binary packages via ephemeral, presigned S3 URLs without requiring external third-party registry accounts (such as GitHub / GHCR).

2. Customer Prerequisites​

To install and run software from the registry, you need:

  1. A Pluggedspace Customer Account: Registered at accounts.pluggedspace.org or invited to an organization.
  2. An Active License Key: In the standard format LIC-XXXX-XXXX-XXXX with current maintenance coverage.
  3. Target Server Environment:
    • Any modern Linux distribution (Ubuntu 22.04+, Debian 12+, RHEL 9+) or server environment.
    • Docker (v24.0+) and Docker Compose (v2.20+).
    • Outbound internet access to https://registry.pluggedspace.org and the underlying S3 distribution endpoint.

3. Two Ways to Deploy​

Pluggedspace supports both graphical and headless terminal installation paths:

graph LR
    A[Customer Organization] --> B[1. Web Dashboard Path]
    A --> C[2. Headless CLI Path]

    B --> B1[Visit /customer/updates]
    B1 --> B2[1-Click Download Assets]
    B2 --> B3[docker load & docker compose up]

    C --> C1[Query Registry API]
    C1 --> C2[Curl Manifest & S3 Tarballs]
    C2 --> C3[Automated Server Bootstrap]

Path 1: Web Dashboard (GUI)​

Best for developers and administrators installing on local workstations or testing environments.

  • Navigate to Customer Dashboard → Updates.
  • Download docker-compose.yml and pre-built container .tar.gz archives with a single click.
  • Load into Docker and boot services.

Path 2: Headless CLI & Automation (Terminal)​

Best for production cloud servers (AWS EC2, DigitalOcean, Hetzner, Bare Metal) and automated CI/CD runners.

  • Pass your x-license-key in HTTP headers.
  • Download the signed deployment manifest directly to your server: 
    curl -H "x-license-key: LIC-XXXX-XXXX-XXXX" \
      "https://registry.pluggedspace.org/api/v1/releases/<RELEASE_ID>/manifest?format=compose" \
      -o docker-compose.yml
  • Download and load images, then run docker compose up -d.

4. Documentation Navigation​

  • Customer Usage Guide (usage.md): Complete step-by-step instructions for:
    • Downloading and running releases via the Web Dashboard.
    • Headless installation scripts via the Terminal/CLI.
    • S3 container image loading (docker load -i ...).
    • Checking for software updates and upgrading versions.
    • Node registration, activation keys, and periodic heartbeats.
    • Configuring Whitelabel branding (custom logo, colors, mobile APK/IPA builds).
    • Common troubleshooting and error codes.