feat: configurable upload file size limits via .env (#695)

* feat: make upload file size limits configurable via .env

Add UPLOAD_MAX_*_MB environment variables for documents, images, videos,
exercise assignment files, AI assistant documents, landing page images,
and media thumbnails. API presign routes validate file size server-side;
dashboard UI reads the same limits from layout data.

* chore: wire upload limit env vars through Docker compose and docs

Pass UPLOAD_MAX_*_MB from the root .env into api and dashboard containers
in both compose files, document them in .env.example and self-hosting guides.

Co-authored-by: Rotimi Best <[email protected]>

* docs: cross-link upload limits in README, Railway, Coolify, and Cloudflare guides

Co-authored-by: Rotimi Best <[email protected]>

* fix: address PR review feedback on upload limits

- Restore 5 MB default for thumbnail uploads (edit-asset-dialog regression)
- Add getResolvedUploadLimits() fallback for Storybook/tests
- Cache core getUploadLimits() like the dashboard helper
- Document presign fileSize as advisory; allow zero-byte fileSize in schema
- Only send fileSize to presign when greater than zero

* docs: remove upload limits from Cloudflare setup guide

---------

packages/core/src/config/env.ts

@@ -88,7 +88,21 @@ const envSchema = z.object({
       const parsed = Number(v);
 
       return Number.isFinite(parsed) && parsed >= 1 ? Math.trunc(parsed) : 500;
-    })
+    }),
+  /** Max course lesson document upload size in megabytes (default 5). */
+  UPLOAD_MAX_DOCUMENT_MB: z.string().optional(),
+  /** Max image upload size in megabytes — avatars, media, editor images (default 5). */
+  UPLOAD_MAX_IMAGE_MB: z.string().optional(),
+  /** Max lesson video upload size in megabytes (default 800). */
+  UPLOAD_MAX_VIDEO_MB: z.string().optional(),
+  /** Max exercise assignment file upload size in megabytes (default 2). */
+  UPLOAD_MAX_EXERCISE_FILE_MB: z.string().optional(),
+  /** Max AI assistant document upload size in megabytes (default 5). */
+  UPLOAD_MAX_AGENT_DOCUMENT_MB: z.string().optional(),
+  /** Max org landing page image upload size in megabytes (default 0.5). */
+  UPLOAD_MAX_LANDING_IMAGE_MB: z.string().optional(),
+  /** Max media thumbnail upload size in megabytes (default 5). */
+  UPLOAD_MAX_THUMBNAIL_MB: z.string().optional()
 });
 
 export const env = envSchema.parse(process.env);

packages/core/src/config/upload-limits.ts

@@ -0,0 +1,15 @@
+import { env } from './env';
+import { resolveUploadLimits, type UploadLimits } from '@cio/utils/config/upload-limits';
+
+export type { UploadLimits } from '@cio/utils/config/upload-limits';
+
+let cachedLimits: UploadLimits | null = null;
+
+export function getUploadLimits(): UploadLimits {
+  if (cachedLimits) {
+    return cachedLimits;
+  }
+
+  cachedLimits = resolveUploadLimits(env);
+  return cachedLimits;
+}

packages/core/src/services/agent/document.ts

@@ -1,12 +1,8 @@
 import { nanoid } from 'nanoid';
 import { AppError } from '@cio/utils/errors';
-import {
-  MAX_DOCUMENT_TEXT_LENGTH,
-  MAX_AGENT_DOCUMENT_SIZE,
-  DOCUMENT_REDIS_TTL,
-  SUPPORTED_DOCUMENT_TYPES
-} from '@cio/ai-assistant';
+import { MAX_DOCUMENT_TEXT_LENGTH, DOCUMENT_REDIS_TTL, SUPPORTED_DOCUMENT_TYPES } from '@cio/ai-assistant';
 import type { DocumentUploadResult } from '@cio/ai-assistant';
+import { getUploadLimits } from '../../config/upload-limits';
 import { agentDocumentKey } from '../../utils/redis-keys';
 import { trackAgentEvent, AgentEvent } from '../../utils/tinybird';
 import type { RedisClient } from '../../utils/redis/redis';
@@ -34,9 +30,11 @@ export async function parseAndStoreDocument(
     throw new AppError('Unsupported file type. Allowed: PDF, DOCX, PPTX', 'UNSUPPORTED_FILE_TYPE', 415);
   }
 
