Deployment with Coolify

Platform: Coolify v4 | Infrastructure: Self-hosted | Apps: 4 production containers

The fXYZ Network uses Coolify for self-hosted deployment, providing full control over infrastructure while maintaining the ease of PaaS-like deployments.

Infrastructure Overview

Why Coolify

Coolify is an open-source, self-hosted alternative to Vercel/Netlify:

Feature	Benefit
Self-hosted	Full control over infrastructure
Git integration	Automatic deployments on push
Docker-native	Consistent environments
SSL automation	Let's Encrypt certificates
Multiple apps	Single dashboard for all services
Cost effective	One VPS vs. per-seat SaaS pricing

Current Deployment

fXYZ Network Coolify Deployment:
┌─────────────────────────────────────────────────────────┐
│                    Coolify Dashboard                     │
│                    coolify.fxyz.network                  │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
  ┌─────────┐         ┌─────────┐         ┌─────────┐
  │   Web   │         │   App   │         │   API   │
  │ fxyz.   │         │  app.   │         │  api.   │
  │ network │         │  fxyz.  │         │  fxyz.  │
  │         │         │ network │         │ network │
  └─────────┘         └─────────┘         └─────────┘
        │                   │                   │
        └───────────────────┼───────────────────┘
                            │
                    ┌───────▼───────┐
                    │     Docs      │
                    │    docs.      │
                    │    fxyz.      │
                    │   network     │
                    └───────────────┘

Application Configuration

Container IDs

App	Coolify Service UUID	Domain
Web	`lsk00s4g08ookk84sw8c04c8`	fxyz.network
App	`tscw4wswgc8k84c0os4cks88`	app.fxyz.network
API	`dws0c8g0o0cgcocw4w4gko4o`	api.fxyz.network
Docs	`z8wgk4woccckg4oo8gko84w8`	docs.fxyz.network

Letta Server

The Letta AI server runs as a separate Coolify service:

Detail	Value
Service UUID	`s8gcos44ck08c40sccs04wog`
Container	`fixie_server-s8gcos44ck08c40sccs04wog`
Database	`fixie_db-s8gcos44ck08c40sccs04wog`
Domain	letta.fxyz.network
Port	8283

Deployment Process

Automatic Deployments

Coolify monitors the GitHub repository for changes:

# Trigger: Push to master branch
# Action: Build and deploy affected apps

1. Git push to master
2. Coolify webhook receives notification
3. Nixpacks detects project type
4. Docker image built
5. Container replaced (zero-downtime)
6. Health check verified

Manual Deployment

Via Coolify dashboard or API:

# Redeploy specific app via Coolify CLI
coolify deploy --uuid lsk00s4g08ookk84sw8c04c8

# Or trigger via webhook
curl -X POST "https://coolify.fxyz.network/api/v1/deploy/lsk00s4g08ookk84sw8c04c8" \
  -H "Authorization: Bearer $COOLIFY_TOKEN"

Build Configuration

Each app uses Nixpacks for automatic build detection:

# Build command (detected from package.json)
pnpm build --filter=<app-name>

# Start command
pnpm start --filter=<app-name>

Environment Variables

Required Variables

Security: Never commit secrets. Configure in Coolify dashboard.

Web App (fxyz.network)

# Public URLs
NEXT_PUBLIC_APP_URL=https://app.fxyz.network
NEXT_PUBLIC_API_URL=https://api.fxyz.network/api/graphql
NEXT_PUBLIC_DOCS_URL=https://docs.fxyz.network

# Analytics (optional)
NEXT_PUBLIC_POSTHOG_KEY=phc_...
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

App (app.fxyz.network)

# API Configuration
NEXT_PUBLIC_API_URL=https://api.fxyz.network/api/graphql

# Privy Authentication
NEXT_PUBLIC_PRIVY_APP_ID=...
PRIVY_APP_SECRET=...

# Solana
NEXT_PUBLIC_CLUSTER_ENV=mainnet-beta
NEXT_PUBLIC_HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=...

# Bridge.xyz
BRIDGE_API_KEY=...
BRIDGE_ENVIRONMENT=production

API (api.fxyz.network)

# Neo4j
NEO4J_URI=neo4j+s://...
NEO4J_USER=neo4j
NEO4J_PASSWORD=...

# Solana Keys (base58)
PAYER_PRIVATE_KEY=...
MINT_AUTHORITY_PRIVATE_KEY=...

# Letta
LETTA_BASE_URL=http://fixie_server-s8gcos44ck08c40sccs04wog:8283
LETTA_SERVER_PASSWORD=...

# Cloudflare R2
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_R2_ACCESS_KEY_ID=...
CLOUDFLARE_R2_SECRET_ACCESS_KEY=...
R2_BUCKET_NAME=fxyz-documents

