HELIX CLEAN INSTALL RUNBOOK v1.0: Difference between revisions

From Helix Project Wiki
VisualWikitext
(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...")
 
No edit summary
Line 1: Line 1:
<noinclude>
{{DISPLAYTITLE:HELIX CLEAN INSTALL RUNBOOK v1.0}}
</noinclude>
= HELIX CLEAN INSTALL RUNBOOK v1.0 =
= HELIX CLEAN INSTALL RUNBOOK v1.0 =
'''© 2025 Helix AI Innovations Inc. — Apache License 2.0'''
'''© 2025 Helix AI Innovations Inc. — Apache License 2.0'''
Line 4: Line 8:
----
----


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


Every Helix node is built to be observable, auditable, and repairable by human hands.
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'' —   
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.
a reproducible, custody-first Ubuntu 24.04 GNOME environment for R&D, governance, and proof issuance.


== 0. Document Header ==
----
{| class="wikitable"
 
|-
== Document Header ==
! Field
{| class="wikitable" style="width:70%"
! Value
! Field !! Value
|-
|-
| '''Version'''
| Version || v1.0
| v1.0
|-
|-
| '''Date'''
| Date || 2025-10-11
| 2025-10-11
|-
|-
| '''Author'''
| Author || Stephen Hope (Helix AI Innovations Inc.)
| Stephen Hope (Helix AI Innovations Inc.)
|-
|-
| '''System'''
| System || Dell Workstation — Ubuntu 24.04 LTS Desktop (GNOME)
| Dell Workstation — Ubuntu 24.04 LTS Desktop (GNOME)
|-
|-
| '''Hostname'''
| Hostname || helix-core
| <code>helix-core</code>
|-
|-
| '''License'''
| License || Apache 2.0
| Apache 2.0
|-
|-
| '''Hash Standard'''
| Hash Standard || SHA-256
| SHA-256
|-
|-
| '''Sign Standard'''
| Sign Standard || Ed25519 (GPG)
| Ed25519 (GPG)
|-
|-
| '''Mode'''
| Mode || Manual Execution / Proof-Aware Logging
| Manual Execution / Proof-Aware Logging
|-
|-
| '''Intended Location'''
| Intended Location || /opt/helix/docs/HELIX_CLEAN_INSTALL_RUNBOOK_v1.0.md
| <code>/opt/helix/docs/HELIX_CLEAN_INSTALL_RUNBOOK_v1.0.md</code>
|}
|}
----


== 1. System Preparation ==
== 1. System Preparation ==
=== Explanation ===
=== Explanation ===
This section ensures the Dell workstation starts from a trusted, deterministic state.   
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.
You’ll perform a clean Ubuntu 24.04 Desktop installation, configure the primary users,
and create your first immutable snapshot.


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# --- BIOS ---
# BIOS: enable UEFI + Secure Boot + AHCI, disable Legacy/CSM, ensure TPM enabled.
# 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 update && sudo apt -y full-upgrade
sudo apt install -y timeshift
sudo apt install -y timeshift
Line 78: Line 62:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo timeshift --list | grep HELIX_BASELINE_v1.0
sudo timeshift --list | grep HELIX_BASELINE_v1.0
# Expected: Snapshot ID with timestamp and 'OK' status.
</syntaxhighlight>
</syntaxhighlight>


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


== 2. Base Tools & Updates ==
== 2. Base Tools & Updates ==
=== Explanation ===
=== Explanation ===
Install reproducible command-line essentials and capture a hashable record of package versions.
Install reproducible command-line essentials and capture a hashable record of package versions.
Everything here forms the operational substrate for later Helix services.
Everything here forms the operational substrate for later Helix services.


Line 92: Line 78:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo apt update
sudo apt update
sudo apt install -y \
sudo apt install -y git curl wget jq unzip build-essential python3-pip tmux vim \
  git curl wget jq unzip build-essential python3-pip tmux vim \
   ufw fail2ban ripgrep btop bat exa tldr ncdu apt-clone
   ufw fail2ban ripgrep btop bat exa tldr ncdu apt-clone


# Freeze package state for proofs
sudo mkdir -p /opt/helix/proofs
sudo mkdir -p /opt/helix/proofs
sudo apt-clone clone /opt/helix/proofs/apt-state-$(date +%F)
sudo apt-clone clone /opt/helix/proofs/apt-state-$(date +%F)
# Optional: register hash
sha256sum /opt/helix/proofs/apt-state-*.tar.gz \
sha256sum /opt/helix/proofs/apt-state-*.tar.gz \
   | sudo tee /opt/helix/proofs/phase-2_base_tools_$(date +%F).sha256
   | sudo tee /opt/helix/proofs/phase-2_base_tools_$(date +%F).sha256
Line 108: Line 90:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
head -n1 /opt/helix/proofs/phase-2_base_tools_*.sha256
head -n1 /opt/helix/proofs/phase-2_base_tools_*.sha256
# Verify file count and reproducible hash.
</syntaxhighlight>
</syntaxhighlight>


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


== 3. Desktop & Productivity Stack ==
== 3. Desktop & Productivity Stack ==
=== Explanation ===
=== Explanation ===
Install the graphical and everyday-productivity layer.
Install the graphical and everyday-productivity layer.
Use APT or official .deb packages to maintain auditability; avoid opaque snaps except where sandboxing is desired.
Use APT or official .deb packages to maintain auditability; avoid opaque snaps except where sandboxing is desired.


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# GNOME utilities
sudo apt install -y gnome-tweaks gparted terminator fonts-firacode
sudo apt install -y gnome-tweaks gparted terminator fonts-firacode
# Browsers & editors (APT / .deb)
sudo apt install -y chromium-browser
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
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | \
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
  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 update && sudo apt install -y code
# Utilities
sudo apt install -y p7zip-full libreoffice
sudo apt install -y p7zip-full libreoffice
sudo snap install notepad-plus-plus --classic
sudo snap install notepad-plus-plus --classic
# Theme defaults
gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita-dark'
gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita-dark'
</syntaxhighlight>
</syntaxhighlight>
Line 145: Line 124:
</syntaxhighlight>
</syntaxhighlight>


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


== 4. Development & Runtime Stack ==
== 4. Development & Runtime Stack ==
=== Explanation ===
=== Explanation ===
Provide deterministic environments for Python, Node, Docker, Java, and local TLS tooling.
Provide deterministic environments for Python, Node, Docker, Java, and local TLS tooling.
All binaries installed via official repositories; versions logged for reproducibility.


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# --- Python environment ---
sudo apt install -y python3-venv pipx
sudo apt install -y python3-venv pipx
pipx ensurepath
pipx ensurepath
# --- Node.js 20 LTS ---
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
sudo apt install -y nodejs
node -v && npm -v
# --- Docker & Compose ---
sudo apt install -y ca-certificates gnupg lsb-release
sudo apt install -y ca-certificates gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
   sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
   sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
   https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
   https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   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 apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker helix
sudo usermod -aG docker helix
# --- Java (OpenJDK 17) ---
sudo apt install -y openjdk-17-jdk
sudo apt install -y openjdk-17-jdk
java -version
# --- Certbot (self-signed localhost) ---
sudo apt install -y certbot
sudo apt install -y certbot
sudo openssl req -x509 -newkey rsa:4096 -keyout localhost.key -out localhost.crt -sha256 -days 365 -nodes \
sudo openssl req -x509 -newkey rsa:4096 -keyout localhost.key -out localhost.crt \
  -subj "/CN=localhost"
  -sha256 -days 365 -nodes -subj "/CN=localhost"
sudo mv localhost.* /etc/ssl/certs/
sudo mv localhost.* /etc/ssl/certs/
</syntaxhighlight>
</syntaxhighlight>
Line 194: Line 163:
</syntaxhighlight>
</syntaxhighlight>


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


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


=== Commands ===
=== Commands ===
Line 207: Line 178:
sudo chown -R helix:helix /opt/helix
sudo chown -R helix:helix /opt/helix
sudo chmod -R 750 /opt/helix
sudo chmod -R 750 /opt/helix
# Create baseline proof entry
echo "HELIX directory initialized $(date -u)" \
echo "HELIX directory initialized $(date -u)" \
  | sudo tee /opt/helix/proofs/phase-5_structure_init.log
  | sudo tee /opt/helix/proofs/phase-5_structure_init.log
Line 218: Line 187:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
tree -L 1 /opt/helix
tree -L 1 /opt/helix
# Expect 8 top-level directories listed.
cat /opt/helix/proofs/phase-5_structure_init_*.sha256
cat /opt/helix/proofs/phase-5_structure_init_*.sha256
</syntaxhighlight>
</syntaxhighlight>


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


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# --- UFW baseline ---
sudo ufw default deny incoming
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw default allow outgoing
sudo ufw allow from 127.0.0.1
sudo ufw allow from 127.0.0.1
sudo ufw enable
sudo ufw enable
sudo ufw status verbose
# --- Fail2ban basic setup ---
sudo systemctl enable fail2ban
sudo systemctl enable fail2ban
sudo systemctl start fail2ban
sudo systemctl start fail2ban
sudo systemctl status fail2ban | head -n 5
# --- Audit log directory ---
sudo mkdir -p /opt/helix/logs
sudo mkdir -p /opt/helix/logs
sudo touch /opt/helix/logs/audit.log
sudo touch /opt/helix/logs/audit.log
sudo chown helix:helix /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'
sudo tee /etc/systemd/system/helix-auditlog.service > /dev/null <<'EOF'
[Unit]
[Unit]
Description=Helix Audit Log Tail
Description=Helix Audit Log Tail
After=multi-user.target
After=multi-user.target
[Service]
[Service]
ExecStart=/bin/bash -c "journalctl -f -u helix-* >> /opt/helix/logs/audit.log"
ExecStart=/bin/bash -c "journalctl -f -u helix-* >> /opt/helix/logs/audit.log"
Restart=always
Restart=always
[Install]
[Install]
WantedBy=multi-user.target
WantedBy=multi-user.target
Line 267: Line 228:
sudo systemctl start helix-auditlog
sudo systemctl start helix-auditlog


# --- GPG key setup ---
gpg --full-generate-key   # Type: Ed25519  |  Comment: Helix Signer
gpg --full-generate-key
# Type: Ed25519  |  Expiration: 0 (never)
# Comment: Helix Signer |  Email: helix@ai.helixprojectai.com
gpg --list-secret-keys --keyid-format=long
gpg --list-secret-keys --keyid-format=long
# Export public key for collaborators
gpg --armor --export helix@ai.helixprojectai.com \
gpg --armor --export helix@ai.helixprojectai.com \
   | tee /opt/helix/proofs/helix_signer_ed25519.pub
   | tee /opt/helix/proofs/helix_signer_ed25519.pub
Line 282: Line 238:
sudo ufw status | grep 127.0.0.1
sudo ufw status | grep 127.0.0.1
sudo tail -n5 /opt/helix/logs/audit.log
sudo tail -n5 /opt/helix/logs/audit.log
gpg --verify /opt/helix/proofs/helix_signer_ed25519.pub 2>&1 | head -n5
gpg --list-keys | grep helix
</syntaxhighlight>
</syntaxhighlight>


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


== 7. Developer Quality-of-Life Layer ==
== 7. Developer Quality-of-Life Layer ==
=== Explanation ===
=== Explanation ===
Operators should enjoy a calm, readable environment that communicates system state.
Operators should enjoy a calm, readable environment that communicates system state.
This section configures shell ergonomics, project-scoped environments, and visual clarity.
This section configures shell ergonomics, project-scoped environments, and visual clarity.


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# --- Direnv / Mise ---
sudo apt install -y direnv
sudo apt install -y direnv
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
# --- Bash prompt indicator ---
echo 'export HELIX_ENV=dev' >> ~/.bashrc
echo 'export HELIX_ENV=dev' >> ~/.bashrc
echo 'PS1="[\u@\h \W($HELIX_ENV)]\$ "' >> ~/.bashrc
echo 'PS1="[\u@\h \W($HELIX_ENV)]\$ "' >> ~/.bashrc
source ~/.bashrc
source ~/.bashrc
sudo apt install -y fish lsd fd-find tree


# --- 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 redhat.vscode-yaml
code --install-extension ms-python.python
code --install-extension ms-python.python
Line 320: Line 270:
code --install-extension bierner.markdown-preview-github-styles
code --install-extension bierner.markdown-preview-github-styles


# --- MOTD banner ---
echo "Welcome to Helix Workstation Node — Custody-First Environment" | sudo tee /etc/motd
echo "Welcome to Helix Workstation Node — Custody-First Environment" \
  | sudo tee /etc/motd
 
# --- Terminator profile colors (optional manual edit) ---
mkdir -p ~/.config/terminator
mkdir -p ~/.config/terminator
echo "[[profiles]]\n  [[default]]\n  background_color = \"#1e1e1e\"\n  foreground_color = \"#c0c0c0\"\n  cursor_color = \"#00ffcc\"" \
echo "[[profiles]]\n  [[default]]\n  background_color = \"#1e1e1e\"\n  foreground_color = \"#c0c0c0\"\n  cursor_color = \"#00ffcc\"" \
Line 337: Line 283:
</syntaxhighlight>
</syntaxhighlight>


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


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


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# --- Grafana ---
sudo docker run -d --name grafana \
sudo docker run -d --name grafana \
   -p 3000:3000 -v grafana-storage:/var/lib/grafana grafana/grafana
   -p 3000:3000 -v grafana-storage:/var/lib/grafana grafana/grafana
# --- Prometheus ---
sudo docker run -d --name prometheus \
sudo docker run -d --name prometheus \
   -p 9090:9090 -v prometheus-storage:/prometheus prom/prometheus
   -p 9090:9090 -v prometheus-storage:/prometheus prom/prometheus
# --- Optional: Qdrant container for local vector storage ---
sudo docker run -d --name qdrant \
sudo docker run -d --name qdrant \
   -p 6333:6333 -p 6334:6334 qdrant/qdrant
   -p 6333:6333 -p 6334:6334 qdrant/qdrant
Line 363: Line 307:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
# Access Grafana → http://localhost:3000  (user: admin / pass: admin)
</syntaxhighlight>
</syntaxhighlight>


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


== 9. Backup & Portability ==
== 9. Backup & Portability ==
=== Explanation ===
=== Explanation ===
All Helix nodes must maintain proof-consistent backups.
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.
Use Timeshift for local rollbacks, rclone for encrypted off-site mirrors,
and tar + hash snapshots for immutable archives.


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# --- Timeshift schedule ---
sudo timeshift --check
sudo crontab -e
sudo crontab -e
# Add line:
# Add: 0 23 * * * /usr/bin/timeshift --create --comments "Nightly Helix Snapshot"
# 0 23 * * * /usr/bin/timeshift --create --comments "Nightly Helix Snapshot"


# --- Rclone encrypted remote (interactive) ---
sudo apt install -y rclone
sudo apt install -y rclone
rclone config create helix-remote drive
rclone config create helix-remote drive
rclone copy /opt/helix/proofs helix-remote:helix-proofs-backup
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
sudo tar czf /opt/helix/proofs/helix-snapshot-$(date +%F).tar.gz /opt/helix
sha256sum /opt/helix/proofs/helix-snapshot-*.tar.gz \
sha256sum /opt/helix/proofs/helix-snapshot-*.tar.gz \
Line 399: Line 341:
</syntaxhighlight>
</syntaxhighlight>


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


== 10. Final Verification & Sign-Off ==
== 10. Final Verification & Sign-Off ==
=== Explanation ===
=== Explanation ===
Re-hash and sign all proof artifacts to certify that the workstation has been initialized in a verifiable, reproducible state.
Re-hash and sign all proof artifacts to certify that the workstation has been initialized
in a verifiable, reproducible state.


=== Commands ===
=== Commands ===
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cd /opt/helix/proofs
cd /opt/helix/proofs
# --- Consolidate hashes ---
cat phase-*20251011.sha256 > consolidated-20251011.sha256
cat phase-*20251011.sha256 > consolidated-20251011.sha256
sha256sum consolidated-20251011.sha256 > consolidated-20251011.sha256sum
sha256sum consolidated-20251011.sha256 > consolidated-20251011.sha256sum
# --- GPG sign the consolidated proof ---
gpg --output consolidated-20251011.sig --sign consolidated-20251011.sha256
gpg --output consolidated-20251011.sig --sign consolidated-20251011.sha256
# --- Verify signature ---
gpg --verify consolidated-20251011.sig consolidated-20251011.sha256
gpg --verify consolidated-20251011.sig consolidated-20251011.sha256
</syntaxhighlight>
</syntaxhighlight>
Line 424: Line 364:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
ls -lh consolidated-20251011.*
ls -lh consolidated-20251011.*
# Expect .sha256, .sha256sum, .sig  (signed within the last few minutes)
</syntaxhighlight>
</syntaxhighlight>


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


== Appendix A — Quick Reference Directory Map ==
== Appendix A — Quick Reference Directory Map ==
<syntaxhighlight lang="kotlin">
<pre>
/opt/helix
/opt/helix
├── ai/                → local LLMs, Ollama, adapters
├── ai/                → local LLMs, Ollama, adapters
├── bin/              → operational scripts (helix-stats, healthcheck)
├── bin/              → operational scripts
├── config/            → YAML / JSON configuration
├── config/            → YAML / JSON configuration
├── docs/              → this runbook & related papers
├── docs/              → this runbook & related papers
Line 442: Line 383:
├── sessions/          → runtime data
├── sessions/          → runtime data
└── proofs/SHA256SUMS  → master checksum manifest
└── proofs/SHA256SUMS  → master checksum manifest
</syntaxhighlight>
</pre>
 
----


== Appendix B — Helix Stats Script (Utility) ==
== Appendix B — Helix Stats Script ==
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
#!/usr/bin/env bash
#!/usr/bin/env bash
Line 453: Line 396:
</syntaxhighlight>
</syntaxhighlight>


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


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


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


<syntaxhighlight lang="makefile">
<pre>
HELIX_CLEAN_INSTALL_RUNBOOK_v1.0
HELIX_CLEAN_INSTALL_RUNBOOK_v1.0
sha256: e47325b8713a2b0e58d8e7a221314f5bc93ce70de6a0a648a9055b5aab36b8b7
sha256: e47325b8713a2b0e58d8e7a221314f5bc93ce70de6a0a648a9055b5aab36b8b7
</syntaxhighlight>
</pre>
 
----
 
== License ==
<pre>
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
</pre>
 
----
 
== Canonical Source ==
''Canonical Markdown file:'' 
`/opt/helix/docs/HELIX_CLEAN_INSTALL_RUNBOOK_v1.0.md` 
SHA-256: <code>e47325b8713a2b0e58d8e7a221314f5bc93ce70de6a0a648a9055b5aab36b8b7</code>
 
----


''End of Runbook — Helix AI Innovations Inc. · All Rights Reserved · Apache License 2.0''
== See Also ==
* [[Helix Core Ethos v1.0]]
* [[TTD Protocol v3.6.4 Skeleton]]
* [[Helix QSR Runbook v1.3]]
* [[RCO Integration Runbook v1.3]]

Revision as of 10:10, 11 October 2025



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, 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 mv localhost.* /etc/ssl/certs/

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

See Also

Retrieved from "https://helixprojectai.com:443/wiki/index.php?title=HELIX_CLEAN_INSTALL_RUNBOOK_v1.0&oldid=196"