ImpTune/README.md

ImpTune

Build printer deploy packages (.intunewin for Intune, .zip for NinjaRMM) from Windows driver ZIPs via a web UI.

Run

Local development

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:

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.

# 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.

services:
  imptune:
    environment:
      - DATA_DIR=/data
      - COOKIE_SECURE=false   # only when serving plain HTTP

For local development the same applies:

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).

services:
  imptune:
    environment:
      - DATA_DIR=/data
      - COOKIE_SECURE=single_user