Database Services

Neo4j (Aura)

Primary graph database hosted on Neo4j Aura:

Setting	Value
Provider	Neo4j Aura
Instance	Professional
Region	us-east-1
Connection	neo4j+s://

PostgreSQL (Letta)

Database for Letta AI agents:

# Docker compose in Coolify
services:
  fixie_db:
    image: pgvector/pgvector:pg16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: letta
      POSTGRES_PASSWORD: ${LETTA_DB_PASSWORD}
      POSTGRES_DB: letta

SSL/TLS Configuration

Automatic Certificates

Coolify handles SSL via Let's Encrypt:

# Each app configured with:
ssl:
  enabled: true
  provider: letsencrypt
  wildcard: false

Custom Domains

Domain	Certificate	Auto-Renew
fxyz.network	Let's Encrypt	✅
app.fxyz.network	Let's Encrypt	✅
api.fxyz.network	Let's Encrypt	✅
docs.fxyz.network	Let's Encrypt	✅
letta.fxyz.network	Let's Encrypt	✅

Health Checks

Configured Endpoints

Each app exposes health endpoints:

App	Endpoint	Expected
Web	`/`	200
App	`/api/health`	200
API	`/health`	200
Docs	`/health`	200
Letta	`/v1/health`	200

Monitoring Configuration

# Coolify health check settings
healthcheck:
  enabled: true
  path: /health
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

Troubleshooting

Common Issues

Build Failures

# Check build logs in Coolify dashboard
# Or via API:
curl "https://coolify.fxyz.network/api/v1/deployments/$DEPLOYMENT_ID/logs" \
  -H "Authorization: Bearer $COOLIFY_TOKEN"

Common causes:

Missing environment variables
pnpm lockfile out of sync
TypeScript errors

Container Restart Loops

# Check container logs
docker logs <container_name> --tail 100

# Common causes:
# - Port already in use
# - Missing database connection
# - Invalid environment variable format

Memory Issues

# Increase container limits in Coolify
resources:
  limits:
    memory: 2G
    cpus: '1'

Database Connectivity

# Test Neo4j connection
curl -u neo4j:$NEO4J_PASSWORD \
  "https://<neo4j-host>:7687/db/neo4j/tx" \
  -H "Content-Type: application/json" \
  -d '{"statements": [{"statement": "RETURN 1"}]}'

# Test Letta PostgreSQL
docker exec fixie_db-s8gcos44ck08c40sccs04wog \
  psql -U letta -d letta -c "SELECT 1"

Scaling

Horizontal Scaling

Coolify supports multi-server deployments:

# Add additional servers
servers:
  - name: server-1
    ip: 10.0.0.1
    apps: [web, app]
  - name: server-2
    ip: 10.0.0.2
    apps: [api, docs]

Resource Allocation

Current production settings:

App	Memory	CPU
Web	1GB	0.5
App	2GB	1.0
API	2GB	1.0
Docs	1GB	0.5
Letta	4GB	2.0

Backup and Recovery

Database Backups

Neo4j (Aura-managed)

Automatic daily backups
Point-in-time recovery
Cross-region replication (optional)

Letta PostgreSQL

# Manual backup
docker exec fixie_db-s8gcos44ck08c40sccs04wog \
  pg_dump -U letta letta > backup_$(date +%Y%m%d).sql

# Restore
docker exec -i fixie_db-s8gcos44ck08c40sccs04wog \
  psql -U letta letta < backup_20260119.sql

Configuration Backup

# Export Coolify configuration
coolify export --output coolify-config-backup.json

Local Development

Docker Compose for Local Dev

# docker-compose.dev.yml
services:
  neo4j:
    image: neo4j:5
    ports:
      - "7474:7474"
      - "7687:7687"
    environment:
      NEO4J_AUTH: neo4j/development

  letta:
    image: letta/letta:0.16.2
    ports:
      - "8283:8283"
    environment:
      LETTA_SERVER_PASSWORD: dev_password
      POSTGRES_URI: postgresql://letta:letta@letta_db:5432/letta

  letta_db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: letta
      POSTGRES_PASSWORD: letta
      POSTGRES_DB: letta

Running Apps Locally

# Start all apps in dev mode
pnpm dev

# Start specific app
pnpm dev --filter=app

# Run production build locally
pnpm build && pnpm start

Security Considerations

Network Security

All traffic encrypted via TLS
Internal services communicate via Docker network
No direct database access from internet

Secret Management

Secrets stored in Coolify encrypted vault
Environment variables injected at runtime
No secrets in git repository

Access Control

Coolify dashboard behind authentication
Role-based access for team members
Audit logging for deployments

Deployment with Coolify

On this page