PC self‐hosting

Run a federation node on your PC

What you need

• PHP on your computer (XAMPP, MAMP, Laragon, or plain PHP)
• A public HTTPS URL so Litter Layer can reach your PC (home internet is usually not public). Easiest: Cloudflare Tunnel or ngrok pointing at your local server
• The starter pack from litterlayer.com/federation/ (Download starter pack)

1. Put the files in a folder (subdomain is fine)

Unzip the starter pack into one folder, e.g. my-node/:

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

2. Edit two files The first file you will edit is .well-known/litterlayer.json — use your public HTTPS URL (not localhost):

Notice that the base_url includes the subdomain or folder where these files live.

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

The other file you will edit is sites.json — list pages you want searchable (url, title, description, score).

[
  {
    "url": "https://wilcosky.com/",
    "title": "wilcosky.com",
    "description": "Personal site of Billy Wilcosky — writing, projects, and links on the small web.",
    "score": 1.0
  },
  {
    "url": "http://www.internetlastpage.com/",
    "title": "The Last Page of the Internet",
    "description": "Ta Da! You have reached the very last page of the Internet. Turn off your computer and go have fun.",
    "score": 0.9
  }
]

3. Run PHP locally In that folder:

cd my-node
php -S localhost:8080
Or point XAMPP/MAMP’s web root at my-node/.

4. Expose it with HTTPS Use a tunnel so the internet gets https://your-url/...:

Cloudflare Tunnel or ngrok → forward to localhost:8080

Your public URL might look like https://abc123.ngrok-free.app or your own domain

Update litterlayer.json so base_url matches that exact HTTPS URL.

/search must work. In other words Litter Layer must be able to find /search, not /search.php. With Apache + .htaccess, the starter rewrite handles it. With php -S only, you may need a tunnel + Apache, or ask AI for a simple router script (so that search.php is converted to /search).

Using Nginx instead of Apache?

Point root at your folder and add a /search rule:

server {
    listen 443 ssl;
    server_name my-node.example.com;
    root /var/www/my-node;
    index index.html;
    # SSL cert paths here (certbot, etc.)
    location = /.well-known/litterlayer.json {
        default_type application/json;
        try_files /litterlayer.json =404;
    }
    location = /search {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/search.php;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;   # adjust for your PHP-FPM socket
    }
    location ~ \.php$ {
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

5. Test Descriptor (browser): https://your-url/.well-known/litterlayer.json → should show JSON

Search (terminal):

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

6. Register Go to litterlayer.com/federation/ and submit:

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

Wait for admin approval. Then federated search can include your node.

PC tips

• localhost alone won’t work — the hub must reach you over HTTPS from the internet.
• Keep the tunnel/server running while you test and after approval.
• base_url must match where search.php lives (folder URL if not site root).

Full shared-hosting steps (same files, more detail): litterlayer.com/federation/