-  if (file.size > MAX_AGENT_DOCUMENT_SIZE) {
+  const maxAgentDocumentSize = getUploadLimits().agentDocumentBytes;
+
+  if (file.size > maxAgentDocumentSize) {
     throw new AppError(
-      `File too large. Maximum size is ${MAX_AGENT_DOCUMENT_SIZE / (1024 * 1024)}MB`,
+      `File too large. Maximum size is ${maxAgentDocumentSize / (1024 * 1024)}MB`,
       'FILE_TOO_LARGE',
       413
     );

packages/question-types/src/exercise-types.ts

@@ -257,6 +257,8 @@ export interface ExerciseQuestionRendererProps {
   maxSubmissionItems?: number;
   disabled?: boolean;
   labels?: ExerciseQuestionLabels;
+  /** Platform-wide cap for exercise file uploads (megabytes). */
+  platformMaxFileSizeMb?: number;
   onAnswerChange?: (answer: AnswerData | null) => void;
   onQuestionChange?: (question: ExerciseQuestionModel) => void;
   onImageUpload?: ExerciseQuestionImageUploader;

packages/question-types/src/render-contract.ts

@@ -18,6 +18,8 @@ export interface ExerciseQuestionRenderContract {
   maxSubmissionItems?: number;
   disabled?: boolean;
   labels?: ExerciseQuestionLabels;
+  /** Platform-wide cap for exercise file uploads (megabytes). */
+  platformMaxFileSizeMb?: number;
   onImageUpload?: ExerciseQuestionImageUploader;
   onFileUpload?: ExerciseQuestionFileUploader;
   onVideoRecordingUpload?: ExerciseQuestionVideoRecordingUploader;
@@ -31,6 +33,8 @@ export interface ExerciseQuestionListRenderContract {
   maxSubmissionItems?: number;
   disabled?: boolean;
   labels?: ExerciseQuestionLabels;
+  /** Platform-wide cap for exercise file uploads (megabytes). */
+  platformMaxFileSizeMb?: number;
   onImageUpload?: ExerciseQuestionImageUploader;
   onFileUpload?: ExerciseQuestionFileUploader;
   onVideoRecordingUpload?: ExerciseQuestionVideoRecordingUploader;

packages/ui/src/custom/exercise-question/question-list.svelte

@@ -32,6 +32,7 @@
         maxSubmissionItems: contract.maxSubmissionItems,
         disabled: contract.disabled,
         labels: contract.labels,
+        platformMaxFileSizeMb: contract.platformMaxFileSizeMb,
         onImageUpload: contract.onImageUpload,
         onFileUpload: contract.onFileUpload,
         onVideoRecordingUpload: contract.onVideoRecordingUpload

packages/ui/src/custom/exercise-question/question-renderer.svelte

@@ -475,6 +475,7 @@
     maxSubmissionItems={contract.maxSubmissionItems}
     disabled={contract.disabled}
     labels={contract.labels}
+    platformMaxFileSizeMb={contract.platformMaxFileSizeMb}
     onImageUpload={contract.onImageUpload}
     onFileUpload={contract.onFileUpload}
     onVideoRecordingUpload={contract.onVideoRecordingUpload}

packages/ui/src/custom/exercise-question/renderers/file-upload-types.ts

@@ -1,4 +1,6 @@
-export const FILE_UPLOAD_MAX_SIZE_MB = 2;
+export const FILE_UPLOAD_DEFAULT_MAX_SIZE_MB = 2;
+/** @deprecated Use FILE_UPLOAD_DEFAULT_MAX_SIZE_MB */
+export const FILE_UPLOAD_MAX_SIZE_MB = FILE_UPLOAD_DEFAULT_MAX_SIZE_MB;
 
 export const FILE_UPLOAD_SUPPORTED_TYPES = [
   { value: 'application/pdf', label: 'PDF (.pdf)', aliases: ['pdf', '.pdf'] },
@@ -106,10 +108,25 @@ export function isFileTypeAllowed(file: File, acceptedTypes: string[]): boolean
 
 const BYTES_PER_MB = 1024 * 1024;
 
-export function isFileSizeAllowed(file: File, maxSizeMb: number | undefined | null): boolean {
-  const effectiveMaxMb = Math.min(
-    typeof maxSizeMb === 'number' && maxSizeMb > 0 ? maxSizeMb : FILE_UPLOAD_MAX_SIZE_MB,
-    FILE_UPLOAD_MAX_SIZE_MB
-  );
+export function resolveExerciseFileUploadMaxSizeMb(
+  questionMaxSizeMb: number | undefined | null,
+  platformMaxSizeMb: number = FILE_UPLOAD_DEFAULT_MAX_SIZE_MB
+): number {
+  const effectivePlatformMax =
+    typeof platformMaxSizeMb === 'number' && platformMaxSizeMb > 0
+      ? platformMaxSizeMb
+      : FILE_UPLOAD_DEFAULT_MAX_SIZE_MB;
+  const requestedMax =
+    typeof questionMaxSizeMb === 'number' && questionMaxSizeMb > 0 ? questionMaxSizeMb : effectivePlatformMax;
+
+  return Math.min(requestedMax, effectivePlatformMax);
+}
+
+export function isFileSizeAllowed(
+  file: File,
+  maxSizeMb: number | undefined | null,
+  platformMaxSizeMb: number = FILE_UPLOAD_DEFAULT_MAX_SIZE_MB
+): boolean {
+  const effectiveMaxMb = resolveExerciseFileUploadMaxSizeMb(maxSizeMb, platformMaxSizeMb);
   return file.size <= effectiveMaxMb * BYTES_PER_MB;
 }

packages/ui/src/custom/exercise-question/renderers/file-upload/edit.svelte

@@ -12,10 +12,17 @@
   import {
     FILE_UPLOAD_SUPPORTED_TYPES,
     formatAcceptedFileTypes,
-    normalizeAcceptedFileTypes
+    normalizeAcceptedFileTypes,
+    resolveExerciseFileUploadMaxSizeMb
   } from '../file-upload-types';
 
-  let { question, disabled = false, labels, onQuestionChange = () => {} }: ExerciseQuestionRendererProps = $props();
+  let {
+    question,
+    disabled = false,
+    labels,
+    platformMaxFileSizeMb,
+    onQuestionChange = () => {}
+  }: ExerciseQuestionRendererProps = $props();
   const label = (key: Parameters<typeof getExerciseQuestionLabel>[1], fallback = '') =>
     getExerciseQuestionLabel(labels, key, fallback);
   const acceptedTypes = $derived(normalizeAcceptedFileTypes(question.settings?.acceptedTypes));
@@ -41,17 +48,19 @@
     patchSettings({ acceptedTypes: nextAcceptedTypes });
   }
 
+  const platformMaxMb = $derived(resolveExerciseFileUploadMaxSizeMb(undefined, platformMaxFileSizeMb));
+
   const rawMaxSize = $derived(question.settings?.maxSizeMb as number | undefined);
   const maxSizeMb = $derived(
     typeof rawMaxSize === 'number' && !Number.isNaN(rawMaxSize) && rawMaxSize >= 0
-      ? String(Math.min(rawMaxSize, 2))
+      ? String(Math.min(rawMaxSize, platformMaxMb))
       : ''
   );
 
   $effect(() => {
     const raw = question.settings?.maxSizeMb as number | undefined;
-    if (typeof raw === 'number' && raw > 2) {
-      patchSettings({ maxSizeMb: 2 });
+    if (typeof raw === 'number' && raw > platformMaxMb) {
+      patchSettings({ maxSizeMb: platformMaxMb });
     }
   });
 
@@ -61,7 +70,7 @@
       patchSettings({ maxSizeMb: undefined });
       return;
     }
-    patchSettings({ maxSizeMb: Math.min(2, Math.max(0, num)) });
+    patchSettings({ maxSizeMb: Math.min(platformMaxMb, Math.max(0, num)) });
   }
 </script>
 
@@ -107,7 +116,7 @@
       <Input
         type="number"
         min="0"
-        max="2"
+        max={platformMaxMb}
         step="0.1"
         placeholder={label('file_upload.edit.max_size_placeholder')}
         value={maxSizeMb}

packages/ui/src/custom/exercise-question/renderers/file-upload/take.svelte

@@ -11,6 +11,7 @@
     answer = null,
     disabled = false,
     labels,
+    platformMaxFileSizeMb,
     onAnswerChange = () => {},
     onFileUpload
   }: ExerciseQuestionRendererProps = $props();
@@ -86,7 +87,7 @@
 
     if (!selectedFile) return;
     if (!isFileTypeAllowed(selectedFile, acceptedTypes)) return;
-    if (!isFileSizeAllowed(selectedFile, maxSizeMb)) return;
+    if (!isFileSizeAllowed(selectedFile, maxSizeMb, platformMaxFileSizeMb)) return;
 
     if (!onFileUpload) return;
 

packages/utils/package.json

@@ -52,6 +52,10 @@
     "./errors": {
       "types": "./dist/errors/index.d.ts",
       "default": "./dist/errors/index.js"
+    },
+    "./config/upload-limits": {
+      "types": "./dist/config/upload-limits.d.ts",
+      "default": "./dist/config/upload-limits.js"
     }
   },
   "scripts": {

packages/utils/src/config/upload-limits.ts

@@ -0,0 +1,69 @@
+const BYTES_PER_MB = 1024 * 1024;
+
+function parseUploadLimitMb(value: string | undefined, defaultMb: number): number {
+  if (value === undefined || value === '') {
+    return defaultMb;
+  }
+
+  const parsed = Number(value);
+
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return defaultMb;
+  }
+
+  return parsed;
+}
+
+export type UploadLimits = {
+  documentMb: number;
+  imageMb: number;
+  videoMb: number;
+  exerciseFileMb: number;
+  agentDocumentMb: number;
+  landingImageMb: number;
+  thumbnailMb: number;
+  documentBytes: number;
+  imageBytes: number;
+  videoBytes: number;
+  exerciseFileBytes: number;
+  agentDocumentBytes: number;
+  landingImageBytes: number;
+  thumbnailBytes: number;
+};
+
+export type UploadLimitEnv = {
+  UPLOAD_MAX_DOCUMENT_MB?: string;
+  UPLOAD_MAX_IMAGE_MB?: string;
+  UPLOAD_MAX_VIDEO_MB?: string;
+  UPLOAD_MAX_EXERCISE_FILE_MB?: string;
+  UPLOAD_MAX_AGENT_DOCUMENT_MB?: string;
+  UPLOAD_MAX_LANDING_IMAGE_MB?: string;
+  UPLOAD_MAX_THUMBNAIL_MB?: string;
+};
+
+export function resolveUploadLimits(env: UploadLimitEnv): UploadLimits {
+  const documentMb = parseUploadLimitMb(env.UPLOAD_MAX_DOCUMENT_MB, 5);
+  const imageMb = parseUploadLimitMb(env.UPLOAD_MAX_IMAGE_MB, 5);
+  const videoMb = parseUploadLimitMb(env.UPLOAD_MAX_VIDEO_MB, 800);
+  const exerciseFileMb = parseUploadLimitMb(env.UPLOAD_MAX_EXERCISE_FILE_MB, 2);
+  const agentDocumentMb = parseUploadLimitMb(env.UPLOAD_MAX_AGENT_DOCUMENT_MB, 5);
+  const landingImageMb = parseUploadLimitMb(env.UPLOAD_MAX_LANDING_IMAGE_MB, 0.5);
+  const thumbnailMb = parseUploadLimitMb(env.UPLOAD_MAX_THUMBNAIL_MB, 5);
+
+  return {
+    documentMb,
+    imageMb,
+    videoMb,
+    exerciseFileMb,
+    agentDocumentMb,
+    landingImageMb,
+    thumbnailMb,
+    documentBytes: documentMb * BYTES_PER_MB,
+    imageBytes: imageMb * BYTES_PER_MB,
+    videoBytes: videoMb * BYTES_PER_MB,
+    exerciseFileBytes: exerciseFileMb * BYTES_PER_MB,
+    agentDocumentBytes: agentDocumentMb * BYTES_PER_MB,
+    landingImageBytes: landingImageMb * BYTES_PER_MB,
+    thumbnailBytes: thumbnailMb * BYTES_PER_MB
+  };
+}

packages/utils/src/validation/course/course.ts

@@ -127,13 +127,15 @@ export type TLessonDownloadContent = z.infer<typeof ZLessonDownloadContent>;
 
 export const ZCoursePresignUrlUpload = z.object({
   fileName: z.string().min(1),
-  fileType: z.enum(ALLOWED_CONTENT_TYPES)
+  fileType: z.enum(ALLOWED_CONTENT_TYPES),
+  fileSize: z.number().int().min(0).optional()
 });
 export type TCoursePresignUrlUpload = z.infer<typeof ZCoursePresignUrlUpload>;
 
 export const ZCourseDocumentPresignUrlUpload = z.object({
   fileName: z.string().min(1),
-  fileType: z.enum(ALLOWED_DOCUMENT_TYPES)
+  fileType: z.enum(ALLOWED_DOCUMENT_TYPES),
+  fileSize: z.number().int().min(0).optional()
 });
 export type TCourseDocumentPresignUrlUpload = z.infer<typeof ZCourseDocumentPresignUrlUpload>;