ATOM Documentation

← Back to App

Deployment Guide - Local Build & Fly.io Deploy

Problem

Fly.io machines have **2GB RAM limit**, but Next.js build needs **8GB+**.

Solution

Build **locally** (8GB+ RAM) → Deploy pre-built artifacts to Fly.io (2GB runtime only)

---

Quick Deploy

npm run deploy:fly

This script:

  1. ✅ Cleans previous build artifacts
  2. ✅ Installs dependencies
  3. ✅ Builds Next.js locally with 8GB RAM
  4. ✅ Verifies build artifacts exist
  5. ✅ Deploys to Fly.io (copies pre-built files)

---

Manual Deploy (Step-by-Step)

1. Build Locally

# Clean previous build
rm -rf .next node_modules/.cache

# Install dependencies
npm ci --legacy-peer-deps

# Build with 8GB RAM
NODE_OPTIONS="--max-old-space-size=8192" npm run build

2. Verify Build Artifacts

# Check standalone output exists
ls -la .next/standalone

# Check static files exist
ls -la .next/static

3. Deploy to Fly.io

# Deploy pre-built artifacts
fly deploy

---

Memory Settings

Local Build (your machine)

  • **Dev**: 8GB (NODE_OPTIONS="--max-old-space-size=8192")
  • **Build**: 8GB (package.json script)
  • **Low-memory fallback**: 6GB (npm run build:lowmem)

Fly.io Runtime (production)

  • **Next.js**: 1.5GB (NODE_OPTIONS="--max-old-space-size=1536")
  • **Python**: ~400MB
  • **System overhead**: ~100MB
  • **Total**: ~2GB (within Fly.io limit)

---

Troubleshooting

Build Fails Locally (OOM)

# Check available memory
free -h  # Linux
vm_stat  # macOS

# Close memory-intensive apps (Chrome, Docker, etc.)

# Try low-memory mode
npm run build:lowmem

Fly Deploy Fails (Missing Artifacts)

# ERROR: Next.js build artifacts not found!
# Run 'npm run build' locally first!

# Solution: Build first
npm run build
fly deploy

Runtime Issues on Fly.io

# Check logs
fly logs --tail 100

# Restart machines
fly apps restart

# Scale up memory (if needed)
fly scale memory 4096

---

Files Changed

  1. **Dockerfile** - Copies pre-built artifacts instead of building
  2. **package.json** - Increased memory limits, added deploy script
  3. **next.config.mjs** - Webpack optimizations
  4. **fly.toml** - Added build warning comment
  5. **scripts/deploy-fly.sh** - Automated deployment script

---

Architecture

Local Machine (8GB+ RAM)          Fly.io (2GB RAM)
┌─────────────────────┐           ┌─────────────────────┐
│  npm run build      │           │                     │
│  ↓                  │           │  Copy artifacts     │
│  .next/standalone   │ ────────> │  .next/standalone   │
│  .next/static       │           │  .next/static       │
│                     │           │                     │
│  8GB build memory   │           │  1.5GB runtime      │
└─────────────────────┘           └─────────────────────┘

---

Verification

After deployment:

# Check app is running
curl https://app.atomagentos.com/api/health

# Check Fly.io status
fly status

# View logs
fly logs --tail 50

---

Previous vs New Approach

ApproachBuild LocationBuild MemoryDeploy Time
**Old**Fly.io remote2GB (fails)❌ OOM error
**New**Local machine8GB+✅ 3-5 min