feat: Complete Fiscal Clone deployment package

- SEC filings extraction (10-K, 10-Q, 8-K) - Portfolio analytics with real-time prices - Watchlist management - NextAuth.js authentication - OpenClaw AI integration - PostgreSQL database with auto P&L calculations - Elysia.js backend (Bun runtime) - Next.js 14 frontend (TailwindCSS + Recharts) - Production-ready Docker configurations
2026-02-16 03:49:32 +00:00
commit da58289eb1
39 changed files with 4070 additions and 0 deletions
--- a/DIRECT_COOLIFY_DEPLOYMENT.md
+++ b/DIRECT_COOLIFY_DEPLOYMENT.md
@@ -0,0 +1,555 @@
+# 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