External Dependencies

The Helium system requires several external services to function properly. The Helium application itself runs in Docker containers, but the core infrastructure dependencies (PostgreSQL, Redis, RabbitMQ) should be provisioned as external managed services for production deployments.

While some dependencies are core infrastructure requirements, others are module-specific and may be optional depending on your deployment configuration.

Core Infrastructure Dependencies

These dependencies are required for all Helium deployments:

1. PostgreSQL Database

Purpose: Primary data store for all application data Version: PostgreSQL 12+ recommended Configuration:

• Environment variable: DATABASE_URL
• Format: postgres://user:password@host:port/database
• Example: postgres://helium:password@localhost:5432/helium_db

Database Schema:

• ⚠️ CRITICAL: SQLx migrations must be run before starting the application
• All database schema changes are managed through SQLx migrations in the /migrations directory
• Use sqlx migrate run --database-url $DATABASE_URL to apply migrations

External Service Requirements:

• NOT containerized - PostgreSQL should run as an external managed service
• Recommended: Use cloud-managed PostgreSQL (AWS RDS, Google Cloud SQL, Azure Database, etc.)
• Alternative: Dedicated PostgreSQL server with proper backup and high availability setup

2. Redis

Purpose: Caching, session storage, and configuration store Version: Redis 6+ recommended Configuration:

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

Usage:

• Session management and authentication tokens
• Configuration caching across modules
• Temporary data storage (OAuth challenges, etc.)

External Service Requirements:

• NOT containerized - Redis should run as an external managed service
• Recommended: Use cloud-managed Redis (AWS ElastiCache, Google Memorystore, Azure Cache, etc.)
• Alternative: Dedicated Redis server with persistence and clustering for production

3. RabbitMQ

Purpose: Message queue for asynchronous processing between modules Version: RabbitMQ 3.8+ recommended Configuration:

• Environment variable: MQ_URL
• Format: amqp://user:password@host:port/
• Example: amqp://helium:password@localhost:5672/

Usage:

• Inter-module communication
• Background job processing
• Event-driven architecture support

External Service Requirements:

• NOT containerized - RabbitMQ should run as an external managed service
• Recommended: Use cloud-managed message queues (AWS MQ, Google Cloud Pub/Sub, Azure Service Bus)
• Alternative: Dedicated RabbitMQ cluster with proper clustering and high availability

Module-Specific Dependencies

These dependencies are required only when using specific modules:

Auth Module - OAuth Providers (Optional)

Purpose: Social authentication (Google, Microsoft, GitHub, Discord) Required: Only if OAuth authentication is enabled Configuration: Stored in database/Redis configuration

Supported Providers:

• Google OAuth 2.0
• Microsoft Azure AD
• GitHub OAuth
• Discord OAuth

Setup Requirements:

1. Create OAuth applications with each provider
2. Configure redirect URIs to your Helium deployment
3. Store client ID and secret in the system configuration
4. Configure OAuth provider settings via the management interface

Configuration Structure:

{
  "auth": {
    "oauth_providers": {
      "providers": [
        {
          "name": "google",
          "client_id": "your-client-id",
          "client_secret": "your-client-secret",
          "redirect_uri": "https://your-domain.com/auth/oauth/callback"
        }
      ],
      "challenge_expiration": "5m"
    }
  }
}

Mailer Module - SMTP Server (Required for Email)

Purpose: Email delivery for user notifications, verification, etc. Required: When email functionality is needed Configuration: Stored in database/Redis configuration

SMTP Configuration:

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

Supported SMTP Features:

• STARTTLS encryption
• Plain authentication
• Custom sender addresses
• HTML email templates

Common SMTP Providers:

• Gmail: smtp.gmail.com:587 (requires app passwords)
• Outlook/Hotmail: smtp-mail.outlook.com:587
• SendGrid: smtp.sendgrid.net:587
• Mailgun: smtp.mailgun.org:587
• Amazon SES: email-smtp.region.amazonaws.com:587

Shop Module - Epay Payment Provider (Required for Payments)

Purpose: Payment processing for e-commerce functionality Required: When payment processing is needed Configuration: Stored in database as epay provider credentials

Epay Provider Setup:

1. Register with an Epay-compatible payment provider
2. Obtain merchant credentials (PID, Key, Merchant URL)
3. Configure webhook endpoints for payment notifications
4. Add provider credentials via the management interface

Supported Payment Methods:

• Alipay (alipay)
• WeChat Pay (wxpay)
• USDT cryptocurrency (usdt)

Configuration Requirements:

{
  "shop": {
    "epay_notify_url": "https://your-domain.com/api/shop/epay/callback",
    "epay_return_url": "https://your-domain.com/payment/success",
    "max_unpaid_orders": 5,
    "auto_cancel_after": "30m"
  }
}

Epay Provider Database Entry:

INSERT INTO epay_provider_credentials (
  display_name,
  enabled_channels,
  key,
  pid,
  merchant_url
) VALUES (
  'My Payment Provider',
  ['alipay', 'wxpay'],
  'your-merchant-key',
  1234,
  'https://pay.provider.com/submit.php'
);

