Self-Hosting CroissantPay in Production (coming soon) | CroissantPay Blog

> Note: Self-hosting is coming soon. This guide will be fully applicable when we launch. For now, use CroissantPay Cloud.

Running CroissantPay on your own infrastructure gives you complete control over your data and removes any usage-based pricing. This guide covers everything you need to know to deploy CroissantPay in production.

Prerequisites

Before starting, you'll need:

Docker and Docker Compose (or Kubernetes)
PostgreSQL 14+ database
Redis for caching (optional but recommended)
A domain with SSL certificate

Quick Start with Docker Compose

The fastest way to get started:

# Clone the repository
git clone https://github.com/croissantpay/croissantpay.git
cd croissantpay

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your configuration

# Start the services
docker compose up -d

Your .env file should include:

# Database
DATABASE_URL=postgresql://user:password@db:5432/croissantpay

# Redis (optional)
REDIS_URL=redis://redis:6379

# Authentication
BETTER_AUTH_SECRET=your-secret-key-here

# App Store Connect (for iOS)
APPLE_ISSUER_ID=xxx
APPLE_KEY_ID=xxx
APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----..."

# Google Play (for Android)
GOOGLE_SERVICE_ACCOUNT_KEY='{"type": "service_account", ...}'

Production Architecture

For production, we recommend:

                    ┌─────────────┐
                    │   Load      │
                    │   Balancer  │
                    └─────┬───────┘
                          │
            ┌─────────────┼─────────────┐
            │             │             │
      ┌─────▼─────┐ ┌─────▼─────┐ ┌─────▼─────┐
      │  App (1)  │ │  App (2)  │ │  App (3)  │
      └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
            │             │             │
            └─────────────┼─────────────┘
                          │
            ┌─────────────┼─────────────┐
            │             │             │
      ┌─────▼─────┐ ┌─────▼─────┐       │
      │ PostgreSQL│ │   Redis   │       │
      │  Primary  │ │  Cluster  │       │
      └───────────┘ └───────────┘       │

Kubernetes Deployment

For Kubernetes, use our Helm chart:

# Add the CroissantPay Helm repository
helm repo add croissantpay https://charts.croissantlabs.com
helm repo update

# Install CroissantPay
helm install croissantpay croissantpay/croissantpay \
  --namespace croissantpay \
  --create-namespace \
  --set database.url="postgresql://..." \
  --set replicas=3

Example values.yaml:

replicas: 3

image:
  repository: croissantpay/croissantpay
  tag: latest

resources:
  requests:
    memory: "256Mi"
    cpu: "100m"
  limits:
    memory: "512Mi"
    cpu: "500m"

database:
  url: postgresql://user:pass@postgres:5432/croissantpay

redis:
  enabled: true
  url: redis://redis:6379

ingress:
  enabled: true
  hostname: api.yourapp.com
  tls: true

Database Setup

PostgreSQL Configuration

For production PostgreSQL:

-- Recommended settings
ALTER SYSTEM SET shared_buffers = '256MB';
ALTER SYSTEM SET effective_cache_size = '768MB';
ALTER SYSTEM SET maintenance_work_mem = '64MB';
ALTER SYSTEM SET checkpoint_completion_target = 0.7;
ALTER SYSTEM SET wal_buffers = '16MB';
ALTER SYSTEM SET default_statistics_target = 100;

Migrations

Run database migrations:

# Using Docker
docker exec -it croissantpay npx drizzle-kit migrate

# Or directly
pnpm db:migrate

Monitoring & Observability

Health Checks

CroissantPay exposes health endpoints:

# Liveness probe
curl http://localhost:3000/api/health

# Readiness probe  
curl http://localhost:3000/api/health/ready

Metrics

Enable Prometheus metrics:

METRICS_ENABLED=true
METRICS_PORT=9090

Logging

Configure structured logging:

LOG_LEVEL=info
LOG_FORMAT=json

Security Best Practices

Use secrets management - Never commit secrets to git
Enable SSL/TLS - Always use HTTPS in production
Set up firewalls - Restrict database access
Regular updates - Keep CroissantPay and dependencies updated
Backup regularly - Automate database backups

# Example backup script
pg_dump $DATABASE_URL | gzip > backup_$(date +%Y%m%d).sql.gz

Scaling

Horizontal Scaling

CroissantPay is stateless and scales horizontally:

# Docker Compose
docker compose up -d --scale app=5

# Kubernetes
kubectl scale deployment croissantpay --replicas=5

Database Scaling

For high traffic:

Use read replicas for read-heavy workloads
Consider connection pooling with PgBouncer
Implement database sharding for very large datasets

Troubleshooting

Common Issues

Database connection errors:

# Check connection
psql $DATABASE_URL -c "SELECT 1"

High memory usage:

# Check Node.js memory
docker stats croissantpay

Slow queries:

-- Find slow queries
SELECT query, mean_time, calls 
FROM pg_stat_statements 
ORDER BY mean_time DESC 
LIMIT 10;

Getting Help

Documentation: https://docs.croissantlabs.com/self-hosted
GitHub Issues: https://github.com/croissantpay/croissantpay/issues
Discord: https://discord.gg/croissantpay

Happy self-hosting! 🚀