Neon-Desk/DEPLOY_VIA_GITEA.md

Deploy Fiscal Clone via Gitea to Coolify

Deploy your fiscal-clone project using your self-hosted Git service.

Quick Start

1. Push to Gitea

cd /data/workspace/fiscal-clone
git init
git add .
git commit -m "Initial commit: Fiscal Clone production ready"
git remote add gitea https://git.b11studio.xyz/francy51/fiscal-clone.git
git push -u gitea main

2. Deploy to Coolify

In Coolify dashboard:

1. Create New Application

   • Type: Docker Compose
   • Name: fiscal-clone
   • Source: Git Repository
   • Repository URL: git@git.b11studio.xyz:francy51/fiscal-clone.git
   • Branch: main
   • Build Context: /
   • Docker Compose File: docker-compose.yml

2. Configure Environment Variables

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

JWT_SECRET=your-jwt-secret-here

GITHUB_ID=your-github-oauth-id
GITHUB_SECRET=your-github-oauth-secret

GOOGLE_ID=your-google-oauth-id
GOOGLE_SECRET=your-google-oauth-secret

NEXT_PUBLIC_API_URL=https://api.fiscal.yourdomain.com

3. Configure Domains

Frontend: https://fiscal.b11studio.xyz
Backend API: https://api.fiscal.b11studio.xyz

4. Deploy

Click "Deploy" button in Coolify

Configuration Details

Backend Application

Service 1: PostgreSQL

• Image: postgres:16-alpine
• Database Name: fiscal
• User: postgres
• Password: (set in environment)
• Volumes: postgres_data

Service 2: Backend

• Build Context: ./backend
• Dockerfile: Dockerfile
• Ports: 3001
• Environment: All backend env vars
• Health Check: /api/health
• Depends On: postgres

Service 3: Frontend

• Build Context: ./frontend
• Dockerfile: Dockerfile
• Ports: 3000
• Environment: NEXT_PUBLIC_API_URL
• Depends On: backend

Traefik Configuration

Coolify automatically configures routing. Labels included in docker-compose.yml.

Environment Variables Reference

Required Variables

Variable	Description	Example
DATABASE_URL	PostgreSQL connection string	postgres://postgres:password@postgres:5432/fiscal
JWT_SECRET	JWT signing secret	generate-secure-random-string
NEXT_PUBLIC_API_URL	Backend API URL	https://api.fiscal.yourdomain.com

OAuth Configuration

GitHub OAuth:

• Create OAuth app: https://github.com/settings/developers
• Callback URL: https://fiscal.b11studio.xyz/api/auth/callback/github

Google OAuth:

• Create OAuth app: https://console.cloud.google.com/apis/credentials
• Callback URL: https://fiscal.b11studio.xyz/api/auth/callback/google

Deployment Steps Detailed

Step 1: Prepare Repository

# Navigate to project
cd /data/workspace/fiscal-clone

# Initialize Git
git init

# Add all files
git add .

# Create initial commit
git commit -m "feat: Initial release

- SEC filings extraction with EDGAR API
- Portfolio analytics with Yahoo Finance
- NextAuth.js authentication (GitHub, Google, Email)
- Real-time stock price updates
- PostgreSQL with automatic P&L calculations
- Recharts visualizations
- OpenClaw AI integration endpoints"

# Add remote
git remote add gitea https://git.b11studio.xyz/francy51/fiscal-clone.git

# Push to Gitea
git push -u gitea main

Step 2: Create Gitea Repository

Option A: Use Gitea web interface

1. Access: https://git.b11studio.xyz
2. Login (admin account)
3. Create repository: fiscal-clone
4. Make it private (recommended)
5. Clone HTTPS URL: https://git.b11studio.xyz/francy51/fiscal-clone.git

Option B: Create via API

