Web interface (M5) #238

The web interface for PaperPi v2 (milestone M5). Design: docs/decisions/web-interface.md, config-format.md, live-config-reload.md.

Decided with txoof (2026-10-07)

• The web server runs inside paperpi run in its own thread. Preview drawings run in a separate process with a time limit, like normal screen updates.
• The password is stored as a scrypt hash (built into Python) in the config file.
• New packages: fastapi, uvicorn (plain), jinja2, python-multipart.
• Log-in can be switched off with a setting in the config file. Then anyone on the home network can use the web interface without a password.
• Forgotten password: clear steps in the docs and on the log-in page, and a command:
  1. Run paperpi reset-password on the Pi (or in the Docker container). It removes the saved password (deleting the line by hand does the same).
  2. Restart or reload PaperPi.
  3. Open the web interface; the first visitor sets a new password.

Parts (one PR each, about 300–600 lines)

• 1. Web server and log-in (split in two, 2026-10-07):
  • 1a. [web] settings, password hash storage, paperpi reset-password: Web settings and password reset (M5 part 1a) #239
  • 1b. Server inside paperpi run, first visitor sets the password, cookie for 1 year, Log out, login = false, base page, htmx shipped: Web server and log-in pages (M5 part 1b) #240 (stacked on Web settings and password reset (M5 part 1a) #239)
• 2. Plugins (split in two, agreed with txoof 2026-10-07):
  • 2a. Required plugin settings (paperpi.plugin.setting(required=True), the standard place for a setting's options; met.no plugins need a real email): Required plugin settings (M5 part 2a) #241
  • 2b. Active Plugins page (only the plugins you added: on/off, move up/down buttons, remove with "Are you sure?"; "Needs settings" and Switch on greyed out) and Plugin Library page (every plugin with its description; add one with a name). Saving keeps comments, keeps unapplied hand edits and applies at once. Split in two (agreed with txoof 2026-10-07):
    • 2b-1. Editing plugin blocks in the config file as text: Editing plugin blocks in the config file (M5 part 2b-1) #244
    • 2b-2. The two pages: Active Plugins and Plugin Library pages (M5 part 2b-2) #245
• 3a. Plugin settings form built from each plugin's settings description (opened from Active Plugins), errors next to fields. Split in three (agreed with txoof 2026-10-08), stacked:
  • 3a-0. Fixed plugin id + friendly name (renaming without losing the storage folder): Plugin id and friendly name (M5 part 3a-0) #251 (merged)
  • 3a-1. Writing settings into a plugin block; form fields from the settings description and checked values back, with an error per field; pytest-xdist: Plugin settings form and settings page (M5 part 3a-1 + 3a-2) #256 (together with 3a-2)
  • 3a-2. The settings page (layout: own settings, then display time / refresh / layout / level, the rest folded under "More settings"; folded "Technical information" with the id), the place where setting helpers plug in, opened right after adding from the Library: Plugin settings form and settings page (M5 part 3a-1 + 3a-2) #256
• 3b. Preview button (separate process, sample data when the source can't be reached), and example pictures in the Plugin Library. Split in two (2026-10-09), each based on main:
  • 3b-1. Preview button on the settings page (real data for at most 45 s, then the sample data, saying why; one preview at a time; no "send to display" here, a "Show on screen now" button comes in part 4): Preview button on the plugin settings page (M5 part 3b-1) #258
  • 3b-2. Example pictures in the Plugin Library (drawn ahead, saved in the state folder, redrawn when the plugin or screen changes): Example pictures in the Plugin Library (M5 part 3b-2) #265
• 3c. Setting helpers (design: docs/decisions/setting-helpers.md, agreed with txoof 2026-10-10). Lookup service: Open-Meteo (gives altitude too). Two PRs, each based on main:
  • 3c-1. The general structure: helpers return choices as dictionaries of kinds (fill, show, link, note), search box, pick list and Use on the settings page: Setting helpers: a search box for plugin settings (M5 part 3c, 1 of 2) #268
  • 3c-2. location with Open-Meteo for met_no and moon_phase, altitude for met_no (the work of Need to add altitude to weather plugin for reliable forecasts #176): Place search for met_no and moon_phase (M5 part 3c, 2 of 2) #271
  • Later: command line paperpi helper met_no.location "...": Setting helpers on the command line: paperpi helper <type>.<helper> #269
• 4. Home page (current screen image, updates by itself; "Show on screen now" button for a saved plugin, agreed 2026-10-09), warnings page, "config file changed outside the web interface. Apply changes?".
  • txoof, 2026-10-10: the image of what is on the screen now goes at the top of the home page (the main screen of the web interface), before anything else.
  • Designed with txoof on 2026-10-11 using clickable mockups: the home page shows the screen picture at the top (shrinks to a slim bar while scrolling) and replaces the Active Plugins page (plugin cards with their last picture, list or grid, drag to reorder, Show now, Skip to next, Refresh); a menu on every page (covers Web interface: navigation menu on every page #262); light/dark button.
  • The Warnings page gets a Full log tab: the log lines since PaperPi started (kept in memory), with filter, search, new lines while the page is open, and Download log as a text file (txoof, 2026-10-11).
  • Hand edits: a bar on every page links to a Review changes page (old → new per plugin, Apply changes, Undo hand edits). Command line paperpi reload: Command line: paperpi reload applies config changes and reports the result #272.
  • PRs, each based on main, one after another:
    • 4-1. New look, menu on every page (closes Web interface: navigation menu on every page #262), light/dark button, design decisions in web-interface.md: Web interface: new look, menu on every page, light/dark button (M5 part 4, 1 of 5) #274
    • 4-2. Scheduler controls (Show now as an extra turn, Skip, Refresh, Dismiss) and a summary of its state, no web pages yet: Scheduler controls: Show now, Skip, Refresh, Try again now, and a summary (M5 part 4, 2 of 5) #276
    • 4-3. The new Home page (screen picture at the top, plugin cards, drag to reorder); replaces Active Plugins: Home page: the screen now, a card per plugin, change the order (M5 part 4, 3 of 5) #280
    • 4-4. Warnings page and log (small log file + memory, Full log tab, download)
    • 4-5. Review changes page
    • Plugin Library refresh (plugin and layout titles, a picture for every layout, Look closer, Add window)
• 5. Application and screen settings.
  • txoof, 2026-10-10: a way to change the display type and the other system settings in the web interface, not only in the config file: [display] (type, model, width/height, mode, rotation, color, vcom, max_refresh, clean_every, on_exit, fallback_clock, splash_time) and [web] (port, address, login, password). To decide when starting: which settings apply at once and which need a restart (docs/decisions/live-config-reload.md), and how a wrong screen type or port is undone when the page can't be reached any more.

Area

web (src/paperpi/web/), core (cli.py, config.py, scheduler.py hooks), ci (pyproject.toml, uv.lock), docs.