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:**
```bash
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:**
```bash
# 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:**
```bash
# 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
```bash
curl http://api.fiscal.b11studio.xyz/api/health
```

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

### Frontend Health
```bash
curl https://fiscal.b11studio.xyz
```

**Expected:** HTML page loads successfully

### Database Health
```bash
# 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:
```bash
# 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:
```bash
# 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:**
```bash
# In Coolify terminal
docker exec -it postgres pg_dump -U postgres -d fiscal > backup-$(date +%Y%m%d).sql
```

**Import Database:**
```bash
# In Coolify terminal
docker exec -i postgres psql -U postgres -d fiscal < backup-20260215.sql
```

**Download Data:**
```bash
# 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:**

```bash
# 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:<secure-password>@postgres:5432/fiscal
- JWT_SECRET=<secure-random-32-characters>
- POSTGRES_PASSWORD=<secure-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**
   ```bash
   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:**
```bash
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