Skip to content

Mac self‐hosting

Jump to bottom
Billy Wilcosky edited this page Jun 20, 2026 · 6 revisions

Run a federation node on your Mac (short version)

What you need

  • PHP (Mac often has it already — check with php -v in Terminal)
  • A public HTTPS URL (tunnel) so Litter Layer can reach your Mac — e.g. Cloudflare Tunnel or ngrok
  • The starter pack from litterlayer.com/federation/
  • No PHP? Install with Homebrew: brew install php

1. Put the files in a folder Unzip the starter pack, e.g.:

~/Sites/my-node/ .well-known/litterlayer.json sites.json search.php .htaccess

2. Edit two files .well-known/litterlayer.json — your public HTTPS URL (not localhost):

{ "node_id": "my-node.example.com", "base_url": "https://my-node.example.com", "categories": ["writing", "tech"], "capabilities": { "search": true }, "performance": { "timeout_ms": 1200 } }

sites.json — pages you want searchable (url, title, description, score).

3. Run PHP on your Mac Open Terminal, go to your folder, start the built-in server:

cd ~/Sites/my-node php -S localhost:8080 Leave that window open while testing.

Alternative: MAMP — set the document root to my-node and use MAMP’s port (often 8888).

4. Expose it with HTTPS Your Mac isn’t reachable from the internet by default. Use a tunnel:

ngrok (quick test):

brew install ngrok ngrok http 8080 Copy the https://….ngrok-free.app URL.

Cloudflare Tunnel — good for a stable URL if you have a domain.

Put that HTTPS URL in litterlayer.json as base_url.

Note: php -S doesn’t read .htaccess, so /search may not work until you use MAMP/Apache or hit search.php directly for local tests. For registration, the hub calls https://your-url/search — Apache + .htaccess, or MAMP with mod_rewrite, is the reliable Mac setup.

5. Test Descriptor (Safari/Chrome): https://your-url/.well-known/litterlayer.json

Search (Terminal):

curl -sS -X POST https://your-url/search
-H "Content-Type: application/json"
-d '{"query":"hello","limit":5}' → expect {"results":[...]}

6. Register https://litterlayer.com/federation/ → submit:

https://your-url/.well-known/litterlayer.json

Wait for approval.

Mac-specific tips

  • Show hidden files in Finder: Cmd + Shift + . to see .well-known
  • Firewall: if using your own domain/IP, allow incoming HTTP/HTTPS in System Settings → Network → Firewall
  • Keep Terminal (or MAMP + tunnel) running while the node is live
  • localhost won’t work for registration — the hub needs your public HTTPS URL

Files & web host instructions: litterlayer.com/federation/

Clone this wiki locally