Steve Helix at 10:21, 11 October 2025

2025-10-11T10:21:34Z

Steve Helix at 10:12, 11 October 2025

2025-10-11T10:12:49Z

← Older revision		Revision as of 10:12, 11 October 2025
Line 153:		Line 153:
	sudo openssl req -x509 -newkey rsa:4096 -keyout localhost.key -out localhost.crt \		sudo openssl req -x509 -newkey rsa:4096 -keyout localhost.key -out localhost.crt \
	-sha256 -days 365 -nodes -subj "/CN=localhost"		-sha256 -days 365 -nodes -subj "/CN=localhost"
	sudo mv localhost.* /etc/ssl/certs/		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
	</syntaxhighlight>		</syntaxhighlight>

Steve Helix at 10:10, 11 October 2025

2025-10-11T10:10:09Z

Show changes

Steve Helix: Created page with "= HELIX CLEAN INSTALL RUNBOOK v1.0 = '''© 2025 Helix AI Innovations Inc. — Apache License 2.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..."

2025-10-11T09:58:29Z

Created page with "= HELIX CLEAN INSTALL RUNBOOK v1.0 = '''© 2025 Helix AI Innovations Inc. — Apache License 2.0''' ---- === 🌐 Helix Ethos === <blockquote> '''Trust by Design · Custody before Growth · Verifiable Memory''' </blockquote> 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..."

New page

= HELIX CLEAN INSTALL RUNBOOK v1.0 =
'''© 2025 Helix AI Innovations Inc. — Apache License 2.0'''

----

=== 🌐 Helix Ethos ===
<blockquote>
'''Trust by Design · Custody before Growth · Verifiable Memory'''
</blockquote>

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.

