Docker Deployment

Docker Deployment Overview

Docker deployment is the recommended approach for running ApiCharge in production environments. It provides consistent operation across different platforms, simplified management, and scalability options.

Key Features of Docker Deployment

• Simplified Installation - All dependencies bundled in a single container
• Consistent Environment - Same behavior across development, testing, and production
• Scalability - Easy to deploy multiple instances for high availability
• Integrated Services - Includes embedded Stellar RPC server and Redis support
• Volume Persistence - Stateful data stored in Docker volumes
• Network Isolation - Enhanced security through container networking

Deployment Options

ApiCharge Docker images support two primary deployment scenarios:

1. Single Container with Embedded Services

The simplest deployment option includes everything needed to run ApiCharge in a single container:

• ApiCharge service
• Embedded Stellar RPC server
• Embedded Redis instance for rate limiter persistence

This approach is ideal for:

• Development and testing environments
• Small-scale production deployments
• Simple deployment scenarios where high availability is not required

2. Clustered Deployment with External Services

For larger-scale production deployments, you can run multiple ApiCharge containers that share external dependencies:

• Multiple ApiCharge service containers for load balancing
• Shared external Redis instance for distributed state
• Shared or dedicated Stellar RPC servers

This approach is recommended for:

• High-traffic production environments
• Deployments requiring high availability
• Scaling to handle large numbers of concurrent requests

For detailed information on clustering, see the Clustering documentation.

Network Configuration

ApiCharge Docker images are available for both Stellar Testnet and Mainnet configurations:

• Testnet - For development and testing (apicharge-stellar-rpc:testnet)
• Mainnet - For production use (apicharge-stellar-rpc:mainnet)

The images are pre-configured with appropriate network settings, but you'll need to provide your own Stellar account credentials via environment variables.

Basic Deployment with Docker Compose

The recommended way to deploy ApiCharge is using Docker Compose. Here's a basic example of a docker-compose.yml file:

version: '3.8'

services:
  apicharge-stellar-rpc:
    image: apicharge-stellar-rpc:testnet  # or :mainnet for production
    container_name: apicharge-stellar-rpc
    ports:
      - "8080:80"   # HTTP
      - "8443:443"  # HTTPS
    volumes:
      - ./certs:/certs:ro                        # SSL certificates
      - apicharge-redis-data:/data/redis         # Redis data
      - soroban-data:/var/lib/stellar            # Stellar blockchain data
    env_file:
      - ./.env                                   # Environment variables
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
    restart: unless-stopped
    networks:
      - apicharge-network

networks:
  apicharge-network:
    driver: bridge

volumes:
  apicharge-redis-data:
  soroban-data:

Environment Configuration

ApiCharge requires several environment variables to be set. Create a .env file with the following variables:

# Required Stellar account credentials
APICHARGE_SIGNING_KEY=SDH3X...YOUR_STELLAR_SECRET_KEY
APICHARGE_NETWORK_PASSPHRASE=Test SDF Network ; September 2015  # for testnet

# Optional configuration
APICHARGE_USE_EMBEDDED_REDIS=true  # Set to false if using external Redis
ASPNETCORE_URLS=http://+:80;https://+:443

Volume Persistence

ApiCharge uses Docker volumes to persist data across container restarts:

• Redis Data - Stores rate limiter state and other cached data
• Stellar RPC Data - Stores blockchain data for the Stellar RPC server
• Certificates - SSL/TLS certificates for HTTPS connections

These volumes ensure that your data is preserved even if the container is stopped or restarted.

Customizing Configuration

You can override the default configuration by mounting your own appsettings.json file:

volumes:
  - ./appsettings.json:/app/appsettings.json:ro  # Custom configuration

This allows you to customize routes, rate limiters, and other settings without rebuilding the Docker image.

Clustered Deployment Example

For production environments with multiple ApiCharge instances, use a configuration like this:

version: '3.8'

services:
  apicharge1:
    image: apicharge-stellar-rpc:mainnet
    container_name: apicharge1
    ports:
      - "8080:80"
      - "8443:443"
    volumes:
      - ./certs:/certs:ro
      - soroban-data1:/var/lib/stellar
    env_file:
      - ./.env
    environment:
      - APICHARGE_USE_EMBEDDED_REDIS=false
      - ASPNETCORE_ENVIRONMENT=Production
    restart: unless-stopped
    networks:
      - apicharge-network
    depends_on:
      - redis

  apicharge2:
    image: apicharge-stellar-rpc:mainnet
    container_name: apicharge2
    ports:
      - "8081:80"
      - "8444:443"
    volumes:
      - ./certs:/certs:ro
      - soroban-data2:/var/lib/stellar
    env_file:
      - ./.env
    environment:
      - APICHARGE_USE_EMBEDDED_REDIS=false
      - ASPNETCORE_ENVIRONMENT=Production
    restart: unless-stopped
    networks:
      - apicharge-network
    depends_on:
      - redis

  redis:
    image: redis:latest
    container_name: apicharge-redis
    command: redis-server --appendonly yes --maxmemory 1gb --maxmemory-policy allkeys-lru
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped
    networks:
      - apicharge-network

networks:
  apicharge-network:
    driver: bridge

volumes:
  soroban-data1:
  soroban-data2:
  redis-data:

In this configuration:

• Multiple ApiCharge instances run in separate containers
• Each instance has its own Stellar RPC server data
• All instances share a common Redis server for state synchronization
• Different HTTP/HTTPS ports are exposed for each instance

You would typically place a load balancer in front of these instances to distribute traffic.

Monitoring and Logging

Docker deployment makes it easy to collect logs and monitor the service:

• View logs with docker logs apicharge-stellar-rpc
• Monitor container health with docker stats
• Integrate with Docker-compatible monitoring solutions like Prometheus

For more information on logging configuration, see the Logging documentation.

Upgrading

To upgrade to a newer version of ApiCharge:

1. Pull the latest Docker image (requires Early Access credentials)
2. Stop the running container with docker-compose down
3. Start the new container with docker-compose up -d

Your data will be preserved in the Docker volumes, allowing for seamless upgrades.

Next Steps

To learn more about deploying ApiCharge:

• Clustering - Detailed information on running multiple ApiCharge instances
• Configuration - How to configure ApiCharge for your specific needs
• Routes - Setting up API routes for monetization