# Deployment Fixes Documentation

## Overview
This document outlines the critical changes made to resolve deployment issues when containerizing the Next.js taskboard application with Docker and Portainer.

## Major Issues Fixed

### 1. File API Reference Error
**Problem**: `ReferenceError: File is not defined` during build process
**Root Cause**: Using `z.instanceof(File)` in Zod schemas - `File` API not available in server-side rendering context
**Solution**: 
- Replaced `z.instanceof(File)` with runtime type guards in schema validation
- Updated file validation to use object shape validation instead of instanceof checks
- Modified affected schemas in `src/features/workspaces/schemas.ts` and `src/features/projects/schemas.ts`

```typescript
// Before (caused error)
image: z.instanceof(File).optional()

// After (working solution)
image: z.any().optional() // with runtime validation in components
```

### 2. bcryptjs Edge Runtime Compatibility
**Problem**: `TypeError: process.on is not a function` and bcryptjs conflicts in Edge Runtime
**Root Cause**: NextAuth and bcryptjs trying to use Node.js APIs in Edge Runtime environment
**Solution**:
- Added webpack externals configuration in `next.config.mjs`
- Configured `serverComponentsExternalPackages` to handle bcryptjs properly
- Replaced NextAuth middleware with simple pass-through middleware

```javascript
// next.config.mjs additions
webpack: (config) => {
  config.externals = [...(config.externals || []), 'bcryptjs'];
  return config;
},
serverComponentsExternalPackages: ['bcryptjs']
```

### 3. Peer Dependency Conflicts
**Problem**: `date-fns` version conflicts between dependencies
**Root Cause**: `react-day-picker@8.10.1` requires `date-fns@^2.28.0 || ^3.0.0` but project uses `date-fns@^4.1.0`
**Solution**:
- Added `--legacy-peer-deps` flag to npm install in Dockerfile
- This allows npm to use older dependency resolution algorithm that's more permissive

```dockerfile
# Updated npm install commands
RUN npm ci --only=production --legacy-peer-deps
```

### 4. Middleware Edge Runtime Issues
**Problem**: NextAuth middleware causing Edge Runtime errors in Docker environment
**Root Cause**: NextAuth middleware trying to access Node.js APIs not available in Edge Runtime
**Solution**:
- Removed complex NextAuth middleware (`src/middleware.ts` deleted)
- Implemented simple pass-through middleware
- Moved authentication checks to page/component level where they run in Node.js runtime

```typescript
// Simple middleware approach (in components)
export { default } from "next-auth/middleware"
export const config = { matcher: [] } // Empty matcher = no middleware interference
```

### 5. Docker Build Optimization
**Problem**: Large Docker images and slow builds
**Solution**:
- Added `output: 'standalone'` to Next.js config for optimized Docker builds
- Multi-stage Docker build to reduce final image size
- Automatic database migrations on container startup

```javascript
// next.config.mjs
const nextConfig = {
  output: 'standalone', // Critical for Docker optimization
  // ... other config
}
```

### 6. Error Handling and Debugging
**Added**: Comprehensive error handling and logging
- Client-side error boundary (`src/components/client-error-handler.tsx`)
- Enhanced error reporting in layout components
- Debug logging throughout the application for troubleshooting

### 7. RPC Configuration Updates
**Problem**: File handling in RPC calls
**Solution**: Updated `src/lib/rpc.ts` to properly handle file uploads and form data in containerized environment

## Configuration Changes Made

### next.config.mjs
```javascript
const nextConfig = {
  output: 'standalone', // Essential for Docker
  webpack: (config) => {
    config.externals = [...(config.externals || []), 'bcryptjs'];
    return config;
  },
  serverComponentsExternalPackages: ['bcryptjs'],
  experimental: {
    serverActions: {
      bodySizeLimit: '10mb'
    }
  }
}
```

### Dockerfile
```dockerfile
# Key additions for fixing build issues
RUN npm ci --only=production --legacy-peer-deps
RUN npx prisma generate
RUN npm run build
```

### Schema Updates
- Replaced `z.instanceof(File)` with runtime validation
- Updated form handling to work with containerized environment
- Fixed file upload validation logic

## Impact of Changes

### Before Fixes
- Build failures due to File API errors
- Runtime errors from bcryptjs in Edge Runtime
- Peer dependency conflicts preventing installation
- 500 internal server errors from middleware issues

### After Fixes
- Clean Docker builds without errors
- Stable runtime performance
- Proper authentication flow
- Working file uploads and form submissions
- Successful deployment to Portainer

## Key Takeaways

1. **Edge Runtime Limitations**: Be careful with dependencies that require Node.js APIs when using Edge Runtime
2. **File API Availability**: `File` constructor not available in all Next.js contexts - use runtime validation instead
3. **Dependency Management**: `--legacy-peer-deps` can resolve complex dependency conflicts
4. **Docker Optimization**: `output: 'standalone'` is crucial for efficient Next.js Docker deployments
5. **Middleware Simplicity**: Sometimes simpler middleware approaches work better in containerized environments

## Files Modified
- `next.config.mjs` - Build configuration and externals
- `src/app/layout.tsx` - Error handling and logging
- `src/lib/rpc.ts` - File handling improvements
- `src/features/workspaces/schemas.ts` - Schema validation fixes
- `src/features/projects/schemas.ts` - Schema validation fixes
- `src/components/client-error-handler.tsx` - Error boundary (new)
- `Dockerfile` - Build process improvements
- Various form components - File handling updates

The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 
The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 

The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 

The combination of these changes resolved alsl deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 

The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 

The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 

The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 

The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration. 

The combination of these changes resolved all deployment issues and enabled successful containerized deployment with Portainer and nginx-proxy-manager integration.