@@ -6,6 +6,21 @@ A minimal, fast, JSON-LD native Solid server for the agentic web.
 
 **[Documentation](https://javascriptsolidserver.github.io/docs/)** | **[GitHub](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer)**
 
+## Contents
+
+- [Architecture](#architecture)
+- [Features](#features)
+- [Quick Start](#quick-start)
+- [Installing with Podman](#installing-with-podman)
+- [Running with Podman](#running-with-podman)
+- [CLI Reference](#cli-reference)
+- [Documentation](#documentation)
+- [Comparison](#comparison)
+- [Performance](#performance)
+- [Running Tests](#running-tests)
+- [Maintainers](#maintainers)
+- [License](#license)
+
 ## Architecture
 
 <p align="center">
@@ -84,6 +99,187 @@ npm install -g javascript-solid-server
 jss start --port 8080 --nostr --git
 ```
 
+## Installing with Podman
+
+These steps install Podman and the helper tools used to run JSS in a Podman pod
+(with a `Makefile`, a `jss.yaml` pod spec and helper scripts, all in the
+[`podman/`](podman/) folder). Podman isolates the JSS from your host system and Podman Pods can be orchestrated with Kubernetes.
+
+You need Podman, `make`, and `curl`, `jq` and `openssl` for the helper
+scripts. Then run everything from the `podman/` folder of this repo (see
+[Running](#running-with-podman)). Only Ubuntu has been tested here; the macOS and Windows
+steps follow Podman's standard setup and are untested.
+
+### Ubuntu
+
+```bash
+sudo apt install -y podman make curl jq openssl
+```
+
+### Linux Mint
+
+Linux Mint 21 and 22 are based on Ubuntu, so it's the same:
+
+```bash
+sudo apt install -y podman make curl jq openssl
+```
+
+Mint 22 (Ubuntu 24.04 base) ships Podman 4.9, which has everything used here
+(`podman kube play --replace --publish`, `podman kube down`). Mint 21 (Ubuntu
+22.04 base) ships Podman 3.4, which is too old; upgrade to Mint 22 or install a
+newer Podman from the [Podman install page](https://podman.io/docs/installation).
+
+Rootless Podman needs your user in `/etc/subuid` and `/etc/subgid`; normal
+Mint accounts already are. Check with:
+
+```bash
+grep "^$USER:" /etc/subuid /etc/subgid
+```
+
+### macOS
+
+Podman runs containers in a small Linux VM on macOS. With
+[Homebrew](https://brew.sh/):
+
+```bash
+xcode-select --install
+```
+
+```bash
+brew install podman jq
+```
+
+```bash
+podman machine init && podman machine start
+```
+
+`xcode-select --install` provides `make` (`curl` and `openssl` are built in).
+Published ports such as `127.0.0.1:4443` are forwarded from the VM to your Mac,
+so <http://localhost:4443/> works as on Linux. Keep your Podman setup under your home
+folder, which the VM can see. The `jss-data` and `jss-secrets` volumes live
+inside the VM, so on-disk volume paths are
+Linux-only. After a reboot, run `podman machine start` before `make up`.
+[Podman Desktop](https://podman-desktop.io/) is a graphical alternative to the
+`brew` install. For HTTPS, `brew install caddy`.
+
+### Windows
+
+The simplest route is WSL 2 with Ubuntu, then the Ubuntu steps inside it. In
+PowerShell as administrator:
+
+```powershell
+wsl --install -d Ubuntu
+```
+
+Restart if asked, open the **Ubuntu** app, and run:
+
+```bash
+sudo apt update && sudo apt install -y podman make curl jq openssl
+```
+
+Keep your Podman setup inside the Ubuntu home folder (for example `~/git/`), not under
+`/mnt/c/`, and run the `make` commands from there. WSL forwards `localhost`,
+so <http://localhost:4443/> opens from your Windows browser.
+
+Alternatively, install Podman for Windows (it also runs on WSL 2) with
+`winget install -e --id RedHat.Podman` or [Podman Desktop](https://podman-desktop.io/),
+then `podman machine init` and `podman machine start` (again after each
+reboot). From PowerShell you can then use the commands in
+[Running without make](#running-without-make), but the `Makefile` and the
+`create-pod`/`grant-webid` scripts need bash (WSL or Git Bash). For HTTPS,
+`winget install -e --id CaddyServer.Caddy`, or install Caddy inside WSL.
+
+## Running with Podman
+
+Run `make` and the `podman` commands below from the `podman/` folder of this
+repo, which contains `jss.yaml` and the `Makefile`. They use relative paths such
+as `jss/`, `profiles/` and `jss.yaml`, so they fail from anywhere else.
+
+| Path (under `podman/`) | Purpose |
+| --- | --- |
+| `jss/Containerfile` | Image: Node 22 + `javascript-solid-server` (pinned via `JSS_VERSION`) |
+| `jss.yaml` | Kubernetes v1 Pod run with `podman kube play` (volumes `jss-data`, `jss-secrets`) |
+| `profiles/local.yaml` | ConfigMap for `http://localhost:4443/` |
+| `profiles/lan.yaml` | ConfigMap for LAN access (`0.0.0.0:4443`) |
+| `profiles/internet.yaml` | ConfigMap for a public HTTPS domain behind Caddy, invite-only |
+| `profiles/*.local.yaml` | Your machine-specific copies of the profiles (gitignored, used automatically) |
+| `proxy/Caddyfile` | Host-side Caddy reverse proxy (internet site, LAN `tls internal` example) |
+| `scripts/create-pod.sh` | Create a pod with a generated password, saving the login outside the repo |
+| `scripts/grant-webid.sh` | Grant a WebID access to a container, keeping existing ACL rules |
+| `Makefile` | Build / run / inspect / reset commands |
+
+### With make
+
+| Command | What it does |
+| --- | --- |
+| `make up` | Build the image and start the pod (`PROFILE=local` by default) |
+| `make up PROFILE=lan` | Same, with the `lan` profile, published on `0.0.0.0:4443` |
+| `make up PROFILE=internet` | Same, with the `internet` profile, on `127.0.0.1:4443` behind Caddy |
+| `make down` | Stop and remove the pod (volumes are kept) |
+| `make restart` | `down` then `up` |
+| `make logs` | Follow server logs |
+| `make status` | Show pod, container, and volume state |
+| `make shell` | Shell inside the server container (e.g. for `jss invite create`) |
+| `make rebuild` | Rebuild the image without cache, then restart |
+| `make reset` | Stop the pod and, after confirmation, delete all data and secrets |
+| `make caddy-validate` | Check `proxy/Caddyfile` in a throwaway Caddy container |
+| `make create-pod NAME=…` | Create a pod (account) and save its login to `~/.config/jss-dev/<name>-account.txt` |
+| `make grant-webid POD=… CONTAINER=… WEBID=…` | Give a WebID Read/Write/Control on a container |
+
+Pass the same `PROFILE=` to `restart` and `rebuild` that you used for `up`.
+
+### Running without make
+
+Without make, the equivalents are `podman kube play --replace --configmap profiles/local.yaml --publish 127.0.0.1:4443:4443 jss.yaml` to start and `podman kube down jss.yaml` to stop.
+Build the image first with `podman build -t localhost/jss:latest jss`
+(`make up` does this for you). For another profile, use
+`profiles/<name>.yaml` (or your `profiles/<name>.local.yaml`) and its bind:
+`--publish 0.0.0.0:4443:4443` for `lan`, `--publish 127.0.0.1:4443:4443` for
+`local` and `internet`.
+
+### Is it running?
+
+With make:
+
+```bash
+make status
+```
+
+The `jss` pod should show `Running` and `jss-server` should show `Up`, with
+`127.0.0.1:4443->4443/tcp` (or `0.0.0.0:4443` on the `lan` profile). `Exited`
+or no pod at all means it's stopped. `make logs` follows the server log.
+
+Without make:
+
+```bash
+podman pod ps
+```
+
+```bash
+podman ps --all --filter name=jss-server
+```
+
+Look for `Running` (pod) and `Up …` (container); `Exited` means it stopped.
+Follow the log with:
+
+```bash
+podman logs -f jss-server
+```
+
+Either way, check that it answers HTTP:
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:4443/
+```
+
+`200` means it's up; `000` means nothing is listening on port 4443. You can
+also open <http://localhost:4443/> in a browser.
+
+The pod doesn't start again by itself after a reboot (rootless Podman doesn't
+start pods at boot unless you set that up), so after restarting the machine,
+run `make up` again. Your data is kept in the `jss-data` and `jss-secrets`
+volumes.
+
 ## CLI Reference
 
 ```bash

@@ -0,0 +1,2 @@
+data/
+profiles/*.local.yaml
@@ -0,0 +1,72 @@
+# Contained JavaScript Solid Server, run with Podman.
+# Usage: make up [PROFILE=local|lan|internet]
+
+PROFILE ?= local
+IMAGE   := localhost/jss:latest
+CONTAINER := jss-server
+CADDY_IMAGE := docker.io/library/caddy:2
+
+# A gitignored profiles/<profile>.local.yaml, if present, overrides the
+# committed profile (e.g. to set your real hostname or LAN IP).
+CONFIG := $(firstword $(wildcard profiles/$(PROFILE).local.yaml) profiles/$(PROFILE).yaml)
+
+ifeq ($(PROFILE),lan)
+BIND := 0.0.0.0:4443:4443
+else
+BIND := 127.0.0.1:4443:4443
+endif
+
+.PHONY: build up down restart logs status shell reset rebuild caddy-validate grant-webid create-pod
+
+build:
+	podman build -t $(IMAGE) jss
+
+up: build
+	@echo "Using $(CONFIG), publishing $(BIND)"
+	podman kube play --replace \
+		--configmap $(CONFIG) \
+		--publish $(BIND) \
+		jss.yaml
+
+down:
+	podman kube down jss.yaml
+
+restart: down up
+
+logs:
+	podman logs -f $(CONTAINER)
+
+status:
+	podman pod ps --filter name=jss
+	podman ps --all --filter pod=jss
+	podman volume ls --filter name=jss-
+
+shell:
+	podman exec -it $(CONTAINER) sh
+
+reset:
+	-podman kube down jss.yaml
+	@printf 'This permanently deletes volumes jss-data and jss-secrets (all pods, users, and logins). Type "yes" to continue: '; \
+	read answer; [ "$$answer" = "yes" ] || { echo "Aborted."; exit 1; }
+	podman volume rm jss-data jss-secrets
+
+rebuild:
+	podman build --no-cache -t $(IMAGE) jss
+	$(MAKE) restart PROFILE=$(PROFILE)
+
+# Check proxy/Caddyfile syntax in a throwaway Caddy container (nothing is
+# installed on the host).
+caddy-validate:
+	podman run --rm -v ./proxy/Caddyfile:/etc/caddy/Caddyfile:ro,Z $(CADDY_IMAGE) \
+		caddy validate --adapter caddyfile --config /etc/caddy/Caddyfile
+
+# Create a pod with a generated password, saved to ~/.config/jss-dev/<name>-account.txt.
+# Usage: make create-pod NAME=billy [EMAIL=billy@example.com]
+create-pod:
+	scripts/create-pod.sh "$(NAME)" $(EMAIL)
+
+# Grant a WebID Read/Write/Control on a container, keeping existing rules.
+# Usage: make grant-webid POD=test CONTAINER=private WEBID=https://... [EMAIL=... PASSWORD=...]
+grant-webid:
+	scripts/grant-webid.sh "$(POD)" "$(CONTAINER)" "$(WEBID)"
+
@@ -0,0 +1,40 @@
+# JSS pod definition.
+#
+# Runs locally with:  podman kube play --configmap profiles/<profile>.yaml jss.yaml
+# (the Makefile wraps this). It is a plain Kubernetes v1 Pod, so it also works
+# on Kubernetes once localhost/jss:latest has been pushed to a registry and the
+# image reference below is updated.
+apiVersion: v1
+kind: Pod
+metadata:
+  name: jss
+  labels:
+    app: jss
+spec:
+  restartPolicy: Always
+  containers:
+    - name: server
+      image: localhost/jss:latest
+      envFrom:
+        - configMapRef:
+            name: jss-config
+      ports:
+        - containerPort: 4443
+          hostPort: 4443
+          hostIP: 127.0.0.1
+      volumeMounts:
+        # Pod storage (all user data).
+        - name: jss-data
+          mountPath: /data
+        # JSS keeps its token-signing secret in ~/.jss/token.secret.
+        # Without a persistent volume here, every restart generates a new
+        # secret and all existing logins/tokens break.
+        - name: jss-secrets
+          mountPath: /home/node/.jss
+  volumes:
+    - name: jss-data
+      persistentVolumeClaim:
+        claimName: jss-data
+    - name: jss-secrets
+      persistentVolumeClaim:
+        claimName: jss-secrets
@@ -0,0 +1,22 @@
+# JavaScript Solid Server (JSS) image.
+# Build: podman build -t localhost/jss:latest jss
+FROM docker.io/library/node:22-bookworm-slim
+
+ARG JSS_VERSION=0.0.224
+
+RUN npm install -g --omit=dev javascript-solid-server@${JSS_VERSION} \
+ && npm cache clean --force \
+ && mkdir -p /data /home/node/.jss \
+ && chown node:node /data /home/node/.jss
+
+USER node
+WORKDIR /data
+
+ENV JSS_ROOT=/data \
+    JSS_HOST=0.0.0.0 \
+    JSS_PORT=4443
+
+EXPOSE 4443
+
+ENTRYPOINT ["jss"]
+CMD ["start"]
@@ -0,0 +1,28 @@
+# Internet profile: `make up PROFILE=internet` keeps JSS bound to
+# 127.0.0.1:4443; Caddy on the host terminates HTTPS for the public name and
+# proxies to it (see proxy/Caddyfile).
+#
+# Copy this file to profiles/internet.local.yaml (gitignored; the Makefile
+# uses it automatically) and replace CHANGE-ME.example.com with your real
+# domain, the same name as in the Caddyfile. Keep the trailing slash.
+#
+# Security:
+# - JSS_INVITE_ONLY: the IdP sign-up form needs an invite code (create them
+#   with `make shell`, then `jss invite --help`). It does NOT cover the
+#   POST /.pods API, so the Caddyfile blocks that with 403. Create accounts
+#   on this host with `make create-pod` (talks to localhost:4443 directly).
+# - remoteStorage (/storage/me/...) is always on in JSS 0.0.224 and has no env
+#   var to disable it. It lets any logged-in account bypass WAC, so the
+#   Caddyfile blocks /storage/*. Never expose port 4443 directly.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: jss-config
+data:
+  JSS_IDP: "true"
+  JSS_IDP_ISSUER: "https://CHANGE-ME.example.com/"
+  JSS_MULTIUSER: "true"
+  JSS_INVITE_ONLY: "true"
+  JSS_CONNEG: "true"
+  JSS_NOTIFICATIONS: "true"
+  JSS_LOG_LEVEL: "warn"