Development Dependencies

These are required for building and developing the project:

Protocol Buffers Compiler

Purpose: Compiling .proto files for gRPC services Installation:

• Ubuntu/Debian: apt-get install protobuf-compiler
• macOS: brew install protobuf
• Already included in Docker build process

SQLx CLI

Purpose: Database migration management Installation: cargo install sqlx-cli --no-default-features --features postgres Usage:

• Apply migrations: sqlx migrate run
• Create new migration: sqlx migrate add <name>

Docker/Kubernetes Deployment Considerations

What Should Be Containerized

✅ Containerize:

• Helium server application (helium-server)
• Application-specific components and workers

❌ Do NOT Containerize:

• PostgreSQL - Use external managed database services
• Redis - Use external managed cache services
• RabbitMQ - Use external managed message queue services

Infrastructure Handled by Platform

When deploying with Docker and Kubernetes, these infrastructure concerns are handled by the orchestration platform:

• Load Balancers: Kubernetes ingress controllers handle load balancing
• TLS Certificates: cert-manager or similar tools handle SSL/TLS
• Service Discovery: Kubernetes DNS handles service discovery
• Health Checks: Kubernetes probes handle application health monitoring
• Logging: Container runtime and logging drivers handle log aggregation

Recommended Managed Services by Cloud Provider

AWS:

• PostgreSQL: Amazon RDS for PostgreSQL
• Redis: Amazon ElastiCache for Redis
• RabbitMQ: Amazon MQ for RabbitMQ

Google Cloud:

• PostgreSQL: Cloud SQL for PostgreSQL
• Redis: Memorystore for Redis
• RabbitMQ: Cloud Pub/Sub (alternative) or third-party RabbitMQ

Azure:

• PostgreSQL: Azure Database for PostgreSQL
• Redis: Azure Cache for Redis
• RabbitMQ: Azure Service Bus (alternative) or third-party RabbitMQ

Environment Variables for Containers

apiVersion: apps/v1
kind: Deployment
metadata:
  name: helium-server
spec:
  template:
    spec:
      containers:
        - name: helium-server
          image: helium-server:latest
          env:
            - name: WORK_MODE
              value: "grpc"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: helium-secrets
                  key: database-url
            - name: REDIS_URL
              valueFrom:
                secretKeyRef:
                  name: helium-secrets
                  key: redis-url
            - name: MQ_URL
              valueFrom:
                secretKeyRef:
                  name: helium-secrets
                  key: rabbitmq-url

Security Considerations

Credentials Management

1. Never store credentials in plain text
2. Use Kubernetes secrets or similar secure storage
3. Rotate credentials regularly
4. Use dedicated service accounts with minimal permissions

Network Security

1. Database: Restrict access to application subnets only
2. Redis: Enable authentication and restrict network access
3. RabbitMQ: Use strong passwords and enable TLS
4. SMTP: Use app passwords or OAuth tokens when available

OAuth Security

1. Use HTTPS for all OAuth redirect URIs
2. Validate redirect URI domains strictly
3. Use state parameter for CSRF protection (handled automatically)

Troubleshooting

Database Connection Issues

# Test database connectivity
psql $DATABASE_URL -c "SELECT version();"

# Check migration status
sqlx migrate info --database-url $DATABASE_URL

Redis Connection Issues

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

# Check Redis memory usage
redis-cli -u $REDIS_URL info memory

RabbitMQ Connection Issues

# Check queue status
rabbitmqctl list_queues

# Check connection status
rabbitmqctl list_connections

SMTP Testing

The mailer module provides test endpoints and logging to help diagnose SMTP issues. Check application logs for detailed SMTP connection and authentication errors.

Epay Integration Issues

1. Verify webhook URLs are accessible from the internet
2. Check payment provider’s callback logs
3. Ensure merchant credentials are correctly configured
4. Validate signature verification in callback processing

Optional Observability Stack

OpenTelemetry & Grafana Stack (Optional)

Purpose: Comprehensive observability with distributed tracing, metrics, and log aggregation Required: No - completely optional enhancement Configuration: OTEL_COLLECTOR environment variable

Components:

• OpenTelemetry Collector: Telemetry data collection and routing
• Grafana Tempo: Distributed tracing backend
• Prometheus: Metrics storage and querying
• Grafana Loki: Log aggregation
• Grafana: Unified visualization dashboard

When to Use:

• Production deployments requiring detailed performance analysis
• Multi-instance deployments needing distributed tracing
• Teams requiring centralized observability dashboards
• Troubleshooting complex performance issues

Deployment:

• NOT containerized with application - Deploy as separate Kubernetes workloads or use Grafana Cloud
• Recommended: Deploy Grafana stack in dedicated observability namespace
• Alternative: Use managed services (Grafana Cloud, Datadog, New Relic)

Note: Helium automatically falls back to basic structured logging if OpenTelemetry is not configured. See the comprehensive Observability with OpenTelemetry guide for full setup instructions.

Summary

Next Steps: After setting up these dependencies, proceed to the Helium Server Deployment Guide for detailed deployment instructions.