Revision as of 10:12, 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.

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

sudo mkdir -p /opt/helix/proofs
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

Verification

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

[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.

Commands

sudo apt install -y gnome-tweaks gparted terminator fonts-firacode
sudo apt install -y chromium-browser
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | \
  sudo tee /etc/apt/trusted.gpg.d/microsoft.gpg
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/code stable main" \
  > /etc/apt/sources.list.d/vscode.list'
sudo apt update && sudo apt install -y code
sudo apt install -y p7zip-full libreoffice
sudo snap install notepad-plus-plus --classic
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.

Commands

sudo apt install -y python3-venv pipx
pipx ensurepath
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
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
sudo apt install -y openjdk-17-jdk
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"
sudo install -m 0644 localhost.crt /etc/ssl/certs/localhost.crt
sudo install -m 0600 localhost.key /etc/ssl/private/localhost.key
sudo openssl x509 -in /etc/ssl/certs/localhost.crt -noout -subject -dates

Verification

docker --version
java -version
openssl x509 -in /etc/ssl/certs/localhost.crt -noout -subject -dates

[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
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

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow from 127.0.0.1
sudo ufw enable
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
sudo mkdir -p /opt/helix/logs
sudo touch /opt/helix/logs/audit.log
sudo chown helix:helix /opt/helix/logs/audit.log

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 --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 | grep 127.0.0.1
sudo tail -n5 /opt/helix/logs/audit.log
gpg --list-keys | grep helix

[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

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

echo "Welcome to Helix Workstation Node — Custody-First Environment" | sudo tee /etc/motd
mkdir -p ~/.config/terminator
echo "[[profiles]]\n  [[default]]\n  background_color = \"#1e1e1e\"\n  foreground_color = \"#c0c0c0\"\n  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

sudo crontab -e
# Add:  0 23 * * * /usr/bin/timeshift --create --comments "Nightly Helix Snapshot"

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

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, Ollama, 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

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

Revision as of 10:12, 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