Skip to content

LIFECYCLE.md

Latest commit

 

History

History
133 lines (96 loc) · 4.46 KB

LIFECYCLE.md

File metadata and controls

133 lines (96 loc) · 4.46 KB

LIFECYCLE

Canonical lifecycle model

The stack should be operated through explicit profiles, optional presets, and a systemd user entrypoint.

Deployment preparation

The repository now includes deployment bridge scripts under scripts/:

  • aoa-doctor
  • aoa-install-layout
  • aoa-sync-configs
  • aoa-bootstrap-configs
  • aoa-check-layout
  • aoa-install-systemd
  • aoa-first-run

For Windows-host orchestration through WSL, the repository also includes:

  • aoa.ps1
  • aoa-doctor-win.ps1
  • aoa-bootstrap-wsl.ps1

They help bridge from a source checkout into the deployed runtime tree under ${AOA_STACK_ROOT}.

Profile and preset introspection

The repository also includes:

  • aoa-preset-profiles
  • aoa-profile-modules
  • aoa-profile-endpoints
  • aoa-render-services
  • aoa-render-config

These helpers make it easy to see what a preset, profile, or profile-combination will activate before you start it. aoa-render-services and aoa-render-config are the deeper runtime-truth layer because they come from the composed runtime view rather than just docs or module lists.

You may optionally layer bounded overlays after the canonical module list through AOA_EXTRA_COMPOSE_FILES on Linux or -Overlay on the Windows bridge.

When ${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json exists, the wrapper scripts also auto-apply its validated_settings and any recommended_overlays that actually touch the currently selected services before compose resolution. Explicit environment variables still win, and you can disable the auto-apply bridge with AOA_MACHINE_FIT_AUTO_APPLY=false.

Human-facing wrappers

The repository also includes these runtime wrappers under scripts/:

  • aoa-up
  • aoa-down
  • aoa-status
  • aoa-logs
  • aoa-smoke
  • aoa-wait

They resolve presets and profiles into an ordered compose module list.

On Windows, pwsh -File scripts/aoa.ps1 <command> is the host-facing wrapper that forwards into the same Linux command surface.

Composition layers

You can operate:

  • one profile
  • several composed profiles
  • one or more presets
  • presets plus extra profiles

Examples:

aoa-up --profile agentic --profile tools
aoa-up --profile agentic,tools,observability
aoa-up --preset agent-full
aoa-up --preset agent-tools --profile observability

The order matters because profile ordering is preserved. Optional layers such as tools and observability should usually come after the base profile. Presets expand before direct --profile additions.

Low-level canonical path

Expected pattern:

  • one or more presets and profiles resolve to an ordered profile list
  • that profile list resolves to an ordered module list
  • machine-fit validated settings are applied next when a current machine-fit record exists and auto-apply is enabled
  • compose files are applied in that order, with matching machine-fit recommended overlays first and any explicit bounded extra compose overlays appended after them
  • the rendered Compose view is inspectable before launch
  • systemd user unit becomes the stable operator entrypoint

Bootstrap manual pattern

Until wrappers are installed into the live runtime path, the intended manual shape is:

cd /srv/abyss-stack/Configs
podman compose \
  -f compose/modules/10-storage.yml \
  -f compose/modules/20-orchestration.yml \
  -f compose/modules/30-local-inference.yml \
  up -d

Optional modules should be layered explicitly rather than assumed.

Systemd user surface

A first unit skeleton now lives at:

  • systemd/user/podman-compose-abyss.service

Its expected deployed location is:

  • ~/.config/systemd/user/podman-compose-abyss.service

It assumes the deployed runtime tree exists under:

  • /srv/abyss-stack/Configs

Path note

The wrapper scripts treat the deployed Linux runtime path as distinct from any source checkout path. This is what makes the repository Fedora-first while still usable from Windows-oriented editing workflows.

Truth progression must stay explicit:

  • source_authored
  • deployed
  • trial_proven
  • live_available

Do not collapse those states into one word such as "landed". A source-authored change becomes deployed only after aoa-sync-configs updates /srv/abyss-stack/Configs. Use python scripts/validate_stack.py --parity-check when repo-managed surfaces should match the deployed Configs mirror.

Profile rule

A profile is a declared set of modules. A module is a declared concern. Nothing should start just because it once happened to live in a giant file.