Lighthouse mark for Peisong's Lighthouse Peisong's Lighthouse Somewhere to find inspiration.

LIGHTHOUSE CLI

lighthouse Quickstart

This is the shortest path from a fresh checkout to a validated local run of the Lighthouse deployment pipeline.

Table of Contents

Install

From the repository root:

python -m pip install -e .

That installs the lighthouse command into the active Python environment.

Runtime Layout

By default, the CLI runs under:

~/.lighthouse/

Important subdirectories:

  • config/ command-specific config files such as lighthouse.yml and harbor.yml
  • cache/repos/ cloned repositories
  • states/ per-run state snapshots
  • logs/ append-only run logs

You can override the runtime root with --run-dir.

Configure

Start from the example files:

Copy them into:

~/.lighthouse/config/

The config directory now supports separate command-specific files:

  • lighthouse.yml or lighthouse.yaml for LIGHTHOUSE:
  • harbor.yml or harbor.yaml for HARBOR:

GLOBAL is reserved for future shared settings, but the current command loaders do not scan global.yml.

If you want weighted-random post ratings, fill in the optional LIGHTHOUSE.RATINGS block with your OpenRouter credentials, model, retry budget, and prompt.

If you want deploys to purge Cloudflare automatically, fill in the optional LIGHTHOUSE.CLOUDFLARE block with the target ZONE_ID and API token.

If you want local-build and remote-deploy separation for the static site, fill in the optional LIGHTHOUSE.REMOTE block with either the local or remote role. The local role uses SSH and SCP to upload and trigger deployment on the remote host, bootstraps the remote lighthouse-cli checkout, and syncs the remote runtime config before invoking remote deployment.

If portable content metadata differs between local and remote, the CLI will stop and ask you to type local or remote before it continues.

RSS feed policy also lives in config. The LIGHTHOUSE.RSS block controls whether feeds are emitted and the minimum combined post rating required for an item to appear. Keep UPDATED_DIFF_RATING_THRESHOLD at <= 0 to use the mechanical updated-post path without an additional LLM pass.

If your site repo contains resume.tex, make sure make4ht and latexmk are installed so the CLI can generate the embedded HTML resume fragment and downloadable PDF artifact.

If you want to use Harbor, fill in HARBOR: with:

  • exactly one Harbor source mode:
    • SOURCE_DIR
    • or CLONE_URL + BRANCH
  • Harbor runtime and deploy roots
  • Harbor DATABASE_URL
  • Harbor bind host/port
  • embedded OIDC config for local e2e
  • docked apps and their config-file paths

For production-facing Harbor testing, point the schedule app config at a normal PostgreSQL database on your local cluster. Harbor apps do not read apps/.env; Harbor passes each app a config file path and the app loads database settings from that file. The todo app remains useful as an e2e-only validation app.

Validate

Validate only the merged configuration:

lighthouse validate --config-only

Run the full pre-build validation:

lighthouse validate

Check whether the current environment supports the configured feature set:

lighthouse check-deps

Force the run to ignore saved rating metadata and treat the next build as fresh:

lighthouse validate --fresh

Clear the cached checkouts if you want the next run to re-clone every configured repository:

lighthouse clean

Narrow that to one target if needed:

lighthouse clean --target lighthouse
lighthouse clean --target harbor

Build or Deploy

Build without deployment:

lighthouse build

Force a full rerating pass during the build:

lighthouse build --fresh

Deploy a new release:

lighthouse apply

Serve a local build directly:

lighthouse local 4000

local ignores DEPLOY_ROOT; it only builds and serves the site from the local cache.

Build a remote deployment artifact locally:

lighthouse remote build

Upload the most recent artifact to the configured remote cache:

lighthouse remote send

Trigger remote deployment from the already-uploaded artifact:

lighthouse remote apply

Build Harbor and its docked apps:

lighthouse build --target harbor

Validate Harbor config only:

lighthouse validate --target harbor --config-only

Deploy Harbor and restart or install the Harbor user service when the Harbor target changed:

lighthouse apply --target harbor

Clone-backed Harbor app updates participate in the Harbor apply fingerprint, so app-only repo changes also trigger Harbor redeploy.

Initialize Harbor’s Postgres-backed mutable state:

lighthouse harbor migrate-db

Run Harbor locally on its configured localhost port:

lighthouse harbor local

Override the Harbor localhost port for one run:

lighthouse harbor local --port 5090

Inspect Harbor runtime status:

lighthouse harbor status
lighthouse harbor apps
lighthouse harbor ps

Manage Harbor users and direct permissions:

lighthouse harbor add-user Alice_User --name "Alice Example" --email alice@example.test
lighthouse harbor set-password alice_user
lighthouse harbor list-permissions
lighthouse harbor list-all-permissions
lighthouse harbor add-permissions alice_user todo.write
lighthouse harbor delete-permissions alice_user todo.write
lighthouse harbor delete-user alice_user

HARBOR.OIDC.EMBEDDED_USERS are bootstrap-only seed users. After lighthouse harbor migrate-db initializes the Harbor database, Harbor reads mutable users, permissions, preferences, and maintenance state from Postgres instead of YAML. Once the Harbor database is initialized, it is safe to remove EMBEDDED_USERS from Harbor config.

Harbor normalizes canonical usernames to lowercase and only allows a-z, 0-9, _, and -. The raw username you provide is preserved as the display name unless you set DISPLAY_USERNAME explicitly in Harbor config.

More Reading