Configuration Guide

This document provides comprehensive configuration information for operators deploying the Helium project. The system uses a combination of environment variables for server configuration and JSON configurations stored in the database for module-specific settings.

Table of Contents

• Environment Variables
• Module Configurations
• Infrastructure Dependencies
• Configuration Templates

Environment Variables

The Helium server is configured entirely through environment variables. These control the server behavior and connectivity to external services.

Required Environment Variables

All worker modes require these variables:

# Worker mode selection (REQUIRED)
WORK_MODE="grpc"  # Options: grpc, subscribe_api, webhook_api, consumer, mailer, cron_executor

# Database connection (REQUIRED)
DATABASE_URL="postgres://user:password@localhost:5432/helium_db"

# Redis connection (REQUIRED)
REDIS_URL="redis://localhost:6379"

# RabbitMQ connection (REQUIRED)
MQ_URL="amqp://user:password@localhost:5672/"

Worker Mode Options

Optional Environment Variables

# Server listen addresses (for API workers)
LISTEN_ADDR="0.0.0.0:50051"  # Default for grpc mode
LISTEN_ADDR="0.0.0.0:8080"   # Default for subscribe_api mode
LISTEN_ADDR="0.0.0.0:8081"   # Default for webhook_api mode

# Cron executor configuration
SCAN_INTERVAL="60"  # Scan interval in seconds (cron_executor mode only)

# Logging configuration
RUST_LOG="info"  # Options: error, warn, info, debug, trace

Module Configurations

Module configurations are stored as JSON in the PostgreSQL database in the application__config table. Each module has its own configuration key and JSON structure.

Note: All duration values are represented as strings containing the number of seconds (e.g., "300" for 5 minutes, "1800" for 30 minutes).

Auth Module (auth)

Key: "auth"

The authentication module handles user registration, login, JWT tokens, and OAuth providers.

{
  "email_provider": {
    "register_domain": {
      "enable_white_list": false,
      "white_list": [],
      "enable_black_list": false,
      "black_list": []
    },
    "otp_expire_after": "300",
    "delete_otp_before": "7200",
    "magic_link_expire_after": "1800",
    "magic_link_delete_before": "14400",
    "resend_interval": "30"
  },
  "jwt": {
    "secret": "your-jwt-secret-key-32-characters-long",
    "refresh_token_expiration": "2592000",
    "access_token_expiration": "900",
    "issuer": "https://your-domain.com",
    "access_audience": "helium_cloud",
    "refresh_audience": "helium_cloud_auth"
  },
  "oauth_providers": {
    "providers": [
      {
        "name": "Google",
        "client_id": "your-google-client-id",
        "client_secret": "your-google-client-secret",
        "redirect_uri": "https://your-domain.com/auth/oauth/google/callback"
      },
      {
        "name": "GitHub",
        "client_id": "your-github-client-id",
        "client_secret": "your-github-client-secret",
        "redirect_uri": "https://your-domain.com/auth/oauth/github/callback"
      }
    ],
    "challenge_expiration": "300"
  },
  "default_user_group": 1
}

Configuration Details:

• email_provider.register_domain: Controls which email domains are allowed for registration
• email_provider.otp_expire_after: How long OTP codes remain valid (in seconds, default: “300” = 5 minutes)
• email_provider.resend_interval: Minimum time between resend attempts (in seconds, default: “30” = 30 seconds)
• jwt.secret: CRITICAL: Must be a secure random string for production
• jwt.*_expiration: Token lifetime settings (in seconds, default: “2592000” = 30 days for refresh, “900” = 15 minutes for access)
• oauth_providers.providers: List of OAuth providers with their credentials
• default_user_group: Default group ID assigned to new users

Telecom Module (telecom)

Key: "telecom"

The telecom module manages VPN nodes, subscription links, and proxy synchronization.

{
  "node_health_check": {
    "offline_timeout": "600"
  },
  "subscribe_link": {
    "endpoints": [
      {
        "url_template": "https://subscribe.your-domain.com/subscribe/{SUBSCRIBE_TOKEN}",
        "endpoint_name": "primary"
      },
      {
        "url_template": "https://backup.your-domain.com/subscribe/{SUBSCRIBE_TOKEN}",
        "endpoint_name": "backup"
      }
    ]
  },
  "uni_proxy_sync": {
    "push_interval": "30",
    "pull_interval": "60"
  },
  "vpn_server_token": "secure-random-token-for-vpn-servers"
}

Configuration Details:

• node_health_check.offline_timeout: Time before marking nodes as offline (in seconds, default: “600” = 10 minutes)
• subscribe_link.endpoints: List of subscription endpoints for client configuration
• uni_proxy_sync.push_interval: How often to push traffic data (in seconds, default: “30” = 30 seconds)
• uni_proxy_sync.pull_interval: How often to pull user info (in seconds, default: “60” = 1 minute)
• vpn_server_token: CRITICAL: Secure token for VPN server authentication

Shop Module (shop)

Key: "shop"

The shop module handles e-commerce functionality, orders, and payment processing.

{
  "max_unpaid_orders": 5,
  "auto_cancel_after": "1800",
  "epay_notify_url": "https://your-domain.com/api/webhook/epay/notify",
  "epay_return_url": "https://your-domain.com/payment/success"
}

Configuration Details:

