Lychee Wizard

An interactive CLI that generates a ready-to-run docker-compose.yaml and .env for Lychee, the self-hosted photo management app.

By default it downloads the latest .env.example, docker-compose.yaml, and config/*.php straight from LycheeOrg/Lychee@master, so the generated setup always matches what upstream actually ships and supports — instead of a config template that goes stale. A --local flag switches to a build-time-embedded snapshot for fully offline use.

Usage

go build -o lychee-wizard .
./lychee-wizard            # fetches the latest templates from GitHub
./lychee-wizard --local    # uses the bundled offline snapshot instead

Answer the prompts, then:

docker compose up -d

Files are written into the current directory:

• docker-compose.yaml, .env
• lychee/{uploads,logs,tmp}/ — the volumes docker-compose.yaml mounts
• secrets/{app_key,db_password,db_master_password} — only if you opt into Docker secrets (recommended default); keep this directory out of version control

If docker-compose.yaml or .env already exist, you'll be asked to confirm before they're overwritten.

Flags

• --local — use the embedded snapshot instead of fetching from GitHub.
• --accessible — plain sequential prompts instead of a raw-mode TUI (screen readers, non-ANSI terminals, or piping in answers from a script).

What the wizard asks

• General: app name, URL, port, force-HTTPS, timezone.
• Database: name, username, and either generated or manually entered passwords.
• Secrets handling: whether to store APP_KEY / DB_PASSWORD / DB_ROOT_PASSWORD as Docker secrets files instead of plaintext in .env.
• Optional services: phpMyAdmin, AI facial recognition (and its API key).
• System: PUID / PGID for the container's file ownership.

Every other setting from upstream's .env.example is carried through unmodified. Anything the wizard doesn't ask about but Lychee's own config/*.php files recognize (found by scanning them for env() calls when not running --local) is appended to .env as a commented-out reference line, so nothing configurable is silently missing.

Development

make build        # go build
make test         # go test ./...
make vet          # go vet ./...
make fmt-check     # gofmt -l .
make genembed      # refresh internal/embedded/ from the live Lychee repo
make docker-build  # build the container image
make docker-run    # run it against the current directory

internal/embedded/ (the --local snapshot) is regenerated by tools/genembed, which re-downloads the Lychee repo and re-scans config/*.php. It's a maintainer-only step (make genembed), never run by end users.