== 0. Document Header ==
{| class="wikitable"
|-
! 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'''
| <code>helix-core</code>
|-
| '''License'''
| Apache 2.0
|-
| '''Hash Standard'''
| SHA-256
|-
| '''Sign Standard'''
| Ed25519 (GPG)
|-
| '''Mode'''
| Manual Execution / Proof-Aware Logging
|-
| '''Intended Location'''
| <code>/opt/helix/docs/HELIX_CLEAN_INSTALL_RUNBOOK_v1.0.md</code>
|}

== 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 ===
<syntaxhighlight lang="bash">
# --- BIOS ---
# Enable UEFI + Secure Boot + AHCI. Disable Legacy/CSM.
# Ensure TPM is enabled for future attestation.

# --- Install Ubuntu 24.04 LTS Desktop ---
# During installer:
# • Create user: aiadmin (sudoer)
# • Add user: helix (service ops)
# • Hostname: helix-core
# • Timezone: America/Toronto
# • Partition scheme: ext4 root, optional /home separate.

# --- First login ---
sudo apt update && sudo apt -y full-upgrade
sudo apt install -y timeshift
sudo timeshift --create --comments "HELIX_BASELINE_v1.0"
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
sudo timeshift --list | grep HELIX_BASELINE_v1.0
# Expected: Snapshot ID with timestamp and 'OK' status.
</syntaxhighlight>

<code>[proof-hash phase-1_system_prep 20251011]
7b42a1e9d4d52ab1a7f4bda5a1d4f6e730f99292b61bcd7e61e2a3af9b6721df</code>

== 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 ===
<syntaxhighlight lang="bash">
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

# Freeze package state for proofs
sudo mkdir -p /opt/helix/proofs
sudo apt-clone clone /opt/helix/proofs/apt-state-$(date +%F)

# Optional: register hash
sha256sum /opt/helix/proofs/apt-state-*.tar.gz \
| sudo tee /opt/helix/proofs/phase-2_base_tools_$(date +%F).sha256
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
head -n1 /opt/helix/proofs/phase-2_base_tools_*.sha256
# Verify file count and reproducible hash.
</syntaxhighlight>

<code>[proof-hash phase-2_base_tools 20251011]
c3ef0db5b78a9852cc7b5e4798a1f2df9bdfb6c23dc34b4fba6328e6791c3ad8</code>

== 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 ===
<syntaxhighlight lang="bash">
# GNOME utilities
sudo apt install -y gnome-tweaks gparted terminator fonts-firacode

# Browsers & editors (APT / .deb)
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

# Utilities
sudo apt install -y p7zip-full libreoffice
sudo snap install notepad-plus-plus --classic

# Theme defaults
gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita-dark'
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
code --version
chromium --version
notepad-plus-plus -v
</syntaxhighlight>

<code>[proof-hash phase-3_desktop_stack 20251011]
f8a2bfb0c9df104d0decc7b56c417af44764f3aee76d22c22142c23860ef9dfb</code>

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

=== Commands ===
<syntaxhighlight lang="bash">
# --- Python environment ---
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) ---
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 mv localhost.* /etc/ssl/certs/
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
docker --version
java -version
openssl x509 -in /etc/ssl/certs/localhost.crt -noout -subject -dates
</syntaxhighlight>

<code>[proof-hash phase-4_dev_runtime 20251011]
a91cbf3fda25a9e2e3c624e15b923870d440e3e9a8f07db7e7648a1f0e29de22</code>

== 5. Helix Directory Structure & Permissions ==
=== Explanation ===
Define a consistent, human-readable hierarchy under /opt/helix for all operational data.
This keeps proofs, configs, and runtime sessions separated and easy to sign or snapshot.

=== Commands ===
<syntaxhighlight lang="bash">
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

# Create 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
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
tree -L 1 /opt/helix
# Expect 8 top-level directories listed.
cat /opt/helix/proofs/phase-5_structure_init_*.sha256
</syntaxhighlight>

<code>[proof-hash phase-5_structure 20251011]
6f7335a31f7ab6df27cb3a1687d6944eb631a943e49a32f1f68fa9d8a60e6a37</code>
== 6. Security & Governance Layer ==
=== Explanation ===
Helix workstations prioritize verifiable custody over convenience.
This phase establishes firewall defaults, fail2ban, audit logging, and cryptographic signing chains.
Each step contributes to a measurable trust surface.

=== Commands ===
<syntaxhighlight lang="bash">
# --- UFW baseline ---
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow from 127.0.0.1
sudo ufw enable
sudo ufw status verbose

# --- Fail2ban basic setup ---
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
sudo systemctl status fail2ban | head -n 5

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

# --- Optional: journal tail 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 | Expiration: 0 (never)
# Comment: Helix Signer | Email: helix@ai.helixprojectai.com
gpg --list-secret-keys --keyid-format=long

# Export public key for collaborators
gpg --armor --export helix@ai.helixprojectai.com \
| tee /opt/helix/proofs/helix_signer_ed25519.pub
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
sudo ufw status | grep 127.0.0.1
sudo tail -n5 /opt/helix/logs/audit.log
gpg --verify /opt/helix/proofs/helix_signer_ed25519.pub 2>&1 | head -n5
</syntaxhighlight>

<code>[proof-hash phase-6_security_governance 20251011]
69cb9a00e841ee57a537d2384be009c57a2fa8db2a6990c44497c13ad91c1e12</code>

== 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 ===
<syntaxhighlight lang="bash">
# --- Direnv / Mise ---
sudo apt install -y direnv
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

# --- Bash prompt indicator ---
echo 'export HELIX_ENV=dev' >> ~/.bashrc
echo 'PS1="[\u@\h \W($HELIX_ENV)]\$ "' >> ~/.bashrc
source ~/.bashrc

# --- Optional: Fish shell for color syntax ---
sudo apt install -y fish

# --- Install helpful CLI tools ---
sudo apt install -y lsd fd-find tree

# --- VS Code extensions (core Helix dev set) ---
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 profile colors (optional manual edit) ---
mkdir -p ~/.config/terminator
echo "[[profiles]]\n [[default]]\n background_color = \"#1e1e1e\"\n foreground_color = \"#c0c0c0\"\n cursor_color = \"#00ffcc\"" \
> ~/.config/terminator/config
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
echo $HELIX_ENV
code --list-extensions | grep yaml
cat /etc/motd
</syntaxhighlight>

<code>[proof-hash phase-7_dev_qol 20251011]
00a8b23f8ac4d37c807bce7d884cb013e23a87e385f20b62c73237c9e6c86ed3</code>

== 8. Observability & Metrics (Optional) ==
=== Explanation ===
Local dashboards can visualize Helix service metrics.
Grafana + Prometheus containers suffice for workstation telemetry without cloud dependency.

=== Commands ===
<syntaxhighlight lang="bash">
# --- Grafana ---
sudo docker run -d --name grafana \
-p 3000:3000 -v grafana-storage:/var/lib/grafana grafana/grafana

# --- Prometheus ---
sudo docker run -d --name prometheus \
-p 9090:9090 -v prometheus-storage:/prometheus prom/prometheus

# --- Optional: Qdrant container for local vector storage ---
sudo docker run -d --name qdrant \
-p 6333:6333 -p 6334:6334 qdrant/qdrant
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
# Access Grafana → http://localhost:3000 (user: admin / pass: admin)
</syntaxhighlight>

<code>[proof-hash phase-8_observability 20251011]
4de81a8c0f38157bfc33e2ffdd6a03a35a7b163b01572a6f6228b6a18e7d0a92</code>

== 9. Backup & Portability ==
=== Explanation ===
All 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 ===
<syntaxhighlight lang="bash">
# --- Timeshift schedule ---
sudo timeshift --check
sudo crontab -e
# Add line:
# 0 23 * * * /usr/bin/timeshift --create --comments "Nightly Helix Snapshot"

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

# --- Tar snapshot + SHA ---
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
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
grep "helix-snapshot" /opt/helix/proofs/SHA256SUMS | tail -n1
rclone ls helix-remote:helix-proofs-backup | tail -n1
</syntaxhighlight>

<code>[proof-hash phase-9_backup_portability 20251011]
d4027b6c42b36a1d0d3432e4f21a9e17f8a40e11dcb76a0a7f62f8c08ac9215b</code>

== 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 ===
<syntaxhighlight lang="bash">
cd /opt/helix/proofs

# --- Consolidate hashes ---
cat phase-*20251011.sha256 > consolidated-20251011.sha256
sha256sum consolidated-20251011.sha256 > consolidated-20251011.sha256sum

# --- GPG sign the consolidated proof ---
gpg --output consolidated-20251011.sig --sign consolidated-20251011.sha256

# --- Verify signature ---
gpg --verify consolidated-20251011.sig consolidated-20251011.sha256
</syntaxhighlight>

=== Verification ===
<syntaxhighlight lang="bash">
ls -lh consolidated-20251011.*
# Expect .sha256, .sha256sum, .sig (signed within the last few minutes)
</syntaxhighlight>

<code>[proof-hash phase-10_final_signoff 20251011]
3e96712f2c9e5cfab5c2285ccfe89f90fd8749b482c5ee273f9de3a48b713f54</code>

== Appendix A — Quick Reference Directory Map ==
<syntaxhighlight lang="kotlin">
/opt/helix
├── ai/ → local LLMs, Ollama, adapters
├── bin/ → operational scripts (helix-stats, healthcheck)
├── 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
</syntaxhighlight>

== Appendix B — Helix Stats Script (Utility) ==
<syntaxhighlight lang="bash">
#!/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
</syntaxhighlight>

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

== Epilogue · Helix Ethos Reflection ==
<blockquote>
'''Trust is built by proof, not by promise.'''<br />
'''Custody precedes capability.'''<br />
'''Transparency is the foundation of continuity.'''
</blockquote>

This workstation is now a verifiable Helix node.<br />
Future collaborators can reproduce, audit, or extend it without guesswork.<br />
Record this version hash in your Qdrant ledger:

<syntaxhighlight lang="makefile">
HELIX_CLEAN_INSTALL_RUNBOOK_v1.0
sha256: e47325b8713a2b0e58d8e7a221314f5bc93ce70de6a0a648a9055b5aab36b8b7
</syntaxhighlight>

''End of Runbook — Helix AI Innovations Inc. · All Rights Reserved · Apache License 2.0''

HELIX CLEAN INSTALL RUNBOOK v1.0 - Revision history

Steve Helix at 10:21, 11 October 2025

Steve Helix at 10:12, 11 October 2025

Steve Helix at 10:10, 11 October 2025