task-board/DEPLOYMENT_FIXES.md

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

// 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

// 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

# 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

// 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

// 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

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

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.