odykyi · Nov 1, 2026 · Nov 1, 2026 · Nov 1, 2026 · Nov 1, 2026 · Nov 1, 2026
@@ -0,0 +1,21 @@
+# Open Questions – Feature 104
+
+Open questions for [Feature 104](spec.md). Log every high- and medium-impact question here (table row + Question Details entry) before asking the user; see [open-questions-format.md](../../spec-guidelines/open-questions-format.md). Once answered, fold the outcome into [spec.md](spec.md) (and an ADR when architecturally significant), then mark the entry resolved.
+
+## Active Questions
+
+| Question ID | Feature | Priority | Summary | Status | Opened | Updated |
+|-------------|---------|----------|---------|--------|--------|---------|
+| Q-104-01 | 104 | High | Does the project want an optional Flisk start path at all? | Open | 2026-11-01 | 2026-11-01 |
+| Q-104-02 | 104 | Medium | Where should the generated Compose file live? | Open | 2026-11-01 | 2026-11-01 |
+
+## Question Details
+
+### Q-104-01 – Optional Flisk start path
+- **Option A (recommended):** Accept it as an option; `docker-compose.yaml` stays the documented main path (as biolend83/tubehaus did in #40). Pros: no change for existing users; Flisk users get `flisk up`. Cons: two descriptions of one stack, kept in step by CI.
+- **Option B:** Keep it outside the repository (a gist or the Flisk docs). Pros: nothing to maintain here. Cons: drifts silently.
+- **Option C:** Decline.
+
+### Q-104-02 – Location of the generated Compose file
+- **Option A (recommended):** `.autogenerated/docker-compose.yml`, committed, with a `.gitignore` exception. Pros: clearly generated. Cons: needs `--env-file .env` when run from the root.
+- **Option B:** Do not commit it; generate on demand. Pros: one less file. Cons: no plain-Compose path without Flisk.
@@ -0,0 +1,55 @@
+# Feature Plan 104 – Flisk Option
+
+_Linked specification:_ [spec.md](spec.md)  
+_Status:_ Draft  
+_Last updated:_ 2026-11-01
+
+> Guardrail: Keep this plan traceable back to the governing spec. Reference FR/NFR/Scenario IDs from `spec.md` where relevant, log any new high- or medium-impact questions in the feature's [open-questions.md](open-questions.md), and assume clarifications are resolved only when the spec’s normative sections (requirements/NFR/behaviour/telemetry) and, where applicable, ADRs under `docs/specs/6-decisions/` have been updated.
+
+## Vision & Success Criteria
+Users who already use Flisk can start Lychee with `flisk up lychee`, and anyone can run the generated Compose file, with the same data as a `docker-compose.yaml` install. Success: S-104-01 … 05 pass.
+
+## Scope Alignment
+- **In scope:** FX-104-01 … 03, `docs/FLISK.md`, one README line, one `.gitignore` exception, one CI workflow.
+- **Out of scope:** N-104-01 … 03.
+
+## Dependencies & Interfaces
+Flisk CLI 1.4.31 or later (1.4.27 has the fields; 1.4.30 needs none of the FR-104-06 … 08 workarounds; 1.4.31 also does not start Flisk's own PostgreSQL, which Lychee does not use), flisk-import 0.16.0, @flisk-sh/flisk-export 0.9.0 (see the spec's *Pinned versions*).
+
+## Assumptions & Risks
+- **Assumptions:** maintainers accept an optional second start path (Q-104-01).
+- **Risks / Mitigations:** drift between `docker-compose.yaml` and `service.json` → CI check (FR-104-04) and `flisk import .` to re-read the Compose file.
+
+## Implementation Drift Gate
+Re-run the per-service `docker compose config --no-interpolate` comparison and S-104-03 after implementation; record results in the PR.
+
+## Increment Map
+1. **I1 – Service files and generated Compose**
+   - _Steps:_ `FLISK_IMPORT_PACKAGE=flisk-import@0.16.0 flisk import . --yes`; `npx @flisk-sh/flisk-export@0.9.0 compose . --force`; `.gitignore` exception.
+   - _Commands:_ `flisk config verify`; `echo "APP_KEY=base64:$(openssl rand -base64 32)" > .env`; `docker compose --env-file .env -f .autogenerated/docker-compose.yml config` (bind sources must resolve to `<repo>/lychee/*`).
+   - _Exit:_ FR-104-01 … 03 met; comparison shows only documented differences.
+2. **I2 – Docs and CI**
+   - _Steps:_ `docs/FLISK.md`, README line, `.github/workflows/flisk.yml`.
+   - _Steps (CI):_ re-import from `docker-compose.yaml` + export in a scratch copy, `git diff --exit-code -- services .flisk .autogenerated`; normalised per-service `docker compose config` comparison of both files (FR-104-04).
+   - _Exit:_ FR-104-04/05; S-104-04 fails as expected both on an edited `service.json` and on an edited `docker-compose.yaml`.
+3. **I3 – Evidence**
+   - _Steps:_ S-104-01 … 05 on a fresh machine; screenshots and logs in the PR.
+
+## Scenario Tracking
+
+| Scenario ID | Increment / Task reference | Notes |
+|-------------|---------------------------|-------|
+| S-104-01 | I3 / T-104-05 | `flisk up lychee` |
+| S-104-02 | I1 / T-104-02 | verified on scratch machine |
+| S-104-03 | I1 / T-104-02 | verified on scratch machine |
+| S-104-04 | I2 / T-104-04 | CI |
+| S-104-05 | I3 / T-104-05 | profiles |
+
+## Analysis Gate
+Pending maintainer review of this specification PR.
+
+## Exit Criteria
+- All S-104 scenarios recorded; no existing file changed beyond NFR-104-01.
+
+## Follow-ups / Backlog
+- Optional: `docker-compose.minimal.yaml` as a second Flisk stack, if wanted.
@@ -0,0 +1,96 @@
+# Feature 104 – Flisk Option
+
+| Field | Value |
+|-------|-------|
+| Status | Draft |
+| Last updated | 2026-11-01 |
+| Owners | odykyi |
+| Linked plan | [plan.md](plan.md) |
+| Linked tasks | [tasks.md](tasks.md) |
+| Roadmap entry | #104 |
+
+> Guardrail: This specification is the single normative source of truth for the feature. Track high- and medium-impact questions in the feature's [open-questions.md](open-questions.md), encode resolved answers directly in the Requirements/NFR/Behaviour/UI/Telemetry sections below (no per-feature `## Clarifications` sections), and use ADRs under `docs/specs/6-decisions/` for architecturally significant clarifications (referencing their IDs from the relevant spec sections).
+
+## Overview
+Self-hosters start Lychee with `docker-compose.yaml`. This feature adds an **optional** second way to start the same stack with [Flisk](https://flisk.sh), a local dev/self-host launcher: one `service.json` per Compose service under `services/lychee/`, plus a Compose file generated from them in `.autogenerated/docker-compose.yml`. No PHP, frontend, API, artisan or image change; `docker-compose.yaml` stays the documented main path and is not edited. Disclosure: the author works on Flisk.
+
+## Goals
+- G-104-01: `flisk up lychee` starts the same services as `docker compose -f docker-compose.yaml up` (lychee_api, lychee_worker, lychee_db, lychee_facial_recognition; phpmyadmin, nsfw and geo-decoding behind their profiles).
+- G-104-02: An existing Compose install switches to the Flisk setup **without copying data**: same Docker volume names (`lychee_prod_mysql`, `lychee_ai_vision_embeddings`, `lychee_nsfw_queue`) and the same `./lychee/*` bind mounts: the generated file writes them as `../lychee/*` (relative to `.autogenerated/`, where Compose resolves them), and `docker compose config` resolves them to `<repo>/lychee/*`.
+- G-104-03: Other services keep reaching each other by the Compose names (`lychee_api`, `lychee_db`), which are written as network aliases.
+- G-104-04: `.autogenerated/docker-compose.yml` runs with plain Docker Compose and no Flisk (`docker compose --env-file .env -f .autogenerated/docker-compose.yml up -d`).
+- G-104-05: Documentation in `docs/FLISK.md`, one pointer line in README, and a CI check that the generated file matches the `service.json` files.
+
+## Non-Goals
+- N-104-01: Replacing or editing `docker-compose.yaml`, `docker-compose.minimal.yaml`, the Dockerfiles or any image.
+- N-104-02: Any change to application code, tests, API or UI.
+- N-104-03: Production deployment or Kubernetes; Flisk does not deploy.
+- N-104-04: Fixing the health checks of the optional nsfw and geo-decoding images, or the installer banner (all exist with `docker-compose.yaml`). The facial-recognition check is changed on the Flisk side only (FR-104-10), because `flisk up --wait` fails on it.
+
+## Functional Requirements
+
+| ID | Requirement | Success path | Validation path | Failure path | Telemetry & traces | Source |
+|----|-------------|--------------|-----------------|--------------|--------------------|--------|
+| FR-104-01 | One `service.json` per Compose service under `services/lychee/<name>/`, generated by `flisk import`. | Same image, env (Compose expressions such as `${DB_PASSWORD:-password}` kept as written), healthchecks incl. `start_period`, `depends_on` conditions, `tmpfs`, cap_add/cap_drop, security_opt, deploy limits, profiles, volumes. | `flisk config verify`; a per-service diff of `docker compose config --no-interpolate` for both files shows only the differences listed in FR-104-04. | Import notes list anything not carried over. | None (no app telemetry). | G-104-01 |
+| FR-104-02 | Volumes keep their Docker names; bind mounts keep their host paths. | Generated file declares `mysql: name: lychee_prod_mysql` etc., and binds as `../lychee/*`. | Switch test: data written by the original stack is read by the generated one; `docker compose -f .autogenerated/docker-compose.yml config` shows bind sources `<repo>/lychee/uploads`, `/logs`, `/tmp`. | — | — | G-104-02 |
+| FR-104-03 | Renamed services keep their Compose hostnames. | `lychee-api` answers as `lychee_api` (network alias). | `getent hosts lychee_api` inside `lychee_facial_recognition`. | — | — | G-104-03 |
+| FR-104-04 | Generated files are committed and CI keeps them in step with `docker-compose.yaml`. | `.autogenerated/docker-compose.yml` (excepted from the `docker-compose.yml` ignore rule). | CI job, in a scratch copy of the checkout: (1) re-run the pinned import from `docker-compose.yaml` and the pinned export, then `git diff --exit-code -- services .flisk .autogenerated` (catches a Compose change nobody re-imported); (2) `docker compose config --format json --no-interpolate` on both `docker-compose.yaml` and the generated file (after `cp .env.example .env`), normalised per service (kebab names, long-form ports, `CMD-SHELL` vs `CMD sh -c`) and compared field by field: image, environment, ports, volumes, tmpfs, cap_add/cap_drop, security_opt, healthcheck, depends_on, profiles, deploy limits. | CI fails on any difference not listed as equivalent in this spec. | — | G-104-04 |
+| FR-104-05 | Documentation. | `docs/FLISK.md`: start with Flisk, start without Flisk, the volume/alias mapping, what differs. README: one line under *Docker*. | Links resolve. | — | — | G-104-05 |
+
+## Known `flisk up` requirements (found on Flisk 1.4.28, re-checked on 1.4.29 and 1.4.30)
+Running the generated stack under `flisk up` (not only as plain Compose) needed three things that the plain Compose path does not on Flisk 1.4.28 (flisk-sh/flisk#1519, #2991, #2992). Flisk 1.4.29 (flisk-sh/flisk#3001) fixes two of them and Flisk 1.4.30 (flisk-sh/flisk#3010) the third. Re-checked from a fresh clone with `flisk-import` 0.17.1 and `@flisk-sh/flisk-export` 0.9.0:
+
+| ID | Requirement | Status on Flisk 1.4.29, and older versions |
+|----|-------------|--------------------------------------------|
+| FR-104-06 | `.flisk/project.json` `project.name` is lowercase (`lychee`). | **Fixed in Flisk 1.4.29, no workaround needed**: Flisk lowercases the name itself and `flisk-import` 0.17.0 and later writes it lowercase. Older Flisk (1.4.28 and earlier) refuses an uppercase name (folder `Lychee`): keep it lowercase by hand. |
+| FR-104-07 | `lychee-api` and `lychee-worker` set `"DATABASE_URL": ""` in `env`. | **Fixed in Flisk 1.4.30, no workaround needed** (flisk-sh/flisk#3010; checked from a fresh clone: no `DATABASE_URL` or `TILT_DATABASE_URL` in the api container, API and worker healthy). Older versions: set `DATABASE_URL` to an empty string on both. On 1.4.29 it is still required: discovery fills in a `databaseName` and 1.4.29 treats it as asking for the shared Postgres. Lychee reads `DATABASE_URL` before `DB_*`. |
+| FR-104-08 | `lychee-facial-recognition` sets `container.memory: "4G"`. | **Fixed in Flisk 1.4.29, no workaround needed**: a service without `container.memory` gets no limit (memory limit 0, not OOM-killed; same for `lychee-geo-decoding` and `lychee-nsfw-classification`). Older Flisk (1.4.28 and earlier) applies a 512M default and OOM-kills the image: set `container.memory: "4G"` there, and `"2G"` on `lychee-geo-decoding` when its profile is used. |
+| FR-104-10 | `lychee-facial-recognition` `healthCheck.command` uses the image's own Python: `["python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health', timeout=5)"]`. | **Needed on every Flisk version**: the image has no `curl`, so the check copied from `docker-compose.yaml` keeps it unhealthy and `flisk up lychee --wait` exits 1. Checked on Linux amd64 (GitHub `ubuntu-latest`, Flisk 1.4.30): the Python call returns 200 inside the container. `docker-compose.yaml` is not changed. |
+| FR-104-09 | `.gitignore` covers what `flisk up` writes: `/.tiltignore`, `/shared-platform-engineering/`, `/services/platform/`, `/services/**/.autogenerated/`, `/.flisk/.flisk-out/`. | Unchanged: generated files must not be committed. |
+
+Known behaviour that is **not** caused by the Flisk setup: the `lychee_facial_recognition` image has no `curl`, but its health check calls it, so it reports unhealthy under `docker-compose.yaml` too while `/health` answers 200 (the Flisk setup uses FR-104-10 instead; `docker-compose.yaml` is not changed). The `lychee_nsfw_classification` image (no `curl`) and the `lychee_geo_decoding` image (no `wget`, no shell) behave the same way under `docker-compose.yaml`. The installer page shows an empty "Please fix the errors" banner in both setups.
+
+## Non-Functional Requirements
+
+| ID | Requirement | Driver | Measurement | Dependencies | Source |
+|----|-------------|--------|-------------|--------------|--------|
+| NFR-104-01 | No change to the existing Compose path. | Most installs use it. | `git diff` touches no existing file except README (one line) and `.gitignore` (one exception line). | — | G-104-01 |
+| NFR-104-02 | Same reachability as Compose. | Self-hosters rely on `${APP_PORT:-8000}:8000`. | Port published on the same host address; checked with `docker ps` and from the LAN. | See *Pinned versions* | G-104-01 |
+| NFR-104-03 | No secrets committed. | Security. | `.env` stays gitignored; only `${VAR}` expressions in `service.json`. | — | — |
+
+## Branch & Scenario Matrix
+
+| Scenario ID | Description / Expected outcome |
+|-------------|--------------------------------|
+| S-104-01 | Fresh clone, `echo "APP_KEY=base64:$(openssl rand -base64 32)" > .env` (`.env.example` is the bare-metal file: its `DB_CONNECTION=sqlite` makes the API look for a SQLite file and restart, under `docker-compose.yaml` too), then `flisk up lychee`: API healthy, `/` redirects to `/install/admin`. |
+| S-104-02 | Fresh clone, `echo "APP_KEY=base64:$(openssl rand -base64 32)" > .env`, then `docker compose --env-file .env -f .autogenerated/docker-compose.yml up -d`: same as S-104-01. |
+| S-104-03 | Existing install from `docker-compose.yaml`, `down` (volumes kept), then S-104-02: previous data is there. |
+| S-104-04 | `service.json` edited without regenerating, or `docker-compose.yaml` changed without re-importing: CI fails. |
+| S-104-05 | `--profile nsfw` / `geo-decoding` / `phpmyadmin`: optional services start only when asked. |
+
+## Test Strategy
+- **Models / Actions, REST API, Artisan, Frontend:** not affected (N-104-02).
+- **Docs/Contracts:** CI job from FR-104-04; manual switch test S-104-03 recorded in the PR with screenshots and logs.
+
+Already verified on a scratch machine (macOS, Docker 29.5.2, flisk-import 0.14.0 / flisk-export 0.7.0; re-checked with 0.15.0 / 0.8.0): S-104-02 and S-104-03 pass (API healthy in 12 s on the original install's volumes, a marker row written by the original stack is read back, `lychee_api` resolves), and the installer page is identical to the one served by `docker-compose.yaml`.
+
+## Pinned versions
+The fields this relies on (`container.networkAliases`, `healthCheck.startPeriod`, `volumes[].name`, `profiles`, `envFile`, `container.tmpfs`) are in Flisk CLI **1.4.27** (released 2026-11-01). The files are produced and checked with fixed versions:
+
+| Step | Command |
+|------|---------|
+| Import | `FLISK_IMPORT_PACKAGE=flisk-import@0.16.0 flisk import . --yes` |
+| Export | `npx @flisk-sh/flisk-export@0.9.0 compose . --force` |
+| CI drift check | re-import + export in a scratch copy, then `git diff --exit-code`; plus the normalised `docker compose config` comparison (FR-104-04) |
+| Start | `flisk up lychee` (Flisk ≥ 1.4.31, checked on Linux amd64 with `--wait`; 1.4.27 … 1.4.29 need the FR-104-06 … 08 workarounds) |
+
+`flisk export compose` is the same exporter run through the Flisk CLI; the spec uses the pinned `npx` form everywhere so CI does not depend on the installed CLI.
+
+## Interface & Contract Catalogue
+
+### Fixtures & Sample Data
+| ID | Path | Purpose |
+|----|------|---------|
+| FX-104-01 | `services/lychee/*/service.json` | Flisk service definitions (generated by `flisk import`). |
+| FX-104-02 | `.autogenerated/docker-compose.yml` | Compose generated from FX-104-01; do not edit. |
+| FX-104-03 | `.flisk/project.json` | Flisk project file. |
@@ -0,0 +1,22 @@
+# Feature 104 Tasks – Flisk Option
+
+_Status: Draft_  
+_Last updated: 2026-11-01_
+
+> Keep this checklist aligned with the feature plan increments. Stage tests before implementation, record verification commands beside each task, and prefer bite-sized entries (≤90 minutes).
+> **Mark tasks `[x]` immediately** after each one passes verification—do not batch completions. Update the roadmap status when all tasks are done.
+
+## Checklist
+- [ ] T-104-01 – Generate `services/lychee/*/service.json` and `.flisk/project.json` with `FLISK_IMPORT_PACKAGE=flisk-import@0.16.0 flisk import . --yes` (S-104-01).  
+  _Verification commands:_ `flisk config verify` (Flisk ≥ 1.4.27)
+- [ ] T-104-02 – Generate and commit `.autogenerated/docker-compose.yml`; add the `.gitignore` exception (S-104-02, S-104-03).  
+  _Verification commands:_ `npx @flisk-sh/flisk-export@0.9.0 compose . --force`; `echo "APP_KEY=base64:$(openssl rand -base64 32)" > .env`; `docker compose --env-file .env -f .autogenerated/docker-compose.yml config` with bind sources resolving to `<repo>/lychee/*`; per-service comparison against `docker-compose.yaml`
+- [ ] T-104-03 – Write `docs/FLISK.md` and the README pointer line.  
+- [ ] T-104-04 – Add `.github/workflows/flisk.yml`: re-import from `docker-compose.yaml` and export with the pinned versions in a scratch copy, then `git diff --exit-code -- services .flisk .autogenerated`; and the normalised per-service `docker compose config` comparison of `docker-compose.yaml` vs the generated file (S-104-04).  
+  _Verification:_ the job fails on a test branch that edits `docker-compose.yaml` only, and on one that edits a `service.json` only.
+- [ ] T-104-06 – Apply FR-104-09 (`.gitignore`). FR-104-06, 07 and 08 need no workaround on Flisk 1.4.30 (keep them only for older versions). Re-run `flisk up lychee` from a fresh clone on 1.4.30 (S-104-01).  
+  _Verification commands:_ `flisk up lychee`; `docker inspect` memory limit; API healthy; `docker exec <api> env | grep -i DATABASE_URL` is empty.
+- [ ] T-104-05 – Record S-104-01 … 05 with screenshots and logs in the implementation PR.
+
+## Notes / TODOs
+None.