Holos Relay Server

What is this?

This server acts as a stable identity provider for mobile ActivityPub instances that run directly on smartphones.

The Problem

Mobile apps running their own ActivityPub server face a challenge: their public URL changes constantly because:

• Tunnel URLs change every session (e.g., https://random-abc.tunnel-service.com → https://random-xyz.tunnel-service.com)
• Mobile IP addresses change (WiFi → 4G → WiFi)
• Users can't have a stable ActivityPub identity like @alice@mobile-url.com

The Solution

This relay server provides:

• Stable identities: @alice@yourdomain.com stays the same forever
• Automatic proxying: All ActivityPub requests are forwarded to the current mobile tunnel URL
• Heartbeat system: Tracks which mobile instances are online/offline
• Simple registration: Users register via web or mobile app, then use OAuth 2.0 for Mastodon instance authentication

How It Works

┌────────────────────────────────────────────┐
│ Mastodon Server │
│ Wants to reach: @alice@yourdomain.com │
└─────────────────┬──────────────────────────┘
 │
 │ ActivityPub request
 ↓
┌────────────────────────────────────────────┐
│ Holos Relay Server (This project) │
│ Hosted on: yourdomain.com │
│ ┌──────────────────────────────────────┐ │
│ │ • Receives: @alice@yourdomain.com │ │
│ │ • Looks up: current tunnel URL │ │
│ │ • Proxies to: user's mobile tunnel │ │
│ └──────────────────────────────────────┘ │
└─────────────────┬──────────────────────────┘
 │
 │ HTTP proxy
 ↓
┌────────────────────────────────────────────┐
│ Mobile Phone (User's device) │
│ ┌──────────────────────────────────────┐ │
│ │ • ActivityPub server (local) │ │
│ │ • Tunnel: random-id.tunnel-svc.com │ │
│ │ • Heartbeat: every 30s │ │
│ └──────────────────────────────────────┘ │
└────────────────────────────────────────────┘

Use Cases

• Mobile Fediverse apps that want to run their own instance
• Privacy-focused users who want full control of their data
• Intermittent presence - only online when you want to be
• Self-hosted on phone - complete control over your instance without relying on third-party servers

Features

Core Features

• Stable identities for mobile instances with changing tunnel URLs
• ActivityPub proxy to mobile instances
• WebFinger support for actor discovery
• Heartbeat system to track online/offline status
• Automatic cleanup of inactive instances

Data & Caching

• PostgreSQL persistence with user management
• Redis caching for fast lookups and distributed rate limiting
• Email verification to prevent bots
• Prometheus metrics with real-time and historical data

Security & Moderation

• Admin panel for user moderation (ban/unban, temporary bans)
• Secure authentication with bcrypt password hashing
• OAuth 2.0 authentication system with JWT tokens
• Rate limiting per IP, per user, and globally (configurable)
• Two-Factor Authentication (2FA) with TOTP and backup codes
• API Keys for automation with scopes and per-key rate limits
• Security logging with login attempts, admin actions, and alerts
• Domain blocklist with import/export (Mastodon-compatible)

Real-Time & Notifications

• WebSocket real-time updates - Instant delivery when online
• Push Notifications - UnifiedPush integration for offline delivery
• Activity queue - Persistent storage with automatic cleanup
• Notification preferences - Per-user control over notification types
• See docs/WEBSOCKET-API.md for details

Admin & Management

• Multi-admin system - Super Admin, Admin, and Moderator roles with permissions
• Team invitations - Secure token-based invitation system for new admins
• Custom emojis - Upload and manage custom emojis for the instance
• NodeInfo protocol - Fediverse discovery and statistics (/.well-known/nodeinfo)
• Server metadata - Configurable name, description, rules, contact email
• Email/SMTP configuration - Test mode and encrypted password storage
• Account migration - ActivityPub Move activity support
• Internationalization (i18n) - English and French translations

Identity & Discovery

• WebFinger support - Provides stable identities for mobile instances (@user@relay-domain.com)
• Transparent proxy - Routes ActivityPub requests to mobile tunnel URLs
• Profile caching - User profiles always visible; posts cached with configurable TTL
• Note: Account search and timeline construction are handled by the mobile app

Quick Start

Choose your preferred setup method:

1. Automated Installation (Recommended)

Production-ready installation with one command. Includes automatic nginx configuration and SSL setup.

# Interactive mode
sudo ./scripts/install.sh
# Or automated mode
sudo ./scripts/install.sh --docker \
 --domain yourdomain.com \
 --tunnel-domain tunnel.yourdomain.com

→ Complete guide: docs/INSTALL.md

2. Docker (Advanced)

For custom Docker setups or existing infrastructure. Uses nginx on host by default.

cp .env.example .env.docker
# Configure: DB_PASSWORD, REDIS_PASSWORD, JWT_SECRET, ENCRYPTION_KEY, ADMIN_PASSWORD, DOMAIN
export $(cat .env.docker | xargs)
docker compose up -d
# Optional: Use Caddy for automatic SSL (dedicated server only)
docker compose --profile caddy up -d

→ Complete guide: docs/DOCKER.md

3. Development Setup

Quick local setup for development:

./scripts/setup.sh # Checks dependencies, creates DB, installs packages
npm run dev

4. Manual Installation

Full control over installation and configuration.

→ Complete guide: docs/DEPLOYMENT.md (Manual Deployment section)

For production deployment and detailed configuration, see:

• docs/INSTALL.md - Automated installation script (recommended)
• docs/DOCKER.md - Docker deployment guide
• docs/DEPLOYMENT.md - Manual production deployment guide
• docs/DATABASE-SETUP.md - Database configuration

Documentation

Core Documentation

• README.md - This file (overview & quick start)
• docs/INSTALL.md - Automated production installation (recommended)
• docs/ARCHITECTURE.md - System architecture and components
• docs/DEPLOYMENT.md - Manual production deployment guide (nginx, SSL, PM2, backups)
• docs/DOCKER.md - Docker deployment with nginx (Caddy optional)
• docs/DATABASE-SETUP.md - Database setup, schema, and admin API
• docs/TUNNEL-SERVER.md - Tunnel server setup (required for mobile app connectivity)

API Documentation

• docs/mobile-api/README.md - Mobile API overview and OAuth authentication
• docs/mobile-api/OAUTH.md - OAuth 2.0 authentication flow (primary method)
• docs/mobile-api/TUNNEL.md - Tunnel management (OAuth-authenticated)
• docs/mobile-api/PROFILE.md - Profile caching for ActivityPub
• docs/mobile-api/IMAGES.md - Avatar and header image upload
• docs/WEBSOCKET-API.md - WebSocket real-time events API
• docs/USER-API.md - User account management API
• docs/API-KEYS.md - API keys for automation and scripts

Admin Documentation

• docs/ADMIN-ROLES.md - Admin roles, permissions, and team management

Development

Project Structure

src/
├── config.ts # Environment configuration
├── index.ts # Application entry point
├── server.ts # Express app setup
├── tunnel-server.ts # Tunnel server for mobile app connectivity
│
├── database/ # Database layer
│ ├── db.ts # PostgreSQL connection & pool
│ ├── schema.sql # Complete database schema
│ └── run-migration.ts # Migration runner
│
├── middleware/ # Express middleware (10+ files)
│ ├── auth.ts # Authentication middleware
│ ├── rateLimit.ts # Rate limiting
│ ├── jwtAuth.ts # JWT validation
│ └── ... # CSRF, permissions, metrics, etc.
│
├── routes/ # API endpoints (23 files)
│ ├── activitypub.ts # ActivityPub proxy
│ ├── admin.ts # Admin dashboard
│ ├── auth.ts # User authentication
│ ├── oauth.ts # OAuth 2.0 flow
│ ├── mobile.ts # Mobile client API
│ ├── tunnel.ts # Tunnel management
│ └── ... # 2FA, API keys, reports, etc.
│
├── services/ # Business logic (27 files)
│ ├── UserRegistryDB.ts # User & session management
│ ├── ProxyService.ts # ActivityPub request proxying
│ ├── OAuthService.ts # OAuth token management
│ ├── EmailService.ts # Email notifications
│ ├── MetricsService.ts # Prometheus metrics
│ └── ... # Image storage, caching, 2FA, etc.
│
├── utils/ # Helper utilities
│ ├── crypto.ts # Password hashing & tokens
│ ├── validators.ts # Input validation
│ ├── i18n.ts # Internationalization
│ └── ... # Template engine, API errors, etc.
│
├── types/ # TypeScript type definitions
├── views/ # Handlebars templates (admin UI, auth pages)
└── public/ # Static assets (CSS, images, JS)

Scripts

• npm run dev - Development with hot reload
• npm run build - Build TypeScript
• npm start - Start production server
• npm run lint - Lint code
• npm run format - Format code

License

AGPL-3.0