Neon-Desk/DIRECT_COOLIFY_DEPLOYMENT.md

Fiscal Clone - Direct Coolify Deployment

Bypassing Gitea for direct Coolify deployment!

Deployment Strategy

Method: File Upload (Simplest & Most Reliable)

Why Direct to Coolify?

1. ✅ No Git repository issues
2. ✅ No SSL certificate problems
3. ✅ No authentication failures
4. ✅ Fast deployment
5. ✅ Easy rollback
6. ✅ Built-in environment variable management

Deployment Steps

Step 1: Prepare Files

Already Ready:

• Fiscal Clone code: /data/workspace/fiscal-clone/
• Docker Compose configured
• All features implemented

Step 2: Deploy to Coolify

In Coolify Dashboard:

1. Create New Application

   • Type: Docker Compose
   • Name: fiscal-clone-full-stack
   • Source: File Upload

2. Upload Files

   • Create zip/tarball of fiscal-clone/ folder
   • Or select folder if Coolify supports directory upload
   • Upload all files

3. Configure Build Context

   • Build Context: /
   • Docker Compose File: docker-compose.yml

4. Configure Domains

   • Frontend: fiscal.b11studio.xyz
   • Backend API: api.fiscal.b11studio.xyz

5. Configure Environment Variables

Required Variables:

DATABASE_URL=postgres://postgres:your-secure-password@postgres:5432/fiscal
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=fiscal

JWT_SECRET=your-jwt-secret-key-min-32-characters

NEXT_PUBLIC_API_URL=http://backend:3001

Optional OAuth Variables:

# GitHub OAuth
GITHUB_ID=your-github-oauth-client-id
GITHUB_SECRET=your-github-oauth-client-secret

# Google OAuth
GOOGLE_ID=your-google-oauth-client-id
GOOGLE_SECRET=your-google-oauth-client-secret

6. Deploy!
   • Click "Deploy" button
   • Monitor deployment logs in Coolify

Step 3: First Access

After Deployment:

1. Access Frontend: https://fiscal.b11studio.xyz

2. Create Account:

   • Click "Sign Up"
   • Enter email, name, password
   • Click "Create Account"

3. Login: Use your new account to log in

4. Add to Watchlist:

   • Go to "Watchlist"
   • Add a stock ticker (e.g., AAPL)
   • Wait for SEC filings to be fetched

5. Add to Portfolio:

   • Go to "Portfolio"
   • Add a holding
   • Enter ticker, shares, average cost

Step 4: Database Migrations

Automatic or Manual:

The database schema should automatically create on first run, but you can manually run migrations if needed:

In Coolify Terminal:

# Access backend container
docker exec -it <backend-container-name> sh

# Run migrations
bun run db:migrate

Architecture

