Deployment

Docker, reverse proxy setup, and environment variable reference.

Payment safety upgrade

Startup applies migration 011_payment_safety.sql before serving requests. It adds durable signed payments, atomic spend reservations, shared PIN attempts, and anchor/bill request identities. Reconcile legacy in-flight payments before rollout; old Redis deduplication records are not migrated. Updated clients must reuse Idempotency-Key on payment retries.

Docker

# Build
docker build -t stackr:latest .

# Run
docker run --rm -p 3000:3000 --env-file .env stackr:latest

# Or use docker-compose
docker-compose up -d

Reverse Proxy

Terminate TLS at a reverse proxy. Set TRUSTED_PROXY_IPS to the proxy's IP.

Caddyfile

stackr.example.com {
    reverse_proxy localhost:3000
}

Environment Variables

VariableDefaultDescription
HOST0.0.0.0Listen address
PORT3000Listen port
ENVIRONMENTdevelopmentdevelopment | staging | production
DATABASE_URLNot setPostgres connection string
REDIS_URLredis://127.0.0.1:6379Redis connection string
STELLAR_HORIZON_URLtestnetHorizon API endpoint
FEE_PAYER_SECRETNot setStellar account that pays fees and funds new accounts
USDC_ASSET_CODEUSDCAsset code on Stellar
USDC_ISSUERtestnet issuerUSDC issuer account
WALLET_MASTER_SEEDNot setMaster seed for wallet derivation (CRITICAL)
WALLET_ENCRYPTION_KEYNot set64 hex chars for AES-256-GCM
FIAT_CURRENCYRWFLocal fiat currency code
FIAT_COUNTRYRWCountry code for Airbills API
ANCHOR_DOMAINNot setSEP-24 anchor domain
WEBHOOK_SECRETNot setAnchor webhook authentication
INTERNAL_API_KEYNot setLegacy configuration; API v1 authenticates operator keys from the backend database
REQUIRE_ENCRYPTED_API_PINSfalseSet true to require encrypted PIN envelopes for REST operations
SWAP_PROVIDERclassicclassic or soroswap; see the Soroswap integration guide for credentials and contract pins

Troubleshooting

"Address already in use"

Another process on port 3000. Kill it: lsof -ti :3000 | xargs kill

"DATABASE_URL required"

.env file missing or not loaded. Ensure it's in the project root.

"WALLET_ENCRYPTION_KEY must be exactly 64 hex characters"

Generate one: openssl rand -hex 32

Stellar "op_src_no_trust"

User doesn't have a USDC trustline. Account wasn't funded during registration.

Exchange rate errors

CoinGecko rate limits on free tier. The 60-second Redis cache minimizes API calls.