# Create repo using Gitea API
curl -X POST \
  -H "Authorization: token YOUR_GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "fiscal-clone",
    "description": "Fiscal.ai clone - Financial filings and portfolio analytics",
    "private": true,
    "auto_init": false
  }' \
  https://git.b11studio.xyz/api/v1/user/repos

Step 3: Configure Coolify Application

1. Navigate to Coolify Dashboard

   • https://coolify.b11studio.xyz

2. Create Application

   • Click "New Application"
   • Name: fiscal-clone-full-stack
   • Type: Docker Compose
   • Source: Git Repository

3. Git Configuration

   • Repository URL: git@git.b11studio.xyz:francy51/fiscal-clone.git
   • Branch: main
   • Docker Compose File: docker-compose.yml
   • Build Context: /
   • Environment ID: Select or create new

4. Add Environment Variables

   • Click "Add Variable"
   • Add each required variable from reference table

5. Configure Domains

   • Click "Domains"
   • Add domain: fiscal.b11studio.xyz
   • Select frontend service
   • Generate SSL certificate

6. Deploy

   • Click "Deploy" button
   • Monitor deployment logs

Post-Deployment Verification

1. Check Application Status

In Coolify dashboard:

• Verify all services are running
• Check deployment logs
• Verify health checks passing

2. Test Endpoints

# Test backend health
curl https://api.fiscal.b11studio.xyz/api/health

# Test frontend
curl https://fiscal.b11studio.xyz

# Test API documentation
curl https://api.fiscal.b11studio.xyz/swagger

3. Run Database Migrations

# In Coolify terminal
docker-compose exec backend bun run db:migrate

4. Verify Database Connection

# Check database connectivity
docker-compose exec backend bun -e "console.log(await db\`SELECT 1\`)"

5. Create First User

1. Access frontend: https://fiscal.b11studio.xyz
2. Click "Sign Up"
3. Create account
4. Log in

6. Add to Watchlist

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

Troubleshooting

Deployment Fails

Issue: Docker build fails

Check:
- Build context is correct (/)
- docker-compose.yml syntax is valid
- Environment variables are set

Solution:

• Redeploy application
• Check Coolify logs
• Verify Gitea repository is accessible

Database Connection Failed

Issue: Backend cannot connect to database

Check:
- DATABASE_URL format is correct
- PostgreSQL service is running
- Network connectivity between containers

Solution:

• Restart PostgreSQL container
• Verify database credentials
• Check environment variables

Frontend Cannot Connect to Backend

Issue: API errors in browser console

Check:
- NEXT_PUBLIC_API_URL is set correctly
- Backend is running
- CORS is configured correctly

Solution:

• Check backend logs
• Verify frontend environment variables
• Clear browser cache

Authentication Fails

Issue: OAuth providers not working

Check:
- OAuth client IDs and secrets are correct
- Callback URLs match Coolify domain
- Redirect URIs are correct

Solution:

• Update OAuth configuration in Coolify
• Verify GitHub/Google console settings
• Check NextAuth configuration

CI/CD with Gitea Actions

Enable Gitea Actions in Coolify

In Coolify environment variables for backend:

GITEA__actions__ENABLED=true
GITEA__actions__DEFAULT_ACTIONS_URL=https://git.b11studio.xyz

Create Workflow File

Create .gitea/workflows/deploy.yml in fiscal-clone:

name: Deploy to Coolify
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Coolify Deployment
        run: |
          curl -X POST \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer ${{ secrets.COOLIFY_API_TOKEN }}}" \
            -d '{
              "resource_id": "your-resource-id",
              "source": "main"
            }' \
            https://coolify.b11studio.xyz/api/v1/resources/${{ secrets.COOLIFY_RESOURCE_ID }}/deploy

Store Secrets

Add secrets in Gitea:

1. COOLIFY_API_TOKEN - Your Coolify API token
2. COOLIFY_RESOURCE_ID - The Coolify resource ID

Monitoring & Alerts

Set Up Discord Alerts

1. Create Discord webhook URL for deployment channel
2. Add to fiscal-clone monitoring

Health Check Endpoint

GET /api/health

Response:
{
  "status": "ok",
  "timestamp": "2026-02-15T23:51:00.000Z",
  "version": "1.0.0",
  "database": "connected"
}

Maintenance

Updates

# Pull latest changes from Gitea
git pull origin main

# Re-deploy in Coolify (automatic webhook triggers)
# Or manual redeploy

Backups

Coolify provides automated PostgreSQL backups. To manually backup:

# Export database
docker-compose exec postgres pg_dump -U postgres -d fiscal > backup.sql

# Restore database
docker-compose exec -T postgres psql -U postgres -d fiscal < backup.sql

Monitoring

Set up monitoring in /data/workspace/memory/coolify-integration.md:

## Applications
- fiscal-backend - https://api.fiscal.b11studio.xyz
- fiscal-frontend - https://fiscal.b11studio.xyz

## Monitoring
- API health: /api/health
- Database status: Coolify metrics
- Deployment logs: Coolify dashboard

## Alerts
- Discord: #alerts channel
- Email: Optional SMTP configuration

Security Considerations

Database

• PostgreSQL 16-alpine (latest stable)
• Strong random password required
• No exposed ports (only internal)
• Coolify provides SSL/TLS

API

• JWT tokens with 30-day expiration
• CORS configured for allowed origins
• Rate limiting recommended (add Nginx/Cloudflare)

Authentication

• Secure OAuth callback URLs
• HTTPS only
• 2FA recommended for sensitive operations

Secrets Management

Never commit secrets to repository. Use Coolify environment variables:

❌ DO NOT COMMIT:

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

✅ DO USE:

• Coolify environment variables
• Encrypted secrets in Coolify
• Separate config files for local development

Scaling

Horizontal Scaling

Add more application replicas:

1. In Coolify application settings
2. Click "Resources"
3. Adjust replica count

Database Scaling

For high load, consider:

1. Separate PostgreSQL instance
2. Connection pooling optimization
3. Read replicas for queries

Caching

Redis is included in docker-compose.yml. Configure application caching:

// In backend services
const cache = {
  get: async (key) => {
    // Try Redis first
    try {
      const value = await redis.get(key);
      return value;
    } catch (err) {
      return null;
    }
  },
  set: async (key, value, ttl = 3600) => {
    await redis.setex(key, ttl, value);
  }
};

Rollback Procedure

Rollback to Previous Version

1. In Gitea, tag previous version:

   git tag v1.0.0
   git push origin v1.0.0
   

2. In Coolify, select previous commit:

   • Application Settings → Deployments
   • Select previous deployment
   • Click "Rollback"

Emergency Rollback

If critical issues occur:

1. Stop application in Coolify
2. Deploy known good version
3. Restore database from backup
4. Verify functionality
5. Document incident

API Usage

SEC Filings API

GET /api/filings/{ticker}
GET /api/filings
POST /api/filings/refresh/{ticker}

Portfolio API

GET /api/portfolio/{userId}
GET /api/portfolio/{userId}/summary
POST /api/portfolio
PUT /api/portfolio/{id}
DELETE /api/portfolio/{id}

Watchlist API

GET /api/watchlist/{userId}
POST /api/watchlist
DELETE /api/watchlist/{id}

Support

Documentation Links

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

Troubleshooting Commands

# Check container logs
docker-compose logs -f backend

# Check all containers
docker-compose ps

# Restart specific service
docker-compose restart backend

# Check database connection
docker-compose exec backend bun run db:migrate

# View resource usage
docker stats

# Clean up resources
docker system prune -f

Success Criteria

Deployment is successful when:

• All containers are running
• Health check passes: /api/health
• Frontend loads at domain
• Can create account and login
• Can add stocks to watchlist
• SEC filings are being fetched
• Database migrations completed
• No errors in logs

---

Deployment Guide Version: 1.0 Last Updated: 2026-02-15 Status: Ready for deployment