Five end-to-end walkthroughs showing how privacytracker actually gets used — kid’s iPad, app comparison, household NAS, regulator audit prep, partner privacy review.
The other Self-Host pages are organised by feature. This one is organised by scenario — five concrete jobs people use privacytracker for, each with the audience setting, install path, and end-to-end steps.If your situation matches one of these, follow the recipe. If it almost-but-not-quite matches, the cross-references at each step let you mix-and-match.
Audience:guardian. Goal:monitor. Install path: desktop app or Docker — whichever you’ll keep running long-term.The job: get a clean view of everything installed on a child’s device, surface what’s high-severity, and notify you only when something actually changes — not every time Apple’s HTML reflows.
1
Set the focus on first run
Open privacytracker, pick Guardian when the audience picker appears, and choose Monitor my apps for changes as the primary goal. The defaults that flow from this combination raise severity-tier visibility on the dashboard, default the bell to only changed apps, and apply 22:00–07:00 quiet hours. You can override any of this later in Settings → Developer Options → Feature flags, but the defaults are tuned for exactly this scenario.
2
Export the kid's app list
Plug the iPad into your Mac, run a Finder backup (no encryption needed), then from your privacytracker source checkout (or any clone of the main repo):
The helper writes a .txt of every installed app’s bundle ID and display name. If you’re not running from source, the helper is published as a stand-alone script under scripts/ios-app-import/ in the main repo — clone just that directory and run it; you don’t need the rest of the codebase.Alternatively, if you have ideviceinstaller installed (brew install libimobiledevice), use --mode device against the connected iPad without taking a backup.
3
Bulk-import into privacytracker
In the onboarding wizard’s Add apps step, click Upload list and pick the .txt from step 2. privacytracker resolves each name through the iTunes Search API, shows you the ranked candidates in a confirm dialog, and starts the scrape once you accept. Apps it can’t resolve land in a needs review tab — usually misspellings or region-locked apps that need a manual App Store URL.
4
Configure quiet hours and the bell
The guardian defaults already enable 22:00–07:00 quiet hours via notifications.not_before, so changes detected overnight defer to morning. Quiet hours hold back only the bell: a notification webhook set to Each change still posts overnight changes as they’re found. If your kid uses different time zones (boarding school, holidays at a relative’s house), adjust under Settings → Notifications → Quiet hours.For the bell itself, leave the default Only when categories change filter on. Re-scrapes that produce no diff don’t add to the unread badge.
5
(Optional) Enable AI for high-severity apps
If you want plain-English summaries of the policies for apps that collect Precise Location, Sensitive Contacts, or Financial Info, configure an AI provider under Settings → AI. The summariser scores each policy against eight fixed lenses (collection_scope, product_use, ads_marketing, third_party_sharing, tracking_analytics, user_controls, data_retention, children_minors) — exactly the questions a guardian wants answered. Hosted providers run a fraction of a cent per app; a local Ollama setup is free at runtime.See Configuration → AI providers for the full setup. To keep it scoped, summarise apps one at a time with the Regenerate button on each app’s detail page — cover the high-severity apps and skip the kid’s wallpaper app.
6
What success looks like
A dashboard view filtered to changed in the last 7 days, a bell that pings you when an app newly collects something it didn’t before (and stays silent otherwise), and a per-app timeline showing exactly when each label appeared.Re-scrape monthly via Settings → Sync → Run now, or leave the 30-minute scheduler running with a daily cadence. The crash-safe resume pattern means a laptop sleep mid-sync doesn’t lose the queue — see Architecture.
Audience:self. Goal: any. Install path: anything — this works fine on a desktop install you only spin up when you need it.The job: you’re picking between two apps that do similar things — say, two journaling apps, two budgeting apps, two flashlight apps with surprisingly elaborate privacy policies. You want to see their privacy labels side by side without installing either one first.
1
Add both apps via App Store URL
From the onboarding wizard or Settings → Apps → Add app, paste the App Store URL of each candidate. privacytracker resolves the numeric track ID and scrapes both. You don’t need to have the apps installed on any device — the scraper just hits Apple’s public HTML.Tip: use the ?utm_source=... parameter on either URL or strip it; the parser only cares about the /id<digits>/ segment.
2
Open the Compare view
Go to the dashboard and click Compare in the top bar (or /dashboard/compare). Pick the two apps from the dropdown.The Compare view shows privacy labels in a side-by-side severity-coded grid. Data Used to Track You lines up against Data Used to Track You, Data Linked to You against the same — so you can see which app has Location for tracking and which one only collects it for app functionality.
3
(If AI is configured) read the policy summaries side-by-side
The Compare view’s bottom panel pulls each app’s AI-summarised privacy policy and renders them in two columns, lens-by-lens — collection scope, product use, ads & marketing, third-party sharing, tracking & analytics, user controls, data retention, children & minors. Differences in language at the data retention lens, especially, are usually where the real distinction between two superficially-similar apps shows up.No AI configured? You can still click through to each app’s policy URL on its detail page and read the source.
4
Annotate your decision
On either app’s detail page, drop an annotation explaining your reasoning (I'm picking app A because B sells aggregated data to advertisers and A doesn't). Tag it concern or positive. Set visibility to private if it’s just for you, export if you might share it later — see the next two recipes.
This is also a good way to vet a replacement for an app you already use — add the candidate alongside your current pick and compare before you migrate.
Install path: Docker. Audience: any (the same instance can serve multiple household members; everyone uses the same browser-accessible UI).The job: run privacytracker on always-on hardware (Synology, Unraid, a Raspberry Pi, an old laptop in a closet) so the household can hit it from any device on the LAN, with the data backed up off-host.
1
Set up Docker on the NAS
Synology DSM ships Docker as a Package Center add-on. Unraid has Docker support out of the box. On a Pi or generic Linux box:
Log out and back in so the group membership takes effect.
2
Pull privacytracker
git clone https://github.com/privacykey/privacytracker.gitcd privacytracker# Generate an admin token before first startexport AUDITOR_ADMIN_TOKEN=$(openssl rand -hex 32)echo "AUDITOR_ADMIN_TOKEN=$AUDITOR_ADMIN_TOKEN" >> .env# The hostname the household will use, behind the proxy in the next stepecho "PRIVACYTRACKER_ALLOWED_HOSTS=privacytracker.lan" >> .envecho "PRIVACYTRACKER_TRUST_PROXY=1" >> .env# Keep the database on the NAS's storage, owned by the container's usermkdir -p data && sudo chown 100:101 datadocker compose -f docker-compose.yml -f docker-compose.bind-mount.yml up --build -d
The database now lives at ./data/privacy.db on the NAS’s persistent storage. Confirm it survives down and up (with the same -f flags) before going further. Without the allowed host, the server refuses requests for privacytracker.lan; without trusting the proxy, it can’t see that the browser came in over HTTPS.
3
Front it with a reverse proxy + TLS
The household browses to the NAS’s hostname, not its bare IP. A short Caddyfile:
Caddy gets you automatic Let’s Encrypt TLS if privacytracker.lan resolves on the public internet, or self-signed certs for a LAN-only deploy. The Host header forwarding is non-negotiable — privacytracker enforces a same-origin CSRF check on every mutating verb, so a proxy that strips the Host header will cause every action to fail with 403 {"error":"Cross-origin mutation rejected"}. See Troubleshooting → Reverse-proxy CSRF rejection if you hit that.
4
Lock down the destructive routes
Confirm the admin token from step 2 is taking effect:
# Should fail with 401 {"error":"Admin token required"}:curl -X POST https://privacytracker.lan/api/reset \ -H "Origin: https://privacytracker.lan"# Should succeed (token present):curl -X POST https://privacytracker.lan/api/reset \ -H "Origin: https://privacytracker.lan" \ -H "X-Auditor-Admin-Token: $AUDITOR_ADMIN_TOKEN"
The server compares the token in constant time. Failed attempts append to audit_log as admin_token.login.invalid. There’s no UI for that table — review it with sudo sqlite3 data/privacy.db "SELECT datetime(created_at/1000,'unixepoch'), action, actor_ip FROM audit_log ORDER BY created_at DESC LIMIT 50;".For full hardening, see Security & trust.
5
Set up off-host backups
The NAS’s own RAID is not a backup. Schedule a daily rsync (or NAS-native sync task) of ./data/ to a different drive, ideally a different physical machine. The directory is private to the container’s user, so run it from root’s crontab:
0 3 * * * rsync -a /volume1/docker/privacytracker/data/ user@backup-host:/backups/privacytracker-$(date +\%F)/
Or turn on Settings → Backup → Automatic local snapshots to keep rolling JSON bundles under data/backups/, then sync those out. They’re off by default. See Backup & restore for the full options.
6
What success looks like
Anyone in the house can browse to https://privacytracker.lan, the 30-minute background sync runs unattended, the bell shows newly-changed apps without anyone needing to think about it, and data/privacy.db is replicated nightly to a different machine. The admin token gates POST /api/reset so a curious guest on the LAN can’t wipe the database.
Back-fill a year of history before a regulator audit
Audience: any. Goal: any. Install path: Docker or desktop, with internet access.The job: an organisation needs evidence of an app’s privacy disclosures going back several months or years — for a DPIA, a regulator request, a custody-evaluation submission, or just a personal record. privacytracker’s Wayback importer walks every calendar quarter from Q1 2021 (1 February 2021) forward — the earliest era when Apple’s HTML carries privacy nutrition labels — and pulls the closest archive.org capture per quarter. For an app that’s been live the whole time that’s roughly 19 quarters of history. The parser auto-detects which era it’s looking at: the modern serialized-server-data blob (Nov 2025+) or the older Ember/FastBoot shoebox-media-api-cache-apps shape (Jan 2021 – Nov 2025).
1
Make sure every app of interest is tracked
The Wayback importer only fetches history for apps already in your database. Add them first — by name through the iTunes Search API, by App Store URL, or in bulk from a .txt. See Quickstart → Import your first apps.
2
Run the bulk Wayback import
From Settings → Sync → Wayback import → Run now, or:
The ?stream=1 flag gets you NDJSON events as the run progresses (batch-start, app-start, target, app-done, summary). Without it, the route returns once the run finishes.Expected result: most apps get 1-3 quarterly snapshots; some get none (“skipped, no capture”). For each empty quarter, the importer fires an archive.org Save Page Now request fire-and-forget, so a future run will pick up the newly-archived page.
3
Wait, then re-run
Wayback typically takes a few days to process Save-Page-Now requests. Re-run the import in 1-2 weeks; it’ll pick up captures that weren’t there the first time. The snapshotsRequested counter in the summary tells you how many save-now requests went out — that’s the upper bound on how much new history the next run can find.
4
Inspect the timeline
Open any app’s detail page. Wayback rows render with a purple dot, a clock glyph, and a Wayback · YYYY-MM-DD badge linking to the original archive.org capture. Where a Wayback snapshot is byte-identical to an adjacent live row, a green Matches live sync badge appears — useful for showing a regulator that the archive and the live page agree.Trigger pills (scheduled / manual / import / wayback) on each timeline row tell you the provenance of every snapshot.
Per-app timeline after a full Q1 2021 → present back-fill (mockup)
The bundle covers every tracked app — there’s no per-app selection on this route. The body takes three optional fields: recommenderName (the attribution shown next to your annotations, defaulting to your friend), includeRecommenderProfile (defaults to true), and migrationFlow. Rate-limited to 5 exports per minute.The bundle is a versioned JSON file containing the apps, every snapshot (live + Wayback), AI summaries if you have them, and any annotations marked visibility = 'export'. Private notes are excluded by SQL filter at build time — there is no force-include.For long-term archive, store the bundle alongside the original Wayback capture URLs (they’re embedded in the bundle). The capture URLs use the id_ suffix (/web/<ts>id_/<orig>) so Apple’s HTML comes through clean of archive.org’s toolbar injector — meaning the capture is forensically usable too, not just human-readable.
6
What success looks like
A complete quarterly history per tracked app from Q1 2021 forward (about 19 quarters for an always-live app), exportable as a single JSON file with each snapshot timestamped, sourced (live vs. Wayback), and linked back to the original archive.org capture for independent verification.
Run a privacy review with a partner or family member
Audience:loved_one. Goal:monitor. Install path: any.The job: you and a partner (or another household member, or a friend you’re helping) want to look at your respective app collections together — comparing notes on what each of you has installed and how concerned you each are about specific apps. You don’t want to install another tool on their machine; you want to share a curated bundle they can read.
If you’d rather track their device in your own install, record them as its owner — when you import it, or on Settings → Devices — and use the device menu to switch between your apps and theirs. Removing apps from their device also asks you to confirm you have their permission.
1
Set the audience to loved_one
On first run pick Loved one, or change it later in Settings → Your focus → Adjust. This unlocks the audit-bundle export workflow and adjusts the dashboard’s emphasis from severity-grids toward annotation visibility.The unlocking is literal, not a UI hint: the loved_one audience rule resolves flag.settings.admin.export.audit_bundle to on, which is one of the two things POST /api/export/audit-bundle accepts — so the export is callable straight away, with flag.focus.workflow still at custom. The other route in is the focus wizard’s “I’m preparing a bundle to hand to them” answer, which sets the workflow to other_handoff; that’s what a self or guardian user needs, since for them the flag defaults to off and the route returns 403 until they answer it or switch the flag on under Settings → Developer Options → Feature flags.
2
Annotate as you review
Walk through your tracked apps and write annotations on the ones that warrant a note. Each annotation has:
Tags:concern, positive, follow_up, other
Visibility:export (will appear in the bundle) or private (never leaves your install)
Markdown: linkify cited evidence; the markdown renders in the recipient’s view too
A typical pattern: write an export-visibility note explaining the headline concern in neutral language, then a private note for your own thinking. Both stay attached to the same app on your install; only the first is in the bundle.
3
Export the bundle
Settings → Export → Audit bundle prompts for:
The apps to include (default: all)
Whether to include your privacy profile (the tolerances you assessed against — useful for explaining why you flagged what you flagged)
The free-text attribution field (your name as it’ll appear next to your annotations on the recipient’s view; defaults to your friend if blank)
Click Export, save the JSON.What’s never included: notes flagged private, your audience or goal selections, your flag overrides, your AI provider configuration or keys, your notification preferences.
4
Share the bundle securely
Bundles are unencrypted JSON. Treat them like a personal email — once shared, the recipient can open them indefinitely, and there is no revocation mechanism. Recommended channels:
End-to-end-encrypted messaging (Signal, iMessage)
End-to-end-encrypted email
Direct file transfer over a trusted local network
Don’t paste the contents into public-facing tools (issue trackers, chat rooms, AI assistants). The bundle is plain text — cat-readable.See Security & trust → Audit-bundle export threat model for the full reasoning.
5
Recipient imports the bundle
On the recipient’s privacytracker install, Onboarding → Import audit bundle (or Settings → Import → Audit bundle if they’re past first-run) accepts the file. They see your annotations attributed to the attribution string from step 3. They can edit or delete their copy of those notes — it does not affect the originals on your device.The bundle’s version field guards against schema mismatches: if their install is older than yours, the import refuses with a clear upgrade required message rather than silently misparsing.
6
What success looks like
A shared frame of reference for the conversation. The recipient sees the apps you flagged, your reasoning in the export-visibility annotations, and (optionally) the privacy profile that made them concerning to you in the first place. Your private notes stay yours; the recipient’s response notes stay theirs. No central server, no account creation, no ongoing data flow — just one JSON file passed once.
Mix and match. The audience and goals can be changed any time without resetting your data; the install path can change via the bundle migration flow; the audit-bundle workflow works between any two privacytracker installs regardless of audience.If you find yourself doing the same thing repeatedly and there isn’t a recipe for it, open an issue describing the workflow — that’s how this page grows.