• max_unpaid_orders: Maximum unpaid orders per user (default: 5)
• auto_cancel_after: Time before auto-canceling unpaid orders (in seconds, default: “1800” = 30 minutes)
• epay_notify_url: REQUIRED: Server-to-server notification endpoint for payment providers
• epay_return_url: REQUIRED: User return URL after payment completion

Mailer Module (mailer)

Key: "mailer"

The mailer module handles email delivery through SMTP.

{
  "host": "smtp.gmail.com",
  "port": 587,
  "username": "your-smtp-username",
  "password": "your-smtp-password",
  "sender": "noreply@your-domain.com",
  "starttls": true
}

Configuration Details:

• host: SMTP server hostname
• port: SMTP server port (typically 587 for STARTTLS, 465 for SSL)
• username/password: SMTP authentication credentials
• sender: Email address used as sender
• starttls: Enable STARTTLS encryption (recommended: true)

Admin Management Module (admin-jwt)

Key: "admin-jwt"

Controls JWT tokens for administrative access.

{
  "secret": "admin-jwt-secret-key-32-characters-long",
  "token_expiration": "864000",
  "issuer": "https://admin.your-domain.com",
  "audience": "HeliumAdmin"
}

Configuration Details:

• secret: CRITICAL: Secure secret for admin JWT signing
• token_expiration: Admin token lifetime (in seconds, default: “864000” = 10 days)
• issuer: JWT issuer for admin tokens
• audience: JWT audience for admin tokens

Market Module (affiliate)

Key: "affiliate"

Controls the affiliate marketing system.

{
  "max_invite_code_per_user": 10,
  "default_reward_rate": "0.1",
  "default_trigger_time_per_user": 3
}

Configuration Details:

• max_invite_code_per_user: Maximum invite codes per user (default: 10)
• default_reward_rate: Default affiliate commission rate (default: 10%)
• default_trigger_time_per_user: Required referrals before earning (default: 3)

Infrastructure Dependencies

PostgreSQL Database

Required Version: PostgreSQL 12+

Configuration:

• Environment variable: DATABASE_URL
• Format: postgres://user:password@host:port/database

Important Notes:

• ⚠️ CRITICAL: Run migrations before starting: sqlx migrate run --database-url $DATABASE_URL
• Use external managed PostgreSQL service for production (AWS RDS, Google Cloud SQL, etc.)
• Ensure proper backup and high availability configuration

Redis

Required Version: Redis 6+

Configuration:

• Environment variable: REDIS_URL
• Format: redis://host:port or redis://user:password@host:port

Usage:

• Session storage and authentication tokens
• Module configuration caching
• Temporary data (OAuth challenges, OTP codes)

RabbitMQ (AMQP)

Configuration:

• Environment variable: MQ_URL
• Format: amqp://user:password@host:port/

Usage:

• Asynchronous task processing
• Email sending queue
• Inter-module communication

Configuration Templates

Development Environment

# .env file for development
WORK_MODE=grpc
DATABASE_URL=postgres://helium:password@localhost:5432/helium_dev
REDIS_URL=redis://localhost:6379
MQ_URL=amqp://guest:guest@localhost:5672/
LISTEN_ADDR=0.0.0.0:50051
RUST_LOG=debug

Production Environment

# Production environment variables
WORK_MODE=grpc
DATABASE_URL=postgres://helium_user:secure_password@db.example.com:5432/helium_prod
REDIS_URL=redis://redis.example.com:6379
MQ_URL=amqp://helium_user:secure_password@mq.example.com:5672/
LISTEN_ADDR=0.0.0.0:50051
RUST_LOG=info

Multi-Worker Deployment

For production, run multiple worker processes:

# API Server (can be scaled horizontally)
WORK_MODE=grpc ./helium-server &

# Background Tasks (can be scaled)
WORK_MODE=consumer ./helium-server &

# Email Processing (single instance recommended)
WORK_MODE=mailer ./helium-server &

# Scheduled Tasks (MUST be single instance)
WORK_MODE=cron_executor ./helium-server &

Configuration Management

To update module configurations:

1. Via Database: Insert/update records in the application__config table
2. Via Admin API: Use the management gRPC API to update configurations
3. Configuration Sync: The system automatically syncs configurations from PostgreSQL to Redis cache

Example SQL for updating auth configuration:

INSERT INTO application__config (key, content)
VALUES ('auth', '{"jwt": {"secret": "new-secret"}, ...}')
ON CONFLICT (key) DO UPDATE SET
  content = EXCLUDED.content,
  updated_at = NOW();

Security Considerations

⚠️ Critical Configuration Security:

1. JWT Secrets: Use cryptographically secure random strings (32+ characters)
2. VPN Server Token: Generate secure random tokens for server authentication
3. Database Credentials: Use strong passwords and restrict database access
4. SMTP Credentials: Use application-specific passwords, not primary account passwords
5. OAuth Secrets: Keep OAuth client secrets secure and rotate them regularly

Troubleshooting

Common Configuration Issues

1. Database Connection: Verify PostgreSQL accessibility and credentials
2. Redis Connection: Check Redis server status and network connectivity
3. RabbitMQ Connection: Ensure RabbitMQ server is running and accessible
4. Email Delivery: Test SMTP configuration with your email provider
5. OAuth Issues: Verify client IDs, secrets, and redirect URIs match provider settings

Validation Commands

# Test database connection
sqlx migrate info --database-url $DATABASE_URL

# Test Redis connection
redis-cli -u $REDIS_URL ping

# Test RabbitMQ connection
rabbitmqctl status  # on RabbitMQ server