Install Postulo as a web app on the browsers that support it #895

New issue

Closed

opened 2026-10-12 07:06:46 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-10-12 07:06:46 +00:00

Owner

What is already there

core:manifest (src/postulo/core/views.py, manifest.webmanifest) serves a manifest named after the instance, with start_url, display: standalone, colours and 192/512 icons; base.html links it, plus an apple-touch-icon.
/sw.js (src/postulo/static/js/sw.js) is a service worker for push notifications only: no fetch handler, by design. It is registered only when somebody turns browser notifications on.
The CSP already allows manifest-src 'self'.

So the pieces exist, but nobody has made sure Postulo installs cleanly, nor what it looks and behaves like once it does.

What to do

The manifest, completed. An id and a scope, lang and dir in the active language, the icons split into a purpose: "any" and a separate purpose: "maskable" image (one file serving both is discouraged and gets cropped), theme_color/background_color that follow the theme, and shortcuts for the main destinations (board, listings, calendar). Optionally screenshots, which Chromium shows in its richer install dialog.
The page head. <meta name="theme-color"> for light and dark (media="(prefers-color-scheme: …)"), and what Safari still reads (apple-mobile-web-app-title, the status-bar style).
Installability on every supported browser. Check against each browser's current install criteria; where one still asks for a registered service worker, register /sw.js for every signed-in visit, not only when push is turned on. The worker stays as it is: no caching of application pages.
An offline page, and only that. When the network or the server is down, the installed app shows a translated “Postulo cannot reach its server” page instead of the browser's own error. That is the one thing the worker may hold in its cache; no data is cached.
Behaving in a window with no browser around it. In display-mode: standalone there is no back button and no address bar: check that every page can be left from within the interface, that links to other sites (postings, company websites, plugin links) open in the browser rather than inside the app window, and that downloads, printing and signing in and out still work.
An install entry. Where the browser offers beforeinstallprompt, an Install Postulo entry in the user menu; where it does not (Safari), a short line in the help saying how to add it from the browser's own menu. Nothing nags, and nothing shows once it is installed.
The operator. The installed name and icon follow the instance name and, when one is set, the instance's own logo; document in the wiki that installing needs HTTPS (a secure context) and what a reverse proxy must pass through (/sw.js and manifest.webmanifest at the root of the site).

Done when

Chrome/Edge on desktop and Android offer to install Postulo, and Safari on iOS adds it to the home screen with the right name, icon and colours.
The installed app opens in its own window on the board, in the account's language, in light and dark.
With the server unreachable, the installed app shows Postulo's offline page.
Lighthouse's PWA/installability checks pass, and a browser test covers the manifest's fields and the offline page.
All new strings are in the catalogues (through Weblate) and the wiki says how to install it.

Postulo should install and run as a web app (a progressive web app) on the browsers that support it: Chromium-based browsers on desktop and Android (Chrome, Edge, Brave, Samsung Internet…), and Safari on iOS, iPadOS and macOS (*Add to Home Screen* / *Add to Dock*). Once installed it opens in its own window, with its own icon, without the browser's address bar and tabs. ## What is already there - `core:manifest` (`src/postulo/core/views.py`, `manifest.webmanifest`) serves a manifest named after the instance, with `start_url`, `display: standalone`, colours and 192/512 icons; `base.html` links it, plus an `apple-touch-icon`. - `/sw.js` (`src/postulo/static/js/sw.js`) is a service worker for push notifications only: no fetch handler, by design. It is registered only when somebody turns browser notifications on. - The CSP already allows `manifest-src 'self'`. So the pieces exist, but nobody has made sure Postulo installs cleanly, nor what it looks and behaves like once it does. ## What to do 1. **The manifest, completed.** An `id` and a `scope`, `lang` and `dir` in the active language, the icons split into a `purpose: "any"` and a separate `purpose: "maskable"` image (one file serving both is discouraged and gets cropped), `theme_color`/`background_color` that follow the theme, and `shortcuts` for the main destinations (board, listings, calendar). Optionally `screenshots`, which Chromium shows in its richer install dialog. 2. **The page head.** `<meta name="theme-color">` for light and dark (`media="(prefers-color-scheme: …)"`), and what Safari still reads (`apple-mobile-web-app-title`, the status-bar style). 3. **Installability on every supported browser.** Check against each browser's current install criteria; where one still asks for a registered service worker, register `/sw.js` for every signed-in visit, not only when push is turned on. The worker stays as it is: no caching of application pages. 4. **An offline page, and only that.** When the network or the server is down, the installed app shows a translated “Postulo cannot reach its server” page instead of the browser's own error. That is the one thing the worker may hold in its cache; no data is cached. 5. **Behaving in a window with no browser around it.** In `display-mode: standalone` there is no back button and no address bar: check that every page can be left from within the interface, that links to other sites (postings, company websites, plugin links) open in the browser rather than inside the app window, and that downloads, printing and signing in and out still work. 6. **An install entry.** Where the browser offers `beforeinstallprompt`, an *Install Postulo* entry in the user menu; where it does not (Safari), a short line in the help saying how to add it from the browser's own menu. Nothing nags, and nothing shows once it is installed. 7. **The operator.** The installed name and icon follow the instance name and, when one is set, the instance's own logo; document in the wiki that installing needs HTTPS (a secure context) and what a reverse proxy must pass through (`/sw.js` and `manifest.webmanifest` at the root of the site). ## Done when - Chrome/Edge on desktop and Android offer to install Postulo, and Safari on iOS adds it to the home screen with the right name, icon and colours. - The installed app opens in its own window on the board, in the account's language, in light and dark. - With the server unreachable, the installed app shows Postulo's offline page. - Lighthouse's PWA/installability checks pass, and a browser test covers the manifest's fields and the offline page. - All new strings are in the catalogues (through Weblate) and the wiki says how to install it.

tiagoagueda added this to the 0.5.0 milestone

2026-10-12 07:06:54 +00:00

tiagoagueda added the

enhancement

interface

labels

2026-10-12 07:06:55 +00:00

tiagoagueda referenced this issue from a commit

2026-10-12 11:15:31 +00:00

Postulo installs as an app on the browsers that support it

tiagoagueda closed this issue

2026-10-12 11:15:31 +00:00