Customer Usage Guide — Pluggedspace Registry

This guide provides end-to-end instructions for customers installing, running, and maintaining software releases (such as BorderCash) from the Pluggedspace Registry.

Method A: Using the Customer Dashboard (GUI)
Method B: Using the Registry via CLI / Terminal (Headless)
Running with Docker & Docker Compose
Checking for Updates & Upgrading
Whitelabel Branding & Custom Builds
Node Deployment Registration & Heartbeats
Troubleshooting & FAQ

Method A: Using the Customer Dashboard (GUI)

The Web Dashboard provides a 1-click graphical interface for downloading software releases and managing licenses.

Visit https://registry.pluggedspace.org/login.
Authenticate using your organization account credentials.

Step 2: Check Your Entitlements

Navigate to Customer Workspace → Licenses.
Verify that your license for the product (e.g. BorderCash) displays a green Active status.
Note your License Key (format: LIC-XXXX-XXXX-XXXX) and Maintenance Until date.

Step 3: Download Release Files

Navigate to Customer Workspace → Updates & Releases.
Under the Download Software Assets card for the latest release:
- Click Download docker-compose.yml to save the tailored compose specification.
- Click Download next to each component archive:
  - bordercash-backend (e.g. 1.17 GB container archive)
  - bordercash-frontend (e.g. 40.3 MB container archive)
The browser downloads the files directly to your machine via secure, presigned S3 URLs authenticated by your active session.

Step 4: Transfer to Your Deployment Host

If you downloaded the files to a local laptop, copy them to your target server using scp or rsync:

scp docker-compose.yml bordercash-*.docker.tar.gz user@your-server-ip:/opt/bordercash/

Method B: Using the Registry via CLI / Terminal (Headless)

For remote cloud instances (AWS EC2, DigitalOcean, Hetzner, Bare Metal) or automated deployment scripts, you can pull manifests and container assets directly from the terminal using your license key.

Step 1: Export Your License Key

export PLUGGEDSPACE_LICENSE_KEY="LIC-XXXX-XXXX-XXXX"
export REGISTRY_URL="https://registry.pluggedspace.org"

Step 2: Fetch the Signed `docker-compose.yml`

Pass your license key in the x-license-key header to download the tailored compose file:

curl -sSL -H "x-license-key: $PLUGGEDSPACE_LICENSE_KEY" \
  "$REGISTRY_URL/api/v1/releases/cmujs191g003j3oirxnozy7pt/manifest?format=compose" \
  -o docker-compose.yml

Tip: You can also query GET /api/v1/releases or GET /api/v1/releases/check-update to discover the latest published release_id.

Step 3: Download the Container Archives from S3

Artifacts can be downloaded in two ways:

Option 1: Direct Download with License Key Query

# Download Backend Image Archive (~1.17 GB)
curl -L -H "x-license-key: $PLUGGEDSPACE_LICENSE_KEY" \
  "$REGISTRY_URL/api/v1/artifacts/<BACKEND_ARTIFACT_ID>/download" \
  -o bordercash-backend.docker.tar.gz

# Download Frontend Image Archive (~40.3 MB)
curl -L -H "x-license-key: $PLUGGEDSPACE_LICENSE_KEY" \
  "$REGISTRY_URL/api/v1/artifacts/<FRONTEND_ARTIFACT_ID>/download" \
  -o bordercash-frontend.docker.tar.gz

Option 2: Ephemeral Token Exchange Flow (Standard CLI)

# 1. Request a short-lived, single-use download token
TOKEN_RESP=$(curl -s -X POST "$REGISTRY_URL/api/v1/artifacts/<ARTIFACT_ID>/authorize" \
  -H "x-license-key: $PLUGGEDSPACE_LICENSE_KEY")

DOWNLOAD_TOKEN=$(echo $TOKEN_RESP | jq -r '.data.token')

# 2. Download directly (follows 302 redirect to SigV4 presigned S3 URL)
curl -L -o artifact.tar.gz "$REGISTRY_URL/api/v1/artifacts/<ARTIFACT_ID>/download?token=$DOWNLOAD_TOKEN"

Running with Docker & Docker Compose

Once you have docker-compose.yml and the .docker.tar.gz archives in your target directory:

1. Load Container Images into Docker

# Load backend container image
docker load -i bordercash-backend.docker.tar.gz

# Load frontend container image
docker load -i bordercash-frontend.docker.tar.gz

Docker will output confirmation such as: Loaded image: pluggedspace/bordercash-backend:v1.0.0.

2. Configure Environment Secrets

Create a .env file in the same directory:

cat <<EOF > .env
PLUGGEDSPACE_LICENSE_KEY=LIC-XXXX-XXXX-XXXX
DATABASE_URL=postgresql://postgres:secret@db:5432/bordercash
SECRET_KEY=$(openssl rand -hex 32)
EOF

3. Start Services

docker compose up -d

4. Verify Health & Logs

# View running containers
docker compose ps

# View backend application logs
docker compose logs -f backend

Checking for Updates & Upgrading

