lighthouse Deployment Design

This document describes the implementation-facing design of the Lighthouse deployment pipeline.

Table of Contents

• Goals
• Pipeline Stages
• Runtime Layout
• Source Discovery
• Materialization Model
• Deployment Model
• State and Retention

Goals

The pipeline is designed to:

• run unattended from cron under the lighthouse user
• remain directly callable by hand through the same CLI
• treat Git repositories as the source of truth for content
• emit deterministic Jekyll-ready Markdown with explicit permalinks
• deploy through atomic release-directory symlink swaps

Pipeline Stages

The core apply path is:

1. load and validate YAML configuration
2. acquire the runtime lock
3. clone or update the site repository and source repositories
4. discover Markdown sources while honoring .lighthouseignore
5. validate URL mapping and local references
6. materialize _automated_posts/ and copied assets
7. run the configured Jekyll build command
8. copy the built site into releases/<timestamp>/
9. atomically repoint active and current
10. write a full state snapshot
11. clean old releases and matching state files

Runtime Layout

The runtime tree under ~/.lighthouse/ is split into:

• config/ for human-maintained YAML
• cache/repos/ for checked-out repositories
• states/ for deployment snapshots
• logs/ for verbose run logs
• lock for overlap prevention

This keeps build state and logs out of the site repository itself.

Source Discovery

Each configured source repository:

• is cloned from CLONE_URL
• is updated from the configured BRANCH
• is scanned recursively from repo root for *.md
• honors .lighthouseignore with .gitignore-style inheritance

URL generation rules:

• lowercase all source paths
• remove the .md suffix
• preserve the remaining relative path
• apply the repo-level URL_PATH
• map repo-root README.md to the repo root URL

Materialization Model

For every discovered Markdown file, the pipeline:

• resolves the canonical title from front matter, heading, or filename
• reads last_modified_at from Git
• assigns a stable publish_date from the first deployment state that saw the file
• rewrites local Markdown references to generated site permalinks
• copies referenced local non-Markdown assets into assets/generated/
• writes a Jekyll source file into _automated_posts/

The generated source includes explicit front matter for permalink, author, source metadata, publish date, and last-modified time.

Deployment Model

Deployment root:

/var/www/lighthouse/
  releases/
    <timestamp>/
  active -> releases/<timestamp>
  current -> releases/<timestamp>

The freshly built site is copied into a new release directory. After basic release validation, active and current are atomically repointed to that release.

State and Retention

Every successful apply writes a full state snapshot:

~/.lighthouse/states/state-<timestamp>.json

That snapshot carries forward first-seen publication dates so older state files can be retired without losing publication history for live posts.

Retention cleanup runs only after a successful deploy. Old releases and their matching state snapshots are deleted together. Logs are retained indefinitely.