ƒxyzƒxyz Network
Developer

Deployment Guide

Deploy fXYZ Network applications using Coolify self-hosted infrastructure

Deployment Guide

Platform: Coolify v4 | Infrastructure: Self-hosted | Build: Nixpacks

This guide covers deploying fXYZ Network applications to production using our Coolify self-hosted infrastructure.

Quick Reference

Application URLs

AppDomainPurpose
Webfxyz.networkMarketing site
Appapp.fxyz.networkMember dashboard
APIapi.fxyz.networkGraphQL API
Docsdocs.fxyz.networkDocumentation
Lettaletta.fxyz.networkAI agent server

Deployment Trigger

Automatic deployment on push to master branch:

git push origin master
# → Coolify webhook triggered
# → Nixpacks builds affected apps
# → Zero-downtime container replacement

Local Development Setup

Prerequisites

# Required tools
node --version  # v20+
pnpm --version  # v9+

# Clone and install
git clone https://github.com/fxyz-network/fxallapp.git
cd fxallapp
pnpm install

Environment Variables

Copy example environment files:

# Root environment
cp .env.example .env

# App-specific (for local overrides)
cp apps/api/.env.example apps/api/.env.local
cp apps/app/.env.example apps/app/.env.local

Required Variables

Minimum for Development

# Neo4j (required for most features)
NEO4J_URI=neo4j://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=development

# Privy (required for auth)
NEXT_PUBLIC_PRIVY_APP_ID=<your-dev-app-id>
PRIVY_APP_SECRET=<your-dev-secret>

Full Local Stack

# Start services with Docker Compose
docker compose -f docker-compose.dev.yml up -d

# This starts:
# - Neo4j on port 7474 (browser) / 7687 (bolt)
# - Letta server on port 8283
# - PostgreSQL for Letta on port 5433

Running Locally

# All apps in dev mode
pnpm dev

# Specific app only
pnpm dev --filter=app
pnpm dev --filter=api
pnpm dev --filter=web
pnpm dev --filter=docs

Production Deployment

Coolify Dashboard Access

Access the Coolify dashboard at coolify.fxyz.network with team credentials.

Container IDs

AppCoolify Service UUID
Weblsk00s4g08ookk84sw8c04c8
Apptscw4wswgc8k84c0os4cks88
APIdws0c8g0o0cgcocw4w4gko4o
Docsz8wgk4woccckg4oo8gko84w8
Lettas8gcos44ck08c40sccs04wog

Manual Deployment

For manual deploys (e.g., after config changes):

# Via Coolify dashboard
# 1. Navigate to app
# 2. Click "Redeploy"

# Or via webhook (requires token)
curl -X POST "https://coolify.fxyz.network/api/v1/deploy/<UUID>" \
  -H "Authorization: Bearer $COOLIFY_TOKEN"

Environment Configuration

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=...

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 (internal Docker network)
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

Security: Never commit secrets. Configure all sensitive values in Coolify dashboard only.

Build Process

Nixpacks Detection

Coolify uses Nixpacks to automatically detect and build the project:

# Detected from package.json
build_command: pnpm build --filter=<app-name>
start_command: pnpm start --filter=<app-name>

Build Commands

# Full monorepo build
pnpm build

# Specific app
pnpm build --filter=app
pnpm build --filter=api

# Type checking
./scripts/typecheck.sh

# Linting
pnpm lint

Turbo Caching

The monorepo uses Turbo for build caching:

# Local cache in node_modules/.cache/turbo
# Remote caching can be enabled via TURBO_TOKEN

Database Services

Neo4j (Aura)

Primary graph database hosted on Neo4j Aura:

SettingValue
ProviderNeo4j Aura
InstanceProfessional
Regionus-east-1
Protocolneo4j+s:// (TLS)
# Test connection
cypher-shell -a "$NEO4J_URI" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" \
  "RETURN 1 AS test"

Letta PostgreSQL

Database for AI agent memory:

# Container name
fixie_db-s8gcos44ck08c40sccs04wog

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

Health Checks

Endpoints

AppHealth EndpointExpected
Web/200
App/api/health200
API/health200
Docs/health200
Letta/v1/health200

Monitoring Script

#!/bin/bash
# check-health.sh

endpoints=(
  "https://fxyz.network"
  "https://app.fxyz.network/api/health"
  "https://api.fxyz.network/health"
  "https://docs.fxyz.network/health"
  "https://letta.fxyz.network/v1/health"
)

for url in "${endpoints[@]}"; do
  status=$(curl -s -o /dev/null -w "%{http_code}" "$url")
  echo "$url: $status"
done

Troubleshooting

Build Failures

Check build logs:

# In Coolify dashboard, click on the failed deployment
# 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-lock.yaml out of sync → run pnpm install locally and commit
  • TypeScript errors → run pnpm typecheck locally

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 from container
docker exec <api_container> curl -u neo4j:$NEO4J_PASSWORD \
  "https://<neo4j-host>:7473/db/neo4j/tx" \
  -H "Content-Type: application/json" \
  -d '{"statements": [{"statement": "RETURN 1"}]}'

Rollback

Quick Rollback

In Coolify dashboard:

  1. Navigate to the app
  2. Go to "Deployments" tab
  3. Find the previous successful deployment
  4. Click "Redeploy"

Git-based Rollback

# Find previous working commit
git log --oneline -10

# Revert to specific commit
git revert <commit-hash>
git push origin master
# → Triggers new deployment with reverted code

SSL Certificates

Automatic via Let's Encrypt

Coolify handles SSL automatically:

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

Certificate Renewal

Certificates auto-renew 30 days before expiration. No manual intervention needed.

Resource Allocation

Production Settings

AppMemoryCPU
Web1GB0.5
App2GB1.0
API2GB1.0
Docs1GB0.5
Letta4GB2.0

Scaling

For horizontal scaling, add additional servers in Coolify:

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

Local Development Setup

Get the fXYZ Network monorepo running locally for development and testing.

REST API Reference

Complete REST API documentation for fXYZ Network services including Fixies, Bridge, Prices, and more.

On this page

Deployment GuideQuick ReferenceApplication URLsDeployment TriggerLocal Development SetupPrerequisitesEnvironment VariablesRequired VariablesMinimum for DevelopmentFull Local StackRunning LocallyProduction DeploymentCoolify Dashboard AccessContainer IDsManual DeploymentEnvironment ConfigurationWeb App (fxyz.network)App (app.fxyz.network)API (api.fxyz.network)Build ProcessNixpacks DetectionBuild CommandsTurbo CachingDatabase ServicesNeo4j (Aura)Letta PostgreSQLHealth ChecksEndpointsMonitoring ScriptTroubleshootingBuild FailuresContainer Restart LoopsMemory IssuesDatabase ConnectivityRollbackQuick RollbackGit-based RollbackSSL CertificatesAutomatic via Let's EncryptCertificate RenewalResource AllocationProduction SettingsScalingRelated Documentation