Skip to content

INSTALLER-ARCHITECTURE.md

Latest commit

 

History

History
155 lines (124 loc) · 7.39 KB

INSTALLER-ARCHITECTURE.md

File metadata and controls

155 lines (124 loc) · 7.39 KB

Installer Architecture

The Dream Server installer is modular — 6 libraries and 13 phases, each in its own file. This guide is your map to understanding, using, and customizing the installer.

Directory Tree

installers/
  lib/                        # Pure libraries — define functions, no side effects
    constants.sh              #   Colors, paths, VERSION, timezone detection
    logging.sh                #   log(), success(), warn(), error(), install_elapsed()
    ui.sh                     #   CRT theme: typing effects, spinners, boot splash, lore
    detection.sh              #   GPU detection, capability profiles, backend contracts, secure boot fix
    tier-map.sh               #   resolve_tier_config() — tier → model/GGUF/context
    compose-select.sh         #   resolve_compose_config() — compose overlay files + flags
  phases/                     # Sequential install steps — execute on source
    01-preflight.sh           #   Root/OS/tools checks, existing installation check
    02-detection.sh           #   Hardware detection → tier assignment → compose config
    03-features.sh            #   Interactive feature selection menu
    04-requirements.sh        #   RAM, disk, GPU, and port availability checks
    05-docker.sh              #   Install Docker, Docker Compose, NVIDIA Container Toolkit
    06-directories.sh         #   Create dirs, copy source, generate .env, configure services
    07-devtools.sh            #   Install Claude Code, Codex CLI, OpenCode
    08-images.sh              #   Build image pull list and download all Docker images
    09-offline.sh             #   Configure M1 offline/air-gapped operation
    10-amd-tuning.sh          #   AMD APU sysctl, modprobe, GRUB, and tuned setup
    11-services.sh            #   Download GGUF model, generate models.ini, launch stack
    12-health.sh              #   Verify services responding, configure Perplexica, pre-download STT
    13-summary.sh             #   URLs, desktop shortcut, sidebar pin, summary JSON
install-core.sh               # Orchestrator: trap → source libs → parse args → source phases

How It Works

Libraries are safe to source. Every file in lib/ defines functions only — no side effects. Sourcing them loads function definitions and constants into the shell without executing anything. They must be sourced in order because later libraries depend on earlier ones (e.g., logging.sh uses color codes from constants.sh).

Phases execute immediately when sourced. Each file in phases/ is a self-contained install step that runs its logic the moment source evaluates it. Phases rely on the functions defined by lib/ and on global variables set by earlier phases (e.g., phase 04 checks the GPU tier assigned by phase 02).

The orchestrator is thin. install-core.sh (~150 lines) does exactly three things: set up interrupt traps, source the 6 libraries, parse CLI arguments, then source the 13 phases in order. All files share one global bash namespace — everything is sourced, not exec'd.

File Header Convention

Every module uses a standardized header:

#!/bin/bash
# ============================================================================
# Dream Server Installer — <Module Name>
# ============================================================================
# Part of: installers/lib/   (or installers/phases/)
# Purpose: <one-line description>
#
# Expects: <comma-separated list of globals/functions this file reads>
# Provides: <comma-separated list of globals/functions this file defines>
#
# Modder notes:
#   <when and why you'd edit this file>
# ============================================================================
Field Meaning
Purpose What this file does in one line
Expects Globals and functions that must already exist when this file is sourced
Provides Globals and functions this file creates for later files to use
Modder notes Plain-English hint for customizers

If you add a new file, copy this template. The Expects / Provides chain is how you trace data flow without reading every line.

Mod Recipes

Common customizations and exactly where to make them:

Recipe What to edit How
Add a hardware tier lib/tier-map.sh + lib/detection.sh Add a case in resolve_tier_config() (tier-map.sh) and a detection path in detection.sh. Also update lib/compose-select.sh if a new compose overlay is needed, and add the tier to QUICKSTART.md and README.md hardware tables.
Swap CRT theme colors lib/constants.sh Change the ANSI escape code variables (GRN, AMB, RED, etc.) near the top
Change lore messages lib/ui.sh Edit the LORE_MESSAGES[] array — add, remove, or reword entries
Change boot splash lib/ui.sh Edit the show_stranger_boot() function — it renders the CRT startup sequence
Skip a phase install-core.sh Comment out or remove the source line for that phase (e.g., remove phase 07 to skip dev tools)
Add a new phase installers/phases/ Create a numbered .sh file with the standard header, then add a source line in install-core.sh in the right order
Swap inference backend lib/compose-select.sh Change the compose overlay logic in resolve_compose_config() to point at different compose files
Change model downloads phases/11-services.sh Edit the GGUF download logic or add new model files
Add a service health check phases/12-health.sh Add a new check_service() call for your service
Change minimum requirements phases/04-requirements.sh Adjust RAM/disk/VRAM thresholds per tier

Cross-Platform Architecture

What's shared vs platform-specific across the installer:

Layer Shared Platform-specific
Colors, version, paths lib/constants.sh —
Logging lib/logging.sh —
CRT UI / spinners lib/ui.sh —
GPU detection lib/detection.sh Backend contract JSONs (config/backends/)
Tier → model mapping lib/tier-map.sh —
Compose selection lib/compose-select.sh Per-backend compose overlays
Pre-flight checks phases/01-preflight.sh —
Docker setup phases/05-docker.sh NVIDIA Container Toolkit vs ROCm
AMD system tuning — phases/10-amd-tuning.sh (AMD only)
Health checks phases/12-health.sh Port/service differences per backend

Testing Your Mods

Syntax check all installer files

for f in installers/lib/*.sh installers/phases/*.sh install-core.sh; do
  bash -n "$f"
done

If any file has a syntax error, bash -n will print the file name and line number.

Dry-run (no actual installs)

bash install-core.sh --dry-run --non-interactive --skip-docker --force

This walks through every phase, printing what would happen without making changes.

Smoke tests

bash tests/smoke/linux-nvidia.sh
bash tests/smoke/linux-amd.sh
bash tests/smoke/wsl-logic.sh
bash tests/smoke/macos-dispatch.sh

Full validation suite

bash scripts/simulate-installers.sh
bash tests/integration-test.sh

See Also