Context
When JSS initializes a single-user pod, it writes a default `index.html` (the server-root welcome page) and `index.html.acl` (public-read) into the pod root. A downstream wrapper that wants to ship a different landing page — branding, additional CTAs, directory tiles, etc. — currently has no clean hook.
The concrete use case: jspod is a thin opinionated wrapper around JSS aimed at first-time users. It wants its own landing page that:
- Shows the rung-1 `me` / `me` credentials inline (so the user doesn't need to read the terminal banner)
- Points at a Solid app to use the pod with (Pilot, etc.)
- Has directory tiles for /profile/, /public/, etc.
- Reuses JSS's HEAD-adaptive Sign in / Sign up logic
- Uses a different visual style (cream + card, matching jspod's data browser)
Current stopgap
jspod's startup waits for the server to become responsive, then `copyFileSync`'s its bundled `welcome.html` over `pod-data/index.html`. This works but has known cracks:
- Unconditional overwrite — user customizations to `pod-data/index.html` are lost on the next jspod start
- Race-prone — depends on JSS finishing pod init before jspod overwrites
- Doesn't update `index.html.acl` if the wrapper needs a different ACL
- The wrapper has to bundle its own copy and ship it
Code lives at jspod#11.
Proposed options
In order of effort:
A. Skip-if-exists for the root `index.html` seed
JSS's pod-init checks whether `pod-data/index.html` already exists and skips writing the default if so. Then a wrapper can pre-create the file before spawning JSS.
- Pro: smallest change. One `if (!existsSync) writeFileSync` line.
- Con: user customizations to the file would also stop JSS from re-writing on upgrade — but that's already the case for everything else in pod-data.
B. CLI / config option for a custom landing page path
```
--landing-page
```
If set, JSS uses that file's contents instead of its built-in template. Wrappers point to their own file.
- Pro: explicit. No file-system races. Wrapper doesn't bundle a duplicate of the seed.
- Con: a bit more code (config plumbing, template loader, fallback).
C. Templating / partials
The landing page becomes a template that downstream wrappers can override at known anchor points (header, actions, footer, etc.) without replacing the whole file.
- Pro: structural integrity preserved across JSS upgrades. Wrappers inherit any future JSS improvements automatically.
- Con: by far the most work. Probably out of scope for now.
Recommendation
Start with A. It's the cheapest change, unblocks jspod (and any other wrapper), and doesn't lock JSS into a specific template-customization API. B is a reasonable follow-up if more wrappers show up with different needs.
Compatibility
A is non-breaking. Existing JSS users have no `pod-data/index.html` until JSS writes one, so behavior is unchanged the first time. Subsequent starts already skip if the file exists (JSS doesn't currently overwrite on each start — only writes if missing) — confirming that would be part of the PR.
Context
When JSS initializes a single-user pod, it writes a default `index.html` (the server-root welcome page) and `index.html.acl` (public-read) into the pod root. A downstream wrapper that wants to ship a different landing page — branding, additional CTAs, directory tiles, etc. — currently has no clean hook.
The concrete use case: jspod is a thin opinionated wrapper around JSS aimed at first-time users. It wants its own landing page that:
Current stopgap
jspod's startup waits for the server to become responsive, then `copyFileSync`'s its bundled `welcome.html` over `pod-data/index.html`. This works but has known cracks:
Code lives at jspod#11.
Proposed options
In order of effort:
A. Skip-if-exists for the root `index.html` seed
JSS's pod-init checks whether `pod-data/index.html` already exists and skips writing the default if so. Then a wrapper can pre-create the file before spawning JSS.
B. CLI / config option for a custom landing page path
```
--landing-page
```
If set, JSS uses that file's contents instead of its built-in template. Wrappers point to their own file.
C. Templating / partials
The landing page becomes a template that downstream wrappers can override at known anchor points (header, actions, footer, etc.) without replacing the whole file.
Recommendation
Start with A. It's the cheapest change, unblocks jspod (and any other wrapper), and doesn't lock JSS into a specific template-customization API. B is a reasonable follow-up if more wrappers show up with different needs.
Compatibility
A is non-breaking. Existing JSS users have no `pod-data/index.html` until JSS writes one, so behavior is unchanged the first time. Subsequent starts already skip if the file exists (JSS doesn't currently overwrite on each start — only writes if missing) — confirming that would be part of the PR.