Self-Hosting Overview

The apps work without a relay server. Invitations can be exchanged in person via QR code, and tree merges happen peer-to-peer.

The relay server adds one capability: distributing encrypted invitations over the internet. This lets you invite someone remotely — over WhatsApp, SMS, or any messaging app — without exposing your infrastructure to that platform.

If your family is entirely local and you prefer the simplest setup, skip this section. You do not need it.

What the relay server does

When you generate a remote invitation:

1. Your device encrypts the invitation payload using AES-256-GCM. The encryption key is the invite token (32 random bytes).
2. The ciphertext is sent to the relay. The relay stores it.
3. You receive a short URL containing the token. You share this URL.
4. The recipient opens the URL. The landing page launches iwacu with the token.
5. Iwacu fetches the ciphertext from the relay, decrypts it using the token, and processes the invitation.
6. The relay deletes the ciphertext. Each token can only be claimed once.

The relay never sees the plaintext. It holds encrypted data it cannot read. Even if the relay is seized or compromised, no invitation contents are exposed.

Why run your own

If you use someone else's relay, you are trusting them to:

• Actually delete tokens after use
• Not log IP addresses
• Not correlate invitation patterns

Running your own relay means you trust yourself. You control what is logged (nothing), who can post tokens (your devices), and when the server goes down.

What you need

• A Linux server with a public IP address, or a machine at home with a stable connection.
• Docker and Docker Compose installed.
• Basic comfort with a terminal.
• Optionally: tor to run the relay as a hidden service (strongly recommended).

Minimum resources: 1 CPU, 256 MB RAM, 1 GB disk. A cheap VPS works fine.

Sections

• Deploy the relay server — Docker Compose setup, configuration, and testing.
• Configure Tor hidden service — How to run the relay behind .onion so the server's IP is never exposed to invitation recipients.