kawaandClaude Haiku 4.5
f70ba93e7a
- COOKIE_SECURE env now accepts: 'true' (secure), 'false' (memory-only), 'single_user' (no cookie) - config.parse_cookie_mode() returns (COOKIE_SECURE, SINGLE_USER) tuple for routing - single_user_owner() returns oldest Owner for test/local deployments - session cookie respects mode: Max-Age only in secure mode, dropped for memory-only - base.html renders ephemeral-session and single-user banners per mode - Tests: comprehensive coverage for all three modes with monkeypatch configs - CLAUDE.md + README docs updated Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# ImpTune
|
|
|
|
Build printer deploy packages (`.intunewin` for Intune, `.zip` for NinjaRMM) from Windows driver ZIPs via a web UI.
|
|
|
|
## Run
|
|
|
|
### Local development
|
|
|
|
```bash
|
|
docker compose up
|
|
```
|
|
|
|
`docker-compose.override.yml` is merged automatically: it mounts your working
|
|
copy into the container and runs uvicorn with `--reload`, so code edits are
|
|
picked up live. The override is gitignored (personal / per-machine).
|
|
|
|
### Run the published image
|
|
|
|
To run the image from the registry instead of building locally, skip the
|
|
override:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml pull
|
|
docker compose -f docker-compose.yml up
|
|
```
|
|
|
|
Then open http://localhost:8000
|
|
|
|
## Publishing
|
|
|
|
`scripts/publish.ps1` builds the image and pushes it to the Gitea container
|
|
registry at `git.azuze.fr/kawa/imptune`.
|
|
|
|
```powershell
|
|
# build + push :<short-git-sha> and :latest (prompts for a Gitea token)
|
|
./scripts/publish.ps1
|
|
|
|
# tag an explicit version
|
|
./scripts/publish.ps1 -Tag v1.2.0
|
|
```
|
|
|
|
Use a Gitea access token (Settings → Applications, with package read/write
|
|
scope) as the password. For non-interactive runs set `GITEA_USER` /
|
|
`GITEA_TOKEN` env vars. Run `Get-Help ./scripts/publish.ps1 -Detailed` for all
|
|
parameters (`-Registry`, `-Owner`, `-Image`, `-NoBuild`, `-SkipLogin`, …).
|
|
|
|
## Environment variables
|
|
|
|
Set these under `environment:` in `docker-compose.yml`.
|
|
|
|
| Variable | Default | Purpose |
|
|
|------------------|---------|--------------------------------------------------|
|
|
| `DATA_DIR` | `/data` | Storage root for the SQLite DB, drivers and icons. Should map to the `imptune_data` volume. |
|
|
| `PORT` | `8000` | Port the server listens on inside the container. |
|
|
| `COOKIE_SECURE` | `true` | Session mode: `true` (Secure cookie), `false` (plain-HTTP cookie, memory-only) or `single_user` (no cookie, one shared store) — see below. |
|
|
|
|
### `COOKIE_SECURE` and HTTPS
|
|
|
|
Printers, print defaults and clients belong to a session identified by an opaque
|
|
key in a cookie (there are no accounts). That cookie is `Secure` by default, so
|
|
it only travels over HTTPS.
|
|
|
|
**Behind a TLS-terminating proxy** (nginx, Traefik, Caddy — the normal setup):
|
|
leave the default. The session cookie lasts ten years, so a browser keeps its
|
|
printers indefinitely.
|
|
|
|
**Reached directly over plain HTTP** (`http://host:8000`): set
|
|
`COOKIE_SECURE=false`, otherwise the browser refuses the cookie and every
|
|
request starts a brand-new empty session — no printer you save is ever visible
|
|
again.
|
|
|
|
In that mode the app is fully usable and keeps remembering everything, but the
|
|
cookie becomes **memory-only**: the session ends when the browser closes, and
|
|
every page shows a warning saying so. This is deliberate — over plain HTTP the
|
|
key is readable on the wire, so it is not written to disk for ten years. Use
|
|
**Download my backup key** to save the key to a file; `/session/restore` takes
|
|
it back on the next browser start, or on another machine.
|
|
|
|
```yaml
|
|
services:
|
|
imptune:
|
|
environment:
|
|
- DATA_DIR=/data
|
|
- COOKIE_SECURE=false # only when serving plain HTTP
|
|
```
|
|
|
|
For local development the same applies:
|
|
|
|
```bash
|
|
export DATA_DIR=/tmp/imptune_data
|
|
export COOKIE_SECURE=false
|
|
uvicorn imptune.main:app --reload --port 8000
|
|
```
|
|
|
|
### `COOKIE_SECURE=single_user` — no sessions at all
|
|
|
|
For a test box or a local deployment used by one person, sessions are pure
|
|
friction. `COOKIE_SECURE=single_user` (also accepted: `single-user`, `single`)
|
|
drops them:
|
|
|
|
- No cookie is read or set. Every request — every browser, every device, curl —
|
|
resolves to **one shared owner**, so all printers, print defaults and clients
|
|
are simply "the server's".
|
|
- The onboarding modal, the memory-only warning, the "This session" sidebar menu
|
|
and both `/session/*` key routes disappear (the routes return `404`). There is
|
|
no backup key to lose, and none to hand out.
|
|
- Every page shows a banner stating that whoever reaches the app sees the same
|
|
data.
|
|
|
|
**There is no isolation left in this mode**, so put it only where reaching the
|
|
app is already the permission — localhost, or a network you trust. Switching an
|
|
existing deployment over adopts the oldest existing owner, so printers saved
|
|
under a cookie stay visible; switching back re-enables cookie scoping and hands
|
|
new browsers a fresh empty session (that same data is then reachable only with
|
|
its key, which single-user mode never printed — download a backup key *before*
|
|
switching if you may switch back).
|
|
|
|
```yaml
|
|
services:
|
|
imptune:
|
|
environment:
|
|
- DATA_DIR=/data
|
|
- COOKIE_SECURE=single_user
|
|
```
|