Skip to content

Latest commit

 

History

History
115 lines (97 loc) · 6.71 KB

install.md

File metadata and controls

115 lines (97 loc) · 6.71 KB

Installing lockhttp

How to install lockhttp, set it up with lea and lockhub, and the commands of its launcher. The short path is in the README.

Moved from the README, whole. lox run runs the hub and the lockhttp console, writes .lockfamily/up.json and serves the decisions in its terminal; it replaces lockhub's deprecated lox up.

Install

LockHTTP runs in Docker. On the host there is only the lockhttp launcher, a shell script that runs every command in the release's image (ghcr.io/davidgodefroid/lockhttp:X.Y.Z, amd64 and arm64). With Homebrew: brew trust davidgodefroid/tap (Homebrew asks to trust a third-party tap once), then brew install davidgodefroid/tap/lockhttp (or davidgodefroid/tap/lockfamily for the whole family, lox and cosign included). The lockhttp formula pulls in neither lox nor cosign: name them with it, brew install davidgodefroid/tap/lockhttp davidgodefroid/tap/lox cosign. lockhttp v0.12 needs lockhub's lox v0.12.1 or later (it passes --runtime-gids to the console) and cosign v2.5.0 or later (lox add and lox run verify every image with it). Without Homebrew, the Lock Family's installer puts the same launcher in ~/.local/bin (lockfamily install):

curl -fsSL https://lockfamily.dev/install.sh | sh

The installer verifies the keyless cosign signature of the release and of its image against this repository's release workflow, and writes the verified image digest into the launcher. The brew formula checks the archive's SHA-256 and writes the image digest the tap verified with cosign when it was bumped. Either way the launcher runs the image by that digest. lea's LEA_LOCKHTTP=1 uses this launcher from lea v0.16.0 on (it checks the digest against its pin or with cosign); older lea accept only a root-owned /usr/local/bin/lockhttp, which lockhttp no longer installs (scripts/install.sh is gone since v0.11.0). Linux (Docker Engine) and macOS (Docker Desktop); on Windows, WSL 2 with Docker Desktop.

Command Runs as What it does
lockhttp profile add [--non-interactive] [--json] [--profile NAME] [--production] [--trusted "a.com .corp.example"] you, on the project Adds a profile with the default policy to the project's .lockhttp/config.toml (never rewrites one already there; never takes a secret).
lockhttp init <agent> you, on the project Nothing to write: lockhttp has no agent files (lea routes the agent's HTTP through the gate).
lockhttp doctor [--fix [--yes]] [--json] [--gate ADDR] [--ca-cert FILE] you, on the project Separated setup, the project's policy and its permissions, CA, gate; --fix repairs the permissions.
lockhttp policy show|edit|path lockhttp, volume lockhttp-home Prints, edits or locates the console's copy of the policy.
lockhttp console lockhttp, container lockhttp-console The policy console (under lox run, its own service runs it). It must run in a terminal.
lockhttp gate gate, container lockhttp-gate The proxy. It needs the hub flags (--hub, --hub-key-file, --instance): lea passes them from lox run's up.json.
lockhttp version, lockhttp update [vX.Y.Z] The launcher's and the image's versions; a newer release's launcher, checked the same way, and its image.

LOCKHTTP_IMAGE runs an image of your own (docker build -t lockhttp . from a clone), LOCKHTTP_DOCKER_ARGS adds docker run arguments. There is no host install. Coming from v0.1.0's sudo lockhttp install: migrating from a host install.

The README's demo is generated by scripts/brand/demo.py: python3 scripts/brand/demo.py > site/assets/demo.svg. Its terminals show the capture in scripts/brand/demo-capture/: output of the gate and of lox run, taken in two separate test runs and joined by hand (how).

Accounts, volumes, the exact docker run of each command, and what Docker does and does not separate: docs/docker.md. Every command and flag: docs/usage.md.

Quick start with lea

LockHTTP runs in Docker and hub-attached only: lockhub's lox run runs the hub and the lockhttp console for your projects directory, and lea runs the gate beside its proxy container when LEA_LOCKHTTP=1, with the hub flags lox run writes in .lockfamily/up.json. The contract between lockhttp and lea (files, mounts, uids, network rules) is in docs/lea.md; the one between lox run and lea in lockhub's docs/lox-run.md.

LockHTTP needs lea, and lox add lockhttp sets it up (its only question is the lock's name): see lockhub's docs/lox-add.md.

# 1. Install the Lock Family (lox, lea and the launchers), or only this tool;
#    Homebrew asks to trust a third-party tap once
brew trust davidgodefroid/tap
brew install davidgodefroid/tap/lockfamily   # or, with lox and cosign: brew install davidgodefroid/tap/lockhttp davidgodefroid/tap/lox cosign
                                              # or the launcher alone: see Install

# 2. In lea's projects directory (LEA_PROJECTS_DIR: lea reads
#    .lockfamily/up.json only at its root): a lockhttp lock, the hub, its console
cd ~/projects
lox add lockhttp              # asks for the lock's name: profile add, the declaration, lox run, the console
# or by hand:
#   lockhttp profile add      # the policy: .lockhttp/config.toml, which lox run reviews and copies
#   lox add lockhttp web
#   lox run                   # runs the hub and the console, registers the gate's key
#   lox attach web            # the console's terminal: approve its first policy (detach: Ctrl-P Ctrl-Q)

# 3. Turn LockHTTP on in lea's configuration, then restart lea: its gate asks
#    the hub. LEA_LOCKHTTP=1 in the environment alone is ignored (lea's
#    configuration wins and lea warns). lea mounts the locks' sockets when its
#    container starts, and lea-proxy and its gate are shared by every lea on
#    the machine (on or off for all of them), so stop them all.
echo LEA_LOCKHTTP=1 >> ~/.config/lea/lea.conf
lea stop --all
lea

# 4. Approve the held requests on a facade of the hub
lox approve

The console runs as the lockhttp account (uid 10021) in lox run's service; lea's gate runs as gate (uid 10003) in a container of its own and shares only the console's socket volume with it. Without a trusted up.json naming a lockhttp lock, lea does not start the gate: it says to run lox run. lockhttp gate refuses to start without its hub flags ("launched by lox run only").