Deployment Options Overview
ApiCharge can be deployed in several different ways, depending on your needs, scale, and infrastructure requirements. This page provides an overview of the available deployment options and helps you choose the right approach for your use case.
Deployment Overview
ApiCharge offers three primary deployment models:
Docker Container Deployment
Recommended for: Most deployments, from development to production
Deploy ApiCharge as a Docker container with all dependencies included. This is the simplest and most consistent deployment method.
Standalone Deployment
Recommended for: Custom environments, specific OS integration
Deploy ApiCharge as a standalone application on a server or virtual machine. This gives you more control over the environment but requires more setup.
Clustered Deployment
Recommended for: High availability, scaling, production workloads
Deploy multiple ApiCharge instances with shared state for high availability and horizontal scaling. This is the most complex but also the most robust deployment model.
System Requirements
ApiCharge has the following general system requirements:
| Component | Minimum Requirements | Recommended |
|---|---|---|
| CPU | 2 cores | 4+ cores |
| Memory | 2 GB RAM | 4+ GB RAM |
| Disk | 5 GB | 20+ GB SSD |
| Network | 10 Mbps | 100+ Mbps |
| Operating System | Linux, Windows, or macOS with Docker support | Linux (Ubuntu 20.04+, Debian 11+) |
Stellar Blockchain Integration Architecture
A key component of ApiCharge is its integration with the Stellar blockchain for secure, low-cost micropayments. This section explains the architecture of this integration.
Blockchain Architecture Overview
ApiCharge uses the Stellar blockchain as its payment rail, leveraging Soroban smart contracts for secure susbcription management. The architecture consists of several components:
+----------------+ +------------------+ +----------------+
| | | | | |
| Client |<------->| ApiCharge |<------->| Your Backend |
| Application | | Service | | Services |
| | | | | |
+----------------+ +--+------------+--+ +----------------+
| |
| |
+--------v--+ +--v------------+
| | | |
| Soroban |<---->| Stellar |
| RPC | | Network |
| Server | | |
+-----------+ +---------------+Key Components
- ApiCharge Service - Core application that handles API proxying, rate limiting, and payment verification
- Soroban RPC Server - Interface between ApiCharge and the Stellar blockchain, handling transaction submission and verification
- Stellar Network - The blockchain network that processes the micropayments
- ApiCharge Smart Contract - Soroban smart contract deployed on the Stellar network that handles payment validation
How ApiCharge Communicates with Stellar
The communication flow between ApiCharge and the Stellar blockchain involves these steps:
- Quote Generation - ApiCharge generates and cryptographically signs quotes for ApiCharge Subscriptions
-
Payment Verification - When a client makes a payment, ApiCharge verifies it by:
- Querying the Soroban RPC server for transaction details
- Verifying the transaction has been included in the Stellar ledger
- Confirming payment amount and destination
- Access Token Issuance - After payment verification, ApiCharge generates a cryptographically signed access token
- Ongoing Validation - For each request using the token, ApiCharge validates its signature and checks rate limiter state
+--------+ +------------+ +-----------+ +-------------+
| Client | | ApiCharge | | Soroban | | Stellar |
| | | | | RPC Server| | Network |
+---+----+ +-----+------+ +-----+-----+ +------+-----+
| | | |
| 1. Request Quote | | |
+--------------------------->+ | |
| | | |
| 2. Return Signed Quote | | |
|<---------------------------+ | |
| | | |
| 3. Make Payment | | |
+--------------------------------------------------------->+------------------------->+
| | | |
| 4. Request Access Token | | |
+--------------------------->+ | |
| | | |
| | 5. Verify Payment | |
| +--------------------------->+ |
| | | |
| | 6. Payment Confirmed | |
| |<---------------------------+ |
| | | |
| 7. Return Access Token | | |
|<---------------------------+ | |
| | | |
| 8. API Requests with Token | | |
+--------------------------->+ | |
| | | |
| 9. API Responses | | |
|<---------------------------+ | |Smart Contract Integration
ApiCharge integrates with a Stellar Soroban smart contract that handles:
- Validation of payment transactions
- Verification of quote authenticity
- Recording of subscription purchases
- Management of payment splits for service providers
Different contract instances are deployed on the Stellar Testnet and Mainnet. The appropriate contract is used automatically based on the UseNetwork configuration setting.
Network Options
ApiCharge can connect to different Stellar networks:
| Network | Description | Use Case |
|---|---|---|
| Testnet | Stellar's test network with test tokens | Development, testing, integration |
| Mainnet | Stellar's production network with real assets | Production deployments |
Deployment Considerations
When deploying ApiCharge with Stellar integration, consider these factors:
1. Wallet Management
ApiCharge requires a Stellar account (wallet) to sign quotes and verify payments. The private key must be securely stored and provided via environment variables.
2. RPC Server Resources
The Soroban RPC server requires sufficient resources to maintain blockchain state and process transactions:
- Disk space for blockchain data (starts at ~5GB, grows over time)
- Memory for processing (minimum 2GB recommended)
- Network bandwidth for blockchain synchronization
3. Network Connectivity
ApiCharge needs reliable network connectivity to the Stellar network. In production environments, consider:
- Redundant network connections
- Load balancing across multiple RPC servers
- Monitoring and alerting for network issues
4. Security Considerations
Protect your Stellar integration with these security measures:
- Store signing keys securely (use environment variables or secret management services)
- Use TLS for all RPC communications
- Implement proper access controls for RPC server administration
- Regularly audit and rotate keys
Deployment Scenarios
Here are some common deployment scenarios and recommended approaches:
Development Environment
- Recommended: Docker container with Testnet configuration
- Settings: Debug logging, development signing keys, self-signed certificates
- Network: Stellar Testnet
- Data: In-container storage (not persistent)
Testing/Staging Environment
- Recommended: Docker container or standalone with persistence
- Settings: Production-like configuration with test accounts
- Network: Stellar Testnet
- Data: Persistent volume for Redis and RPC server data
Small Production Environment
- Recommended: Docker container with volume mounts
- Settings: Production configuration, proper certificates
- Network: Stellar Mainnet
- Data: Persistent volumes, regular backups
- Monitoring: Basic health checks and alerts
Large Production Environment
- Recommended: Clustered deployment with load balancing
- Settings: Production configuration, proper certificates
- Network: Stellar Mainnet
- Data: Redis Cluster, dedicated RPC server cluster
- Monitoring: Comprehensive monitoring, alerting, and logging
- Redundancy: Multi-zone or multi-region deployment
Next Steps
Based on your deployment needs, explore these detailed guides:
- Docker Deployment - How to deploy ApiCharge using Docker
- Standalone Deployment - Running ApiCharge directly on a server
- Clustered Deployment - Setting up ApiCharge for high availability and scaling