Running instances can automatically or manually check for new updates against the registry.

Check for Available Updates via CLI

curl -s -H "x-license-key: $PLUGGEDSPACE_LICENSE_KEY" \
  "$REGISTRY_URL/api/v1/releases/check-update?product=bordercash&channel=stable&current_version=1.0.0"

Example Response:

{
  "success": true,
  "data": {
    "updateAvailable": true,
    "latestVersion": "1.1.0",
    "channel": "stable",
    "changelog": "- Performance improvements in settlement ledger\n- Upgraded cryptographic engine",
    "maintenanceCovered": true,
    "releaseId": "rel_01J8NEWVERSION",
    "downloadUrl": "https://registry.pluggedspace.org/api/v1/releases/rel_01J8NEWVERSION/manifest?format=compose"
  }
}

Upgrading to a New Version

When an update is available:

Download the new release's docker-compose.yml and new image archives.
Load the new archives: docker load -i ....
Restart containers with zero downtime:
```
docker compose up -d --remove-orphans
```

Whitelabel Branding & Custom Builds

Organizations with enterprise whitelabel entitlements can customize the frontend (colors, logos, custom titles, mobile apps).

In the Customer Workspace, navigate to Branding & Whitelabel.
Configure your brand settings:
- Display Name: Your company name (e.g. Acme Payments).
- Primary / Accent Colors: Custom hex values matching your brand identity.
- Logo & Favicon URLs: High-resolution vector or PNG assets.
Click Save Configuration and trigger Build Custom Frontend.
The Artifact Engine automatically compiles your custom build. When complete:
- Web frontend manifests automatically substitute the generic frontend with your customized build.
- For mobile apps, download your custom Android APK or iOS IPA directly from the portal.

Node Deployment Registration & Heartbeats

Your license plan specifies a maximum number of concurrent installations/nodes (e.g. 5 active servers).

Registering a Deployment Node

When a new BorderCash server boots, it registers itself:

curl -X POST "$REGISTRY_URL/api/v1/deployments/register" \
  -H "x-license-key: $PLUGGEDSPACE_LICENSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "prod-node-01.acme.corp",
    "ipAddress": "198.51.100.10",
    "currentVersion": "1.0.0"
  }'

Returns a unique deploymentKey used for heartbeat reporting.

Sending Periodic Heartbeats

Client instances send heartbeats (e.g. every 6 hours):

curl -X POST "$REGISTRY_URL/api/v1/deployments/heartbeat" \
  -H "x-license-key: $PLUGGEDSPACE_LICENSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deploymentKey": "<DEPLOYMENT_KEY>",
    "metrics": {
      "status": "healthy",
      "uptimeSeconds": 86400
    }
  }'

Troubleshooting & FAQ

1. `401 UNAUTHORIZED / License key required`

Cause: Missing or malformed x-license-key header.
Fix: Ensure you pass -H "x-license-key: LIC-XXXX-XXXX-XXXX" or pass ?licenseKey=LIC-XXXX-XXXX-XXXX in curl commands.

2. `403 FORBIDDEN / Maintenance Expired`

Cause: Your license maintenance coverage ended before the requested version was published.
Fix: You can continue running existing versions permanently, but downloading newer releases requires a maintenance renewal via Customer Workspace → Licenses → Renew Maintenance.

3. `Error response from daemon: open bordercash-*.docker.tar.gz: no such file or directory`

Cause: Running docker load -i in a directory where the files haven't been downloaded or finished downloading.
Fix: Run ls -lh in your current terminal directory to ensure the files are completely downloaded and match the filenames.

4. `docker compose up` reports container port conflicts

Cause: Port 80 or 8000 is already in use by another service on your host machine.
Fix: Edit docker-compose.yml to change the host binding (e.g., "8080:80" instead of "80:80").

Table of Contents​

Method A: Using the Customer Dashboard (GUI)​

Step 1: Sign in to Customer Workspace​

Step 2: Check Your Entitlements​

Step 3: Download Release Files​

Step 4: Transfer to Your Deployment Host​

Method B: Using the Registry via CLI / Terminal (Headless)​

Step 1: Export Your License Key​

Step 2: Fetch the Signed docker-compose.yml​

Step 3: Download the Container Archives from S3​

Option 1: Direct Download with License Key Query​

Option 2: Ephemeral Token Exchange Flow (Standard CLI)​

Running with Docker & Docker Compose​

1. Load Container Images into Docker​

2. Configure Environment Secrets​

3. Start Services​

4. Verify Health & Logs​

Checking for Updates & Upgrading​

Check for Available Updates via CLI​

Upgrading to a New Version​

Whitelabel Branding & Custom Builds​

Node Deployment Registration & Heartbeats​

Registering a Deployment Node​

Sending Periodic Heartbeats​

Troubleshooting & FAQ​

1. 401 UNAUTHORIZED / License key required​

2. 403 FORBIDDEN / Maintenance Expired​

3. Error response from daemon: open bordercash-*.docker.tar.gz: no such file or directory​

4. docker compose up reports container port conflicts​

Table of Contents