Earthbond Build And Access Manual

Source: docs/operations/EARTHBOND_BUILD_AND_ACCESS_MANUAL.md

Manual Index Client UI

Earthbond Build And Access Manual

Purpose

This manual explains how the current Earthbond deployment is built, accessed, backed up, and defended operationally.

It is written for humans making the next decision about:

  1. whether the current deployment is understandable,
  2. whether the current backup boundary is correct,
  3. how PostgreSQL, MinIO, Docker, and the web app fit together,
  4. what is preserved in GitHub,
  5. what is intentionally excluded.

Access Points

Primary WAN access:

  1. app:
  1. upload workflow:
  1. manuals:
  1. admin gate:

Workspace Layout

The repository is now partitioned into explicit project views:

  1. projects/earthbond/README.md
  2. projects/wiicco-site/README.md

Earthbond remains the active deployment project.

projects/earthbond/core provides the Earthbond source view.

projects/earthbond/generated provides the Earthbond generated/backup view.

projects/wiicco-site isolates unrelated website/export assets from the deployment root.

The runtime remains Earthbond-only.

Canonical GitHub Source

Earthbond should be treated as its own GitHub deployment source:

  1. repository:
  1. active deployment branch:

The local server remains the runtime environment and should run from a local clone of this repository.

Deployment Shape

The deployment is built from:

  1. Docker Compose
  2. Python application services
  3. nginx and Caddy proxy layers
  4. PostgreSQL as the main relational truth store
  5. MinIO as raw object storage
  6. generated manuals and operational exports

Main source files:

  1. docker-compose.yml
  2. Dockerfile.python
  3. Dockerfile.web
  4. Dockerfile.edge
  5. Caddyfile
  6. edge.conf
  7. app-web.conf

Programming Languages

Main languages used:

  1. Python
  2. SQL
  3. JavaScript
  4. bash
  5. YAML

Proxy Layers

The deployment uses multiple proxy layers:

  1. public TLS proxy:
  1. internal edge proxy:
  1. app-web proxy:
  1. API gateway:

PostgreSQL

PostgreSQL is used for:

  1. source registry
  2. canonical tables
  3. semantic projection
  4. audit records
  5. workflow state
  6. scoring outputs

The live schema is defined by migrations under:

MinIO

MinIO is used for immutable raw object storage.

It stores:

  1. uploaded raw payloads
  2. staged field-package objects
  3. evidence-pack style outputs where object persistence is needed

It does not hold:

  1. canonical relational truth
  2. auth state
  3. scoring logic

GitHub Backup Boundary

The GitHub backup is a source and configuration backup, not a raw data backup.

Included in the GitHub backup branch:

  1. Docker deployment source
  2. Python application source
  3. UI source
  4. docs and manuals
  5. schema migrations
  6. generated redacted Docker deployment config
  7. generated PostgreSQL schema-only backup
  8. generated MinIO manifest without objects

Excluded:

  1. .env
  2. data/minio/
  3. data/runtime/
  4. data/auth-outbox/
  5. data/external/
  6. PostgreSQL row data
  7. MinIO objects
  8. runtime secrets

Backup Branch

The automated source backup is pushed to:

  1. remote:
  1. branch:

Local Git Workflow

The local working branch for Earthbond deployment operations should be:

  1. main

This avoids mixing deployment history with unrelated local branches.

The GitHub backup job now expects the checked-out branch to match the configured target branch before it will push.

Backup Structure

Generated backup artifacts are stored in:

Structure:

  1. backups/README.md
  2. backups/docker/config
  3. backups/docker/images/manifest
  4. backups/docker/images/ghcr
  5. backups/postgres/schema
  6. backups/minio/manifest
  7. backups/repo/state

Backup Automation

Host automation:

  1. backup_to_github.sh
  2. export_backup_artifacts.sh
  3. install_backup_launchd.sh
  4. install_backup_cron.sh

Why The Backup Runs Outside Containers

The backup runs on the host because:

  1. the git working tree is on the host
  2. GitHub SSH credentials are host-bound
  3. the backup should not depend on container shell state
  4. the backup boundary should remain outside app credentials and runtime secrets

PostgreSQL Backup Meaning

The GitHub branch contains:

  1. schema-only export
  2. table inventory
  3. no row data

Script:

MinIO Backup Meaning

The GitHub branch contains:

  1. bucket manifest
  2. bucket names
  3. deployment storage shape
  4. no object payload data

Script:

Docker Backup Meaning

The GitHub branch contains:

  1. source Docker files from the repo
  2. generated resolved Compose output with secrets redacted
  3. current service list
  4. Docker image manifest separated from config
  5. optional GHCR push logs when image mirroring is enabled

Script:

Related Manuals

  1. Deployment Healthcheck Runbook
  2. Data Platform Storage And DB Manual
  3. Database Relationship Schematic
  4. Decision Defense Report

Operational Conclusion

The current Earthbond backup approach preserves:

  1. deployment source
  2. database structure
  3. object-store structure
  4. access/build documentation

It intentionally does not preserve:

  1. secrets
  2. runtime datasets
  3. raw MinIO payloads
  4. PostgreSQL row data