Coolify Server
└── Fiscal Clone Application
    ├── Frontend (Next.js 14)
    │   ├── Domain: https://fiscal.b11studio.xyz
    │   ├── Routes: /, /auth/*, /api/*, /portfolio, /filings, /watchlist
    │   └── Environment: NEXT_PUBLIC_API_URL
    ├── Backend (Elysia.js + Bun)
    │   ├── Port: 3001
    │   ├── Routes: /api/*, /api/auth/*
    │   └── Environment: DATABASE_URL, JWT_SECRET, etc.
    └── Database (PostgreSQL 16)
        ├── User auth tables
        ├── Filings tables
        ├── Portfolio tables
        └── Watchlist tables

Health Checks

After deployment, verify all services are running:

Backend Health

curl http://api.fiscal.b11studio.xyz/api/health

Expected Response:

{
  "status": "ok",
  "timestamp": "2026-02-16T02:31:00.000Z",
  "version": "1.0.0",
  "database": "connected"
}

Frontend Health

curl https://fiscal.b11studio.xyz

Expected: HTML page loads successfully

Database Health

# Check Coolify dashboard
# PostgreSQL container should show as "healthy"
# All containers should be "running"

Troubleshooting

Application Won't Start

Check Coolify Logs:

• Navigate to application → Logs
• Look for database connection errors
• Check if PostgreSQL container is healthy
• Verify environment variables are correct

Common Issues:

1. Database Connection Failed

   • Error: connection refused or password authentication failed
   • Fix: Verify DATABASE_URL and POSTGRES_PASSWORD match
   • Fix: Ensure PostgreSQL container is running and healthy

2. Frontend Can't Connect to Backend

   • Error: 502 Bad Gateway or Connection refused
   • Fix: Verify NEXT_PUBLIC_API_URL is correct
   • Fix: Check if backend is running
   • Fix: Verify network connectivity between containers

3. Authentication Fails

   • Error: Invalid token or Authentication failed
   • Fix: Generate new JWT_SECRET
   • Fix: Update backend container to restart
   • Fix: Verify OAuth credentials (GitHub/Google) are correct

4. Port Conflicts

   • Error: Address already in use
   • Fix: Coolify automatically assigns ports
   • Fix: Check Coolify logs for port conflicts

Manual Restart

If application is in bad state:

1. In Coolify Dashboard → Application
2. Click "Restart" button
3. Wait for all containers to restart
4. Check logs for errors

Rollback to Previous Version

If deployment breaks functionality:

1. In Coolify Dashboard → Application
2. Click "Deployments"
3. Select previous successful deployment
4. Click "Rollback"
5. Verify functionality

Advanced Configuration

Performance Tuning

For High Load:

In Coolify environment variables for backend:

# Database connection pooling
POSTGRES_DB_MAX_CONNECTIONS=200
POSTGRES_DB_MAX_IDLE_CONNECTIONS=50
POSTGRES_DB_CONNECTION_LIFETIME=1h

# Worker processes
PORT=3001
NODE_ENV=production

Caching Configuration:

Already configured with Redis. Add environment variable:

# Enable Redis caching
REDIS_ENABLED=true
REDIS_URL=redis://redis:6379

SSL/TLS Configuration

Coolify automatically handles SSL with Let's Encrypt. Ensure:

• Domain DNS points correctly to Coolify
• Port 80 and 443 are open on VPS firewall
• Coolify Traefik proxy is running

Monitoring

Coolify Built-in Monitoring

1. Application Logs: View in Coolify Dashboard
2. Container Logs: Docker logs for each service
3. Resource Usage: CPU, Memory, Disk in Dashboard
4. Health Checks: Built-in health endpoints

External Monitoring

Set up uptime monitoring:

Services:

• UptimeRobot
• Pingdom
• StatusCake

URLs to Monitor:

• Frontend: https://fiscal.b11studio.xyz
• Backend API: http://api.fiscal.b11studio.xyz/api/health
• Health Check: http://api.fiscal.b11studio.xyz/health

Discord Alerts

Integrate with your Discord server:

Create these webhooks in Coolify:

1. For Deployment Channel:

   • Coolify → Application → Webhooks
   • Webhook URL: Your Discord webhook URL
   • Events: Deployment status

2. For Alert Channel:

   • Webhook URL: Your Discord webhook URL
   • Events: Application failures, crashes

Or use Coolify's built-in Discord integration (if available)

Backup Strategy

Automatic Backups (Coolify)

Coolify provides:

• ✅ PostgreSQL automated backups
• ✅ Volume persistence across deployments

Manual Backups

Export Database:

# In Coolify terminal
docker exec -it postgres pg_dump -U postgres -d fiscal > backup-$(date +%Y%m%d).sql

Import Database:

# In Coolify terminal
docker exec -i postgres psql -U postgres -d fiscal < backup-20260215.sql

Download Data:

# Access backend container
docker exec -it backend tar -czf /tmp/fiscal-backup.tar.gz /app/data

# Download from container (if Coolify provides file access)
# Or access via Coolify file browser (if available)

Scaling

Horizontal Scaling

In Coolify:

1. Application Settings → Resources
2. Increase replicas for frontend
3. Add more backend instances
4. Load balance with Traefik

Database Scaling

For High Load:

1. Use separate PostgreSQL instance
2. Configure connection pooling
3. Use read replicas for queries
4. Optimize indexes

Coolify provides:

• Easy horizontal scaling
• Load balancing with Traefik
• Resource limits per container

Security

Environment Variables Security

Never commit secrets!

Use Coolify environment variables for sensitive data:

❌ DO NOT COMMIT:

• API keys
• Database passwords
• JWT secrets
• OAuth client secrets
• SMTP credentials

✅ DO USE:

• Coolify environment variables
• Encrypted storage in Coolify
• Separate .env files for local development

Password Security

Generate Strong Passwords:

# Database password
openssl rand -base64 32 | tr -d '[:alnum:]'

# JWT secret
openssl rand -base64 32 | tr -d '[:alnum:]'

# Admin password (if needed)
openssl rand -base64 32 | tr -d '[:alnum:]'

Store securely in Coolify:

• DATABASE_URL=postgres://postgres:@postgres:5432/fiscal
• JWT_SECRET=
• POSTGRES_PASSWORD=

Access Control

Discord Server:

• Create private channels for admin discussions
• Limit sensitive information to private channels
• Use role-based access control

Coolify:

• Use Team permissions
• Restrict application access
• Enable 2FA (if available for Coolify account)
• Regular security updates

Firewall Rules

Ensure VPS firewall allows:

# Inbound
80/tcp - HTTP (Traefik)
443/tcp - HTTPS (Traefik)
22/tcp - SSH (optional)
3000/tcp - Next.js
3001/tcp - Backend API

# Outbound
All (for Git operations, SEC API, Yahoo Finance)

Update Strategy

Update Process

Current Version: 1.0.0

To Update:

1. Update Code Locally

   cd /data/workspace/fiscal-clone
   git pull origin main
   # Make changes
   git add .
   git commit -m "chore: Update Fiscal Clone"
   git push origin main
   

2. Deploy New Version in Coolify

   • Go to Coolify Dashboard → Application
   • Click "Deploy" button
   • Coolify pulls latest code and rebuilds

3. Monitor Deployment

   • Watch logs in Coolify
   • Verify all services are healthy
   • Test all features

Blue-Green Deployment:

1. Deploy new version to new Coolify application
2. Switch DNS to new version
3. Verify new version works
4. Delete old version

Rollback Strategy

If new deployment has issues:

1. In Coolify Dashboard → Deployments
2. Select previous stable version
3. Click "Rollback"
4. DNS switches back automatically

CI/CD

Coolify Built-in CI/CD

Automatic Deployment:

Configure webhooks in Coolify:

GitHub:

1. Repository Settings → Webhooks
2. Payload URL: Coolify provides this
3. Events: Push, Pull Request
4. Push to main branch triggers deployment

GitLab:

1. Repository Settings → Integrations
2. Deployments → Create deploy token
3. Configure in Coolify

Gitea:

1. Repository Settings → Webhooks
2. Gitea webhook URL: Coolify provides this
3. Events: Push events

Pipeline

Push Code → GitHub/GitLab/Gitea
         ↓
Coolify Webhook Triggered
         ↓
New Build & Deploy
         ↓
Application Deployed to Coolify
         ↓
Health Checks & Monitoring
         ↓
Live on https://fiscal.b11studio.xyz

Documentation

Links

• Fiscal Clone README: /data/workspace/fiscal-clone/README.md
• Coolify Docs: https://docs.coolify.io/
• NextAuth Docs: https://next-auth.js.org/
• Elysia Docs: https://elysiajs.com/
• PostgreSQL Docs: https://www.postgresql.org/docs/

API Documentation

After deployment, access:

• Swagger UI: https://api.fiscal.b11studio.xyz/swagger
• API Docs: /api/filings, /api/portfolio, etc.

Quick Reference

Environment Variables:

DATABASE_URL=postgres://postgres:password@postgres:5432/fiscal
JWT_SECRET=<your-jwt-secret>
NEXT_PUBLIC_API_URL=http://backend:3001

Endpoints:

• Frontend: https://fiscal.b11studio.xyz
• Backend API: http://api.fiscal.b11studio.xyz
• Health: http://api.fiscal.b11studio.xyz/api/health
• Swagger: https://api.fiscal.b11studio.xyz/swagger

## Success Criteria

Deployment is successful when:

- [ ] All containers are running
- [ ] PostgreSQL is healthy
- [ ] Frontend loads at https://fiscal.b11studio.xyz
- [ ] Backend API responds on /api/health
- [ ] Can create account and login
- [ ] Can add stocks to watchlist
- [ ] Can add holdings to portfolio
- [ ] SEC filings are being fetched
- [ ] Database tables created
- [ ] No errors in logs

---

**Deployment Version:** 2.0 (Direct to Coolify)
**Status:** Ready for deployment
**Last Updated:** 2026-02-16