lighthouse Configuration

This document describes the YAML configuration schema consumed by the lighthouse CLI.

Table of Contents

• Config Loading
• Top-Level Keys
• EMAIL
• SOURCES
• Validation Rules
• Command Notes

Config Loading

The CLI loads configuration from either:

• a single YAML file
• a directory containing *.yml and *.yaml files merged in lexical order

Default config directory:

~/.lighthouse/config/

Use --config to point to a different file or directory.

Top-Level Keys

Required unless marked optional:

• LIGHTHOUSE_CLONE_URL Clone URL for the site repository itself.
• LIGHTHOUSE_DIRECTORY Optional local cache directory name for the site repo. Default: lighthouse
• LIGHTHOUSE_BRANCH Optional branch for the site repo.
• BUILD_COMMAND Optional site build command. Default: bundle exec jekyll build
• BUILD_OUTPUT_DIR Optional relative build output directory inside the site repo. Default: _site
• DEPLOY_ROOT Optional deployment root. Default: /var/www/lighthouse
• RETAIN_DEPLOYMENTS Optional number of retained releases and state snapshots. Must be >= 1.
• EMAIL Optional SMTP configuration block.
• SOURCES List of source repositories to materialize.

EMAIL

Supported keys:

• ENABLED
• FROM
• USER
• SMTP_ADDR
• SMTP_PORT
• PASSWD
• DESTINATIONS
• STARTTLS
• IMPLICIT_TLS

If EMAIL.ENABLED is true, the SMTP fields above must be fully specified and DESTINATIONS must be non-empty.

Run-log delivery is controlled per invocation with --email-log. SMTP configuration alone does not automatically send mail on every run.

SOURCES

Each source entry supports:

• NAME
• CLONE_URL
• BRANCH
• URL_PATH
• POST_TAG
• RECENT_POSTS

URL_PATH is optional. If omitted, the default is:

/blogs/projects/<normalized-name>/

Special cases can override this explicitly, for example:

• /blogs/
• /maestro/

POST_TAG is optional. It controls the badge shown on cards for materialized posts from that source. If omitted, the CLI derives the badge from NAME by replacing - and _ with spaces and uppercasing the result.

Examples:

POST_TAG: "BLOGS"

POST_TAG: "LANGUAGE DESIGN"

RECENT_POSTS is an optional list of glob patterns evaluated relative to the source repo root. Matching Markdown files are marked for the homepage recent-posts section.

Examples:

RECENT_POSTS:
  - "**/*.md"

RECENT_POSTS:
  - "thoughts/**/*.md"
  - "announcements/*.md"

If RECENT_POSTS is omitted or empty, that source repo does not contribute blog entries to the homepage recent-posts strip.

Validation Rules

Validation is intentionally strict. The CLI will fail if it sees:

• unknown config keys
• wrong value types
• empty required strings
• RETAIN_DEPLOYMENTS < 1
• invalid URL_PATH formatting
• URL or generated-path conflicts
• missing local Markdown references
• references to unmanaged Markdown targets
• missing referenced local assets
• existing runtime lock files for non-config-only operations

Error messages are designed to say:

• what key or path failed
• what type or shape was expected
• what value was actually received

Command Notes

• validate --config-only validates merged config only
• validate validates config and the pre-build deployment inputs
• build validates, syncs, materializes, and builds without deployment
• apply runs the full build and deployment path
• clean acquires the runtime lock, removes cache/repos with rm -rf, and recreates the empty cache directory
• local PORT builds and serves locally without deploying to /var/www/lighthouse