Locks · lockhttp

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, scripts/install.sh installs 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). Otherwise, download the script from the release you install, read it, then run it:

V=vX.Y.Z
curl -fsSLO "https://raw.githubusercontent.com/DavidGodefroid/lockhttp/$V/scripts/install.sh"
less install.sh
LOCKHTTP_VERSION=$V sh install.sh

It verifies the keyless cosign signature of checksums.txt against this repository's release workflow, checks the archive, verifies the image's cosign signature and writes its digest into the launcher, which runs the image by that digest. The launcher lands in /usr/local/bin, root-owned (LOCKHTTP_INSTALL_DIR to change it). cosign is required unless LOCKHTTP_SKIP_COSIGN=1, which verifies nothing and runs the image by its tag. 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.

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: brew install davidgodefroid/tap/lockhttp
                                              # 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").