This guide explains how to self-host your own Seed Hypermedia gateway, including running a custom fork.

A Seed gateway consists of two main components:

• seed-daemon - The P2P node that stores and syncs documents

• seed-web - The web interface that serves content

The easiest way to run a gateway is with Docker Compose. Create a docker-compose.yml file:

version: '3.8'
services:
  seed-daemon:
    image: seedhypermedia/daemon:latest
    ports:
      - '56000:56000'  # P2P
      - '56001:56001'  # gRPC
      - '56002:56002'  # HTTP
    volumes:
      - ./daemon-data:/data

  seed-web:
    image: seedhypermedia/site:latest
    ports:
      - '3000:3000'
    environment:
      - DATA_DIR=/data
      - DAEMON_GRPC_URL=http://seed-daemon:56001
      - DAEMON_HTTP_URL=http://seed-daemon:56002
    volumes:
      - ./web-data:/data
    depends_on:
      - seed-daemon

Then run:

docker compose up -d

The web component needs a config.json in its data directory:

{
  "availableRegistrationSecret": "your-secret-here",
  "registeredAccountUid": null
}

After starting, register your account by visiting your-domain/hm/register?secret=your-secret-here

To run custom modifications, you'll need to build your own Docker image.

• Docker with at least 10GB free disk space

• The seed-hypermedia source code

# Clone the repo
git clone https://github.com/seed-hypermedia/seed
cd seed

# Make your modifications to frontend/apps/web/

# Build the Docker image
docker build -f frontend/apps/web/Dockerfile -t my-seed-web:custom .

# This takes 5-10 minutes

Out of Memory: The Vite build requires significant memory. If you hit OOM errors, the Dockerfile includes NODE_OPTIONS for increased heap size.

Disk Space: Docker build cache can fill up. Clean with:

docker system prune -af && docker builder prune -af

For production, you'll want:

• A reverse proxy (nginx, Caddy) for HTTPS

• Ports 56000-56002 open for P2P connectivity

• DNS pointing to your server

Your daemon will automatically discover peers and sync content. To ensure connectivity to the main network, your daemon should be able to reach the production peer ID:

12D3KooWEDdEeuY3oHCSKtn1eC7tU9qNWjF9bb8sCtHzpuCjvomQ

• /reference/http-api - HTTP API reference

• /reference/troubleshooting - Common issues and solutions