docs: cloud deployment IaC design (OpenTofu + cloud-init + Hetzner)

.github/workflows/pr-checks.yml

@@ -23,13 +23,83 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      - name: Checkout log-collector
+        uses: actions/checkout@v4
+        with:
+          repository: unytco/log-collector
+          path: docker/log-collector
+          token: ${{ secrets.HARVESTER_REPO_TOKEN }}
+
+      - name: Build log-collector (cached)
+        uses: docker/build-push-action@v5
+        with:
+          context: docker/log-collector
+          file: docker/Dockerfile.log-collector
+          load: true
+          tags: edgenode-log-collector:latest
+          cache-from: type=gha,scope=log-collector
+          cache-to: type=gha,mode=max,scope=log-collector
+
       - name: Build image for testing
-        run: |
-          docker buildx build docker/ --file docker/Dockerfile \
-            --platform linux/amd64 \
-            --load \
-            --tag local-edgenode
+        uses: docker/build-push-action@v5
+        with:
+          context: docker/
+          file: docker/Dockerfile
+          load: true
+          tags: local-edgenode
+          cache-from: type=gha,scope=edgenode
+          cache-to: type=gha,mode=max,scope=edgenode
 
       - name: Run tests
         run: |
           CI_RELEASE_TEST=true ./docker/run_tests_multi.sh local-edgenode
+
+  test-harvester-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Checkout log-collector
+        uses: actions/checkout@v4
+        with:
+          repository: unytco/log-collector
+          path: docker/log-collector
+          token: ${{ secrets.HARVESTER_REPO_TOKEN }}
+
+      - name: Build log-collector (cached)
+        uses: docker/build-push-action@v5
+        with:
+          context: docker/log-collector
+          file: docker/Dockerfile.log-collector
+          load: true
+          tags: edgenode-log-collector:latest
+          cache-from: type=gha,scope=log-collector
+          cache-to: type=gha,mode=max,scope=log-collector
+
+      - name: Checkout log-harvester
+        uses: actions/checkout@v4
+        with:
+          repository: unytco/log-harvester
+          path: docker/log-harvester-src
+          token: ${{ secrets.HARVESTER_REPO_TOKEN }}
+
+      - name: Build harvester image for testing
+        uses: docker/build-push-action@v5
+        with:
+          context: docker/
+          file: docker/Dockerfile.harvester
+          load: true
+          tags: local-edgenode-harvester
+          cache-from: type=gha,scope=edgenode-harvester
+          cache-to: type=gha,mode=max,scope=edgenode-harvester
+
+      - name: Run harvester tests
+        run: |
+          CI_RELEASE_TEST=true ./docker/run_harvester_tests.sh local-edgenode-harvester

.github/workflows/release.yml

@@ -156,3 +156,43 @@ jobs:
             --push \
             --tag "${VERSION_TAG}" \
             --tag "${LATEST_TAG}"
+
+  build-and-push-harvester-image:
+    runs-on: ubuntu-latest
+    needs: create-release
+    if: github.ref_type == 'tag' || github.event_name == 'workflow_dispatch'
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.create-release.outputs.tag }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push harvester image
+        run: |
+          VERSION_TAG="ghcr.io/holo-host/edgenode-harvester:${{ needs.create-release.outputs.tag }}"
+          LATEST_TAG="ghcr.io/holo-host/edgenode-harvester:latest"
+
+          docker buildx build docker/ --file docker/Dockerfile.harvester \
+            --platform linux/amd64,linux/arm64 \
+            --push \
+            --tag "${VERSION_TAG}" \
+            --tag "${LATEST_TAG}" \
+            --secret id=github_token,env=GITHUB_TOKEN
+        env:
+          GITHUB_TOKEN: ${{ secrets.HARVESTER_REPO_TOKEN }}

.gitignore

@@ -3,8 +3,10 @@ test-data/
 holo-data-test/
 .roo/
 .gemini/
+.agents/
 docker/happ_config_file
 docker/log-collector/
+docker/log-harvester-src/
 AGENTS.md
 log_fix.md
 UNYT_TEST_ANALYSIS.md

README.md

@@ -4,7 +4,7 @@ This repo contains the tooling needed to deploy and operate always-on nodes for
 
 The tooling consists of:
 
-1. Edge Node - A Docker container specification for running Holochain with hApps in an OCI-compliant containerized environment.
+1. Edge Node - Docker container specifications for running Holochain with hApps in an OCI-compliant containerized environment. Two variants: `edgenode` (standard, with log-sender) and `edgenode-harvester` (with log-harvester for Unyt invoice aggregation).
 2. HolOS - A streamlined Linux ISO that enables the deployment of this container on physical or virtual hardware (especially HoloPorts).
 
 For a detailed overview and usage instructions [see here](/USAGE.md).
@@ -23,8 +23,9 @@ For a detailed overview and usage instructions [see here](/USAGE.md).
 
 A [Docker-based container](docker/README.md) that delivers Edge Node, ready to run hApps:
 
-- Holochain conductor configured to automatically run via `tini`.
+- Holochain conductor managed by s6-overlay, starting automatically on container launch.
 - Tools for installing and managing hApps from configuration files.
+- Two variants: standard (`edgenode`) and harvester (`edgenode-harvester`).
 
 ### HolOS Build System
 
@@ -43,9 +44,9 @@ A [specialized OS builder](holos/README.md) for creating custom ISO images using
 
 ## Quick Start
 
-### To test the Edge Node container:
+### Standard Edge Node
 
-1. Pull the Docker image:
+1. Pull the image:
 
 ```sh
 docker pull ghcr.io/holo-host/edgenode
@@ -64,6 +65,29 @@ docker exec -it edgenode su - nonroot
 ps -ef
 ```
 
+### Harvester Edge Node
+
+1. Pull the image:
+
+```sh
+docker pull ghcr.io/holo-host/edgenode-harvester
+```
+
+2. Launch with your log-collector credentials:
+
+```sh
+docker run --name harvester -dit \
+  -v $(pwd)/holo-data:/data \
+  -p 4444:4444 \
+  -p 4445:4445 \
+  -e COLLECTOR_URL=https://your-log-collector.unyt.dev \
+  -e ADMIN_SECRET=your-admin-secret \
+  -e LAIR_PASSWORD=your-lair-password \
+  ghcr.io/holo-host/edgenode-harvester
+```
+
+See [docker/LOG_HARVESTER_QUICKSTART.md](docker/LOG_HARVESTER_QUICKSTART.md) for full setup instructions.
+
 ### For HolOS Users
 
 1. Download a release of the iso from our [releases page](https://github.com/Holo-Host/edgenode/releases)
@@ -74,5 +98,7 @@ ps -ef
 
 - [Detailed overview and usage instructions](/USAGE.md)
 - [Edge Node Container Instructions](docker/README.md)
+- [Log-Sender Quickstart (Unyt resource accounting)](docker/LOG_SENDER_QUICKSTART.md)
+- [Log-Harvester Quickstart (Unyt invoice aggregation)](docker/LOG_HARVESTER_QUICKSTART.md)
 - [HolOS Build System Guide](holos/README.md)
 - [Tools for working with Edge Nodes](tools/README.md)

deploy/.env.example

@@ -0,0 +1,61 @@
+# Edge Node Cloud Deployment — Environment Variables
+#
+# Copy this file to .env.staging or .env.production and fill in your values.
+# Source it before running any deploy scripts:
+#
+#   cp deploy/.env.example deploy/.env.staging
+#   $EDITOR deploy/.env.staging
+#   source deploy/.env.staging
+#
+# Never commit .env.staging or .env.production — they are gitignored.
+
+# --- Hetzner Cloud ---
+HCLOUD_TOKEN=""
+
+# --- Cloudflare ---
+CLOUDFLARE_ACCOUNT_ID=""
+CLOUDFLARE_API_TOKEN=""
+# Workers subdomain (found in Workers & Pages → Overview → Your subdomain)
+CLOUDFLARE_WORKERS_SUBDOMAIN=""
+# Zone ID for the domain used by this deployment (found in the Cloudflare dashboard Overview tab)
+CLOUDFLARE_ZONE_ID=""
+
+# --- SSH ---
+# Contents of the SSH public key to install on Hetzner VMs (e.g. ~/.ssh/id_ed25519.pub)
+SSH_PUBLIC_KEY=""
+
+# --- Joining Service ---
+# Shared secret between h2hc-linker and the joining service Worker.
+LINKER_ADMIN_SECRET=""
+# Comma-separated invite codes for HWC browser nodes.
+INVITE_CODES="test-invite-123"
+
+# --- Unyt / Log-Sender (edgenode) ---
+# URL of the Cloudflare log-collector Worker.
+LOG_SENDER_ENDPOINT=""
+# Unyt agent public key (uhCAk...) of the party paying for resources.
+LOG_SENDER_UNYT_PUB_KEY=""
+
+# --- Harvester ---
+# URL of the Cloudflare log-collector Worker (same as LOG_SENDER_ENDPOINT).
+COLLECTOR_URL=""
+# Admin secret for the log-collector.
+ADMIN_SECRET=""
+# Lair keystore password for the harvester Holochain conductor.
+HARVESTER_LAIR_PASSWORD=""
+
+# --- edgenode container ---
+# Lair keystore password for the Holochain conductor.
+LAIR_PASSWORD=""
+
+# --- OpenTofu variable passthrough ---
+# These map env vars to TF_VAR_* so tofu picks them up automatically.
+export TF_VAR_hcloud_token="$HCLOUD_TOKEN"
+export TF_VAR_cloudflare_account_id="$CLOUDFLARE_ACCOUNT_ID"
+export TF_VAR_cloudflare_api_token="$CLOUDFLARE_API_TOKEN"
+export TF_VAR_cloudflare_workers_subdomain="$CLOUDFLARE_WORKERS_SUBDOMAIN"
+export TF_VAR_cloudflare_zone_id="$CLOUDFLARE_ZONE_ID"
+export TF_VAR_ssh_public_key="$SSH_PUBLIC_KEY"
+export TF_VAR_linker_admin_secret="$LINKER_ADMIN_SECRET"
+export TF_VAR_invite_codes="$INVITE_CODES"
+export TF_VAR_harvester_lair_password="$HARVESTER_LAIR_PASSWORD"