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

```bash
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

```bash
# 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
```bash
# 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

```bash
# 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

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

### 4. Verify Database Connection

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

```yaml
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

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

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

```markdown
## 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:

```javascript
// 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:
   ```bash
   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

```bash
# 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