Run Your Own Gateway

What is a Gateway?

A web gateway provides read-only HTTP access to Swimchain content. It connects to one or more Swimchain nodes and serves content to web browsers. Gateways:

• Index content for full-text search
• Render content as SEO-friendly HTML
• Apply rate limiting to prevent abuse
• Provide a familiar web browsing experience

Gateways do not allow posting, replying, or engaging with content. That requires a full Swimchain client.

Why run a gateway?

Keeping the network open and readable is reason enough — a public gateway is community infrastructure, like running a Bitcoin node. But a gateway doesn't have to mirror all of Swimchain. It's just a node plus a rendering layer, and you choose the slice: one space, a curated set, or your own namespace. That makes Swimchain a headless, self-moderating content backend — think Contentful or Sanity, but decentralized, un-censorable, and with identity and anti-spam already built in. You point a bespoke frontend at the slice you care about and ship a product with no database and no server of your own.

Example: a news site with no backend

Say you want to run a news site. On the network you create a space for it — public, private, or its own app namespace — and your editors publish articles into it from a normal Swimchain client. Your website runs a gateway pointed at just that space and renders the articles as a clean, branded feed at your domain. Readers see a news site; they never know or care that the “CMS” is a P2P network. There is no content database to run, back up, or get breached, and nobody — not even you — can quietly rewrite what was published, because the record lives on the chain.

This is publishing, not social media: readers just read, no one needs an account, and the whole thing is a thin frontend over a slice of the network. The existing wiki client already works exactly this way — it's a gateway-shaped frontend scoped to wiki spaces, presented as an ordinary wiki.

See it live: The Daily Drift is exactly this — a newspaper whose every story is a real post on the Swimchain testnet, rendered by one node with no database or app backend. (Yes, that node is a server. That's the honest part.)

Adding interaction, when you want it

A read-only gateway is deliberately read-only — that's what makes it safe to expose publicly. When you do want visitors to participate, you have options:

• Let readers bring their own identity. A visitor who runs a Swimchain client can comment or reply as themselves — you just link the thread. Their keys stay on their device; you host nothing.
• Proxy identities for visitors (advanced). With some work your site can post on a visitor's behalf through a node's JSON-RPC — e.g. a comment box under each article. Just know the tradeoff: if your server holds the keys, you've taken on custody, so scope those identities narrowly. Posting is still sponsorship- and proof-of-work-gated, so you inherit spam resistance for free.
• Ship a full client instead. If the goal is real many-user interaction, distribute an app where each user runs their own node and owns their keys — see the developer docs for the node RPC surface.

The through-line: you decide the slice and the presentation; the network is the invisible, un-censorable, self-moderating database. “No servers” stops being a constraint and becomes “I shipped a content product with zero backend and zero moderation code.”

Quick Start with Docker

The fastest way to run a gateway:

1. Clone the repository

git clone https://github.com/superness/swimchain.git
cd swimchain/web-gateway

2. Configure environment

Create a .env file:

# Gateway identity
GATEWAY_NAME="My Swimchain Gateway"
GATEWAY_OPERATOR="Your Name or Organization"
GATEWAY_URL="https://your-domain.com"

# Node connection
NODE_URL="ws://your-swimchain-node:8765"

# Rate limiting (requests per minute per IP)
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60000

3. Start the gateway

docker-compose up -d

Your gateway will be available at http://localhost:3000.

Configuration Options

Node Requirements

Your gateway needs to connect to at least one Swimchain node. The node should have:

• WebSocket API enabled
• Public content sync enabled
• Sufficient storage for content you want to serve

For high availability, configure multiple nodes:

NODE_URL="ws://node1:8765,ws://node2:8765,ws://node3:8765"

Health Monitoring

The gateway exposes a health endpoint at /api/health:

curl http://localhost:3000/api/health

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-15T10:30:00Z",
  "gateway": {
    "name": "My Swimchain Gateway",
    "operator": "Your Name"
  },
  "node": {
    "connected": true,
    "chainHeight": 12345
  },
  "uptime": 86400
}

Response Status Codes

• 200 OK - Gateway is healthy
• 503 Service Unavailable - Gateway is unhealthy (node disconnected)

Use this endpoint for:

• Kubernetes/Docker health checks
• Load balancer health probes
• Uptime monitoring services

Production Deployment

SSL/TLS with Nginx

For production, use Nginx as a reverse proxy to handle SSL termination:

# nginx.conf
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location / {
        proxy_pass http://gateway:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Resource Limits

Recommended resources per gateway instance:

• Memory: 256MB minimum, 512MB recommended
• CPU: 0.5 cores minimum
• Disk: Minimal (search index is memory-based)

Scaling

Gateways are stateless and can be horizontally scaled. Use a load balancer to distribute traffic across multiple instances.

Rate Limiting

Built-in rate limiting protects your gateway from abuse:

• Default: 100 requests per minute per IP
• Configurable via environment variables
• Returns HTTP 429 when limit exceeded
• Rate limit headers included in responses

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312200

Troubleshooting

Gateway not connecting to node

• Verify NODE_URL is correct
• Check node is running and WebSocket API is enabled
• Ensure network connectivity between gateway and node
• Check firewall rules allow WebSocket connections

High memory usage

• Search index grows with content volume
• Consider increasing memory limit
• Configure content retention policies on your node

Rate limit issues

• Adjust RATE_LIMIT_REQUESTS if too restrictive
• Use Nginx rate limiting for more sophisticated rules
• Consider per-route rate limits for API endpoints

Support

For help operating a gateway:

• GitHub Issues
• GitHub Discussions