Latest revision as of 10:21, 11 October 2025

HELIX CLEAN INSTALL RUNBOOK v1.0

🌐 Helix Ethos

Trust-by-Design · Custody-before-Growth · Verifiable-Memory

Every Helix node is built to be observable, auditable, and repairable by human hands. This runbook defines a canonical baseline for a Helix Workstation Node — a reproducible, custody-first Ubuntu 24.04 GNOME environment for R&D, governance, and proof issuance.

Document Header

Field	Value
Version	v1.0
Date	2025-10-11
Author	Stephen Hope (Helix AI Innovations Inc.)
System	Dell Workstation — Ubuntu 24.04 LTS Desktop (GNOME)
Hostname	helix-core
License	Apache 2.0
Hash Standard	SHA-256
Sign Standard	Ed25519 (GPG)
Mode	Manual Execution / Proof-Aware Logging
Intended Location	/opt/helix/docs/HELIX_CLEAN_INSTALL_RUNBOOK_v1.0.md

1. System Preparation

Explanation

This section ensures the Dell workstation starts from a trusted, deterministic state. You’ll perform a clean Ubuntu 24.04 Desktop installation, configure the primary users, and create your first immutable snapshot.

Commands

# BIOS: enable UEFI + Secure Boot + AHCI, disable Legacy/CSM, ensure TPM enabled.

sudo apt update && sudo apt -y full-upgrade
sudo apt install -y timeshift
sudo timeshift --create --comments "HELIX_BASELINE_v1.0"

Verification

sudo timeshift --list | grep HELIX_BASELINE_v1.0

[proof-hash phase-1_system_prep 20251011] 7b42a1e9d4d52ab1a7f4bda5a1d4f6e730f99292b61bcd7e61e2a3af9b6721df

2. Base Tools & Updates

Explanation

Install reproducible command-line essentials and capture a hashable record of package versions. Everything here forms the operational substrate for later Helix services. Includes a portable fallback if apt-clone is unavailable.

Commands

sudo apt update
sudo apt install -y git curl wget jq unzip build-essential python3-pip tmux vim \
  ufw fail2ban ripgrep btop bat exa tldr ncdu apt-clone

# Proofs directory
sudo mkdir -p /opt/helix/proofs

# Preferred manifest capture
sudo apt-clone clone /opt/helix/proofs/apt-state-$(date +%F)
sha256sum /opt/helix/proofs/apt-state-*.tar.gz \
  | sudo tee /opt/helix/proofs/phase-2_base_tools_$(date +%F).sha256

# Fallback (if apt-clone is missing or fails)
dpkg --get-selections > /opt/helix/proofs/dpkg-selections-$(date +%F).txt
apt-mark showmanual > /opt/helix/proofs/apt-manual-$(date +%F).txt
sha256sum /opt/helix/proofs/dpkg-selections-*.txt /opt/helix/proofs/apt-manual-*.txt \
  | sudo tee /opt/helix/proofs/phase-2_base_tools_fallback_$(date +%F).sha256

Verification

head -n1 /opt/helix/proofs/phase-2_base_tools_*.sha256 || true
head -n1 /opt/helix/proofs/phase-2_base_tools_fallback_*.sha256 || true

[proof-hash phase-2_base_tools 20251011] c3ef0db5b78a9852cc7b5e4798a1f2df9bdfb6c23dc34b4fba6328e6791c3ad8

3. Desktop & Productivity Stack

Explanation

Install the graphical and everyday-productivity layer. Use APT or official .deb packages to maintain auditability; avoid opaque snaps except where sandboxing is desired.

Chromium note (Ubuntu 24.04):* chromium-browser via APT may install a Snap backend.

If you want strictly non-snap Chromium, consider Flatpak (requires enabling Flatpak) or an alternate PPA (advanced users only). Otherwise, accept Chromium as a snap-acceptable exception.

Snap refresh discipline (optional):*

To control auto-updates for reproducibility:

sudo snap set system refresh.timer=sat,23:00
sudo snap set system refresh.metered=hold

Commands

# GNOME utilities & fonts
sudo apt install -y gnome-tweaks gparted terminator fonts-firacode

# Browser & editor
sudo apt install -y chromium-browser

# VS Code (official repo)
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | \
  sudo tee /etc/apt/trusted.gpg.d/microsoft.gpg >/dev/null
echo "deb [arch=amd64] https://packages.microsoft.com/repos/code stable main" | \
  sudo tee /etc/apt/sources.list.d/vscode.list >/dev/null
sudo apt update && sudo apt install -y code

# Utilities
sudo apt install -y p7zip-full libreoffice

# Notepad++ (snap; sandbox acceptable)
sudo snap install notepad-plus-plus --classic

# Dark theme default
gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita-dark'

Verification

code --version
chromium --version
notepad-plus-plus -v

[proof-hash phase-3_desktop_stack 20251011] f8a2bfb0c9df104d0decc7b56c417af44764f3aee76d22c22142c23860ef9dfb

4. Development & Runtime Stack

Explanation

Provide deterministic environments for Python, Node, Docker, Java, and local TLS tooling. All binaries installed via official repositories; versions logged for reproducibility.

TLS key placement security fix:*

Place localhost.crt in /etc/ssl/certs/ and the private key localhost.key in /etc/ssl/private/ with restrictive permissions.

Commands

# Python
sudo apt install -y python3-venv pipx
pipx ensurepath

# Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v && npm -v

# Docker & Compose
sudo apt install -y ca-certificates gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker helix

# Java (OpenJDK 17)
sudo apt install -y openjdk-17-jdk
java -version

# Certbot + self-signed localhost cert (manual/local use)
sudo apt install -y certbot
sudo openssl req -x509 -newkey rsa:4096 -keyout localhost.key -out localhost.crt \
  -sha256 -days 365 -nodes -subj "/CN=localhost"

# Correct file placement & perms (SECURE)
sudo install -m 0644 localhost.crt /etc/ssl/certs/localhost.crt
sudo install -m 0600 localhost.key /etc/ssl/private/localhost.key

Verification

docker --version
java -version
openssl x509 -in /etc/ssl/certs/localhost.crt -noout -subject -dates
ls -l /etc/ssl/private/localhost.key   # expect -rw------- (600)

[proof-hash phase-4_dev_runtime 20251011] a91cbf3fda25a9e2e3c624e15b923870d440e3e9a8f07db7e7648a1f0e29de22

5. Helix Directory Structure & Permissions

Explanation

Define a consistent hierarchy under /opt/helix for all operational data.

Commands

sudo mkdir -p /opt/helix/{bin,config,proofs,sessions,observability,logs,ai,docs}
sudo chown -R helix:helix /opt/helix
sudo chmod -R 750 /opt/helix

# Baseline proof entry
echo "HELIX directory initialized $(date -u)" \
 | sudo tee /opt/helix/proofs/phase-5_structure_init.log
sha256sum /opt/helix/proofs/phase-5_structure_init.log \
 | sudo tee /opt/helix/proofs/phase-5_structure_init_$(date +%F).sha256

Verification

tree -L 1 /opt/helix
cat /opt/helix/proofs/phase-5_structure_init_*.sha256

[proof-hash phase-5_structure 20251011] 6f7335a31f7ab6df27cb3a1687d6944eb631a943e49a32f1f68fa9d8a60e6a37

6. Security & Governance Layer

Explanation

Helix workstations prioritize verifiable custody over convenience. This phase establishes firewall defaults, fail2ban, audit logging, and cryptographic signing chains.

Commands

# --- UFW baseline ---
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw enable
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

# --- Audit log directory ---
sudo mkdir -p /opt/helix/logs
sudo touch /opt/helix/logs/audit.log
sudo chown helix:helix /opt/helix/logs/audit.log

# --- Audit log tailer service ---
sudo tee /etc/systemd/system/helix-auditlog.service > /dev/null <<'EOF'
[Unit]
Description=Helix Audit Log Tail
After=multi-user.target
[Service]
ExecStart=/bin/bash -c "journalctl -f -u helix-* >> /opt/helix/logs/audit.log"
Restart=always
[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable helix-auditlog
sudo systemctl start helix-auditlog

# --- GPG key setup ---
gpg --full-generate-key        # Type: Ed25519 | Comment: Helix Signer
gpg --list-secret-keys --keyid-format=long
gpg --armor --export helix@ai.helixprojectai.com \
  | tee /opt/helix/proofs/helix_signer_ed25519.pub

Verification

sudo ufw status verbose
sudo tail -n5 /opt/helix/logs/audit.log
gpg --show-keys --fingerprint /opt/helix/proofs/helix_signer_ed25519.pub

[proof-hash phase-6_security_governance 20251011] 69cb9a00e841ee57a537d2384be009c57a2fa8db2a6990c44497c13ad91c1e12

7. Developer Quality-of-Life Layer

Explanation

Operators should enjoy a calm, readable environment that communicates system state. This section configures shell ergonomics, project-scoped environments, and visual clarity.

Commands

sudo apt install -y direnv
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
echo 'export HELIX_ENV=dev' >> ~/.bashrc
echo 'PS1="[\u@\h \W($HELIX_ENV)]\$ "' >> ~/.bashrc
source ~/.bashrc
sudo apt install -y fish lsd fd-find tree

# --- VS Code extensions ---
code --install-extension redhat.vscode-yaml
code --install-extension ms-python.python
code --install-extension ms-azuretools.vscode-docker
code --install-extension ms-vscode-remote.remote-ssh
code --install-extension yzhang.markdown-all-in-one
code --install-extension eamodio.gitlens
code --install-extension humao.rest-client
code --install-extension bierner.markdown-preview-github-styles

# --- MOTD banner ---
echo "Welcome to Helix Workstation Node — Custody-First Environment" | sudo tee /etc/motd

# --- Terminator color profile ---
mkdir -p ~/.config/terminator
echo "[[profiles]]
  [[default]]
  background_color = '#1e1e1e'
  foreground_color = '#c0c0c0'
  cursor_color = '#00ffcc'" > ~/.config/terminator/config

Verification

echo $HELIX_ENV
code --list-extensions | grep yaml
cat /etc/motd

[proof-hash phase-7_dev_qol 20251011] 00a8b23f8ac4d37c807bce7d884cb013e23a87e385f20b62c73237c9e6c86ed3

8. Observability & Metrics (Optional)

Explanation

Local dashboards can visualize Helix service metrics. Grafana + Prometheus containers suffice for workstation telemetry without cloud dependency.

Commands

sudo docker run -d --name grafana \
  -p 3000:3000 -v grafana-storage:/var/lib/grafana grafana/grafana
sudo docker run -d --name prometheus \
  -p 9090:9090 -v prometheus-storage:/prometheus prom/prometheus
sudo docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 qdrant/qdrant

Verification

sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

[proof-hash phase-8_observability 20251011] 4de81a8c0f38157bfc33e2ffdd6a03a35a7b163b01572a6f6228b6a18e7d0a92

9. Backup & Portability

Explanation

Helix nodes must maintain proof-consistent backups. Use Timeshift for local rollbacks, rclone for encrypted off-site mirrors, and tar + hash snapshots for immutable archives.

Commands

# --- Timeshift nightly cron ---
sudo crontab -e
# 0 23 * * * /usr/bin/timeshift --create --comments "Nightly Helix Snapshot"

# --- Rclone encrypted remote ---
sudo apt install -y rclone
rclone config create helix-remote drive
rclone copy /opt/helix/proofs helix-remote:helix-proofs-backup

# --- Tar snapshot + hash ---
sudo tar czf /opt/helix/proofs/helix-snapshot-$(date +%F).tar.gz /opt/helix
sha256sum /opt/helix/proofs/helix-snapshot-*.tar.gz \
  | tee /opt/helix/proofs/SHA256SUMS

Verification

grep "helix-snapshot" /opt/helix/proofs/SHA256SUMS | tail -n1
rclone ls helix-remote:helix-proofs-backup | tail -n1

[proof-hash phase-9_backup_portability 20251011] d4027b6c42b36a1d0d3432e4f21a9e17f8a40e11dcb76a0a7f62f8c08ac9215b

10. Final Verification & Sign-Off

Explanation

Re-hash and sign all proof artifacts to certify that the workstation has been initialized in a verifiable, reproducible state.

Commands

cd /opt/helix/proofs
cat phase-*20251011.sha256 > consolidated-20251011.sha256
sha256sum consolidated-20251011.sha256 > consolidated-20251011.sha256sum
gpg --output consolidated-20251011.sig --sign consolidated-20251011.sha256
gpg --verify consolidated-20251011.sig consolidated-20251011.sha256

Verification

ls -lh consolidated-20251011.*

[proof-hash phase-10_final_signoff 20251011] 3e96712f2c9e5cfab5c2285ccfe89f90fd8749b482c5ee273f9de3a48b713f54

Appendix A — Quick Reference Directory Map

/opt/helix
├── ai/                → local LLMs and adapters
├── bin/               → operational scripts
├── config/            → YAML / JSON configuration
├── docs/              → this runbook & related papers
├── logs/              → live and audit logs
├── observability/     → dashboards & metrics
├── proofs/            → cryptographic proofs and snapshots
├── sessions/          → runtime data
└── proofs/SHA256SUMS  → master checksum manifest

Appendix B — Helix Stats Script

#!/usr/bin/env bash
echo "Helix Node Status — $(date)"
df -h /opt/helix
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
journalctl -u helix-* --since today | tail -20

Save as `/opt/helix/bin/helix-stats` and mark executable (`chmod +x`).

Epilogue · Helix Ethos Reflection

Trust is built by proof, not by promise. Custody precedes capability. Transparency is the foundation of continuity.

This workstation is now a verifiable Helix node. Future collaborators can reproduce, audit, or extend it without guesswork.

HELIX_CLEAN_INSTALL_RUNBOOK_v1.0
sha256: e47325b8713a2b0e58d8e7a221314f5bc93ce70de6a0a648a9055b5aab36b8b7

License

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy at http://www.apache.org/licenses/LICENSE-2.0

This page is expressly licensed under Apache 2.0.

The default wiki footer does not override this license.*

Canonical Source

Canonical Markdown file: `/opt/helix/docs/HELIX_CLEAN_INSTALL_RUNBOOK_v1.0.md` SHA-256: e47325b8713a2b0e58d8e7a221314f5bc93ce70de6a0a648a9055b5aab36b8b7

Anonymous

Search

HELIX CLEAN INSTALL RUNBOOK v1.0: Difference between revisions

Latest revision as of 10:21, 11 October 2025

HELIX CLEAN INSTALL RUNBOOK v1.0

🌐 Helix Ethos

Document Header

1. System Preparation

Explanation

Commands

Verification

2. Base Tools & Updates

Explanation

Commands

Verification

3. Desktop & Productivity Stack

Explanation

Commands

Verification

4. Development & Runtime Stack

Explanation

Commands

Verification

5. Helix Directory Structure & Permissions

Explanation

Commands

Verification

6. Security & Governance Layer

Explanation

Commands

Verification

7. Developer Quality-of-Life Layer

Explanation

Commands

Verification

8. Observability & Metrics (Optional)

Explanation

Commands

Verification

9. Backup & Portability

Explanation

Commands

Verification

10. Final Verification & Sign-Off

Explanation

Commands

Verification

Appendix A — Quick Reference Directory Map

Appendix B — Helix Stats Script

Epilogue · Helix Ethos Reflection

License

Canonical Source

See Also

Navigation

Wiki tools

Page tools

Categories