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 <rotimi-best@users.noreply.github.com>

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

Co-authored-by: Rotimi Best <rotimi-best@users.noreply.github.com>

* 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

---------

apps/api/.env.example

@@ -89,6 +89,15 @@ MOONSHOT_API_KEY=""
 # AGENT_MAX_FETCHES_PER_CONVERSATION=15
 # AGENT_MAX_FETCHES_PER_ORG_PER_DAY=500
 
+# Upload file size limits (megabytes). Set these on both API and dashboard for self-hosted installs.
+# UPLOAD_MAX_DOCUMENT_MB=5
+# UPLOAD_MAX_IMAGE_MB=5
+# UPLOAD_MAX_VIDEO_MB=800
+# UPLOAD_MAX_EXERCISE_FILE_MB=2
+# UPLOAD_MAX_AGENT_DOCUMENT_MB=5
+# UPLOAD_MAX_LANDING_IMAGE_MB=0.5
+# UPLOAD_MAX_THUMBNAIL_MB=5
+
 # Tinybird event tracking for AI observability (optional — silently skipped when not set)
 # TINYBIRD_TOKEN=""
 # TINYBIRD_BASE_URL="https://api.tinybird.co"

apps/api/src/constants/upload.ts

@@ -1,7 +1,15 @@
+import { getUploadLimits } from '@cio/core/config/upload-limits';
+
+const limits = getUploadLimits();
+
 // API-specific constants (file size limits)
-export const MAX_FILE_SIZE = 800 * 1024 * 1024; // 800MB
-export const MAX_DOCUMENT_SIZE = 5 * 1024 * 1024; // 5MB
-export const MAX_IMAGE_SIZE = 5 * 1024 * 1024; // 5MB
+export const MAX_FILE_SIZE = limits.videoBytes;
+export const MAX_DOCUMENT_SIZE = limits.documentBytes;
+export const MAX_IMAGE_SIZE = limits.imageBytes;
+export const MAX_EXERCISE_FILE_SIZE = limits.exerciseFileBytes;
+export const MAX_AGENT_DOCUMENT_SIZE = limits.agentDocumentBytes;
+
+export { getUploadLimits };
 
 // API-specific constants (bucket names)
 export const BUCKET_NAME = {

apps/api/src/routes/agent/agent.ts

@@ -6,6 +6,7 @@ import { orgAdminMiddleware } from '@api/middlewares/org-admin';
 import { authOrApiKeyMiddleware } from '@api/middlewares/auth-or-api-key';
 import { b64EnvelopeRewrite } from '@api/middlewares/b64-envelope';
 import { handleError, AppError } from '@api/utils/errors';
+import { MAX_AGENT_DOCUMENT_SIZE } from '@api/constants/upload';
 import { zValidator } from '@hono/zod-validator';
 import { streamText, stepCountIs, convertToModelMessages } from 'ai';
 import {
@@ -171,7 +172,7 @@ const agentCoreRouter = new Hono()
     } catch (error) {
       if (error instanceof AppError) {
         if (error.statusCode === 413) {
-          return c.json({ success: false, error: 'file_too_large', maxSize: 5242880 }, 413);
+          return c.json({ success: false, error: 'file_too_large', maxSize: MAX_AGENT_DOCUMENT_SIZE }, 413);
         }
 
         if (error.statusCode === 415) {

apps/api/src/routes/course/presign.ts

@@ -14,6 +14,19 @@ import {
 import { Hono } from '@api/utils/hono';
 import { authMiddleware } from '@api/middlewares/auth';
 import { generateFileKey } from '@cio/core/utils/upload';
+import { AppError } from '@api/utils/errors';
+import { MAX_DOCUMENT_SIZE, MAX_FILE_SIZE } from '@api/constants/upload';
+
+/**
+ * Advisory check on client-reported `fileSize`. Upload bytes go directly to object storage
+ * via the presigned PUT URL, so omitting `fileSize` (or understating it) bypasses this guard.
+ * Real enforcement requires storage-side policies (bucket max object size, etc.).
+ */
+function assertPresignFileSizeWithinLimit(fileSize: number | undefined, maxBytes: number): void {
+  if (fileSize != null && fileSize > maxBytes) {
+    throw new AppError(`File size exceeds maximum of ${maxBytes / 1024 / 1024}MB`, 'FILE_TOO_LARGE', 413);
+  }
+}
 
 // Response schemas for OpenAPI documentation
 const PresignUploadResponse = {
@@ -68,7 +81,10 @@ export const presignRouter = new Hono()
     async (c) => {
       const body = c.req.valid('json');
 
-      const { fileName, fileType } = body;
+      const { fileName, fileType, fileSize } = body;
+
+      assertPresignFileSizeWithinLimit(fileSize, MAX_FILE_SIZE);
+
       const fileKey = generateFileKey(fileName);
 
       const presignedUrl = await generateVideoUploadPresignedUrl(fileKey, fileType);
@@ -108,7 +124,10 @@ export const presignRouter = new Hono()
     async (c) => {
       const body = c.req.valid('json');
 
-      const { fileName, fileType } = body;
+      const { fileName, fileType, fileSize } = body;
+
+      assertPresignFileSizeWithinLimit(fileSize, MAX_DOCUMENT_SIZE);
+
       const fileKey = generateFileKey(fileName);
 
       const presignedUrl = await generateDocumentUploadPresignedUrl(fileKey, fileType);

apps/dashboard/.env.example

@@ -52,3 +52,12 @@ PUBLIC_SENTRY_ENVIRONMENT=production
 PUBLIC_SENTRY_TRACES_SAMPLE_RATE=0
 PUBLIC_SENTRY_REPLAYS_SESSION_SAMPLE_RATE=0
 PUBLIC_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=1
+
+# Upload file size limits (megabytes). Must match apps/api/.env for self-hosted installs.
+# UPLOAD_MAX_DOCUMENT_MB=5
+# UPLOAD_MAX_IMAGE_MB=5
+# UPLOAD_MAX_VIDEO_MB=800
+# UPLOAD_MAX_EXERCISE_FILE_MB=2
+# UPLOAD_MAX_AGENT_DOCUMENT_MB=5
+# UPLOAD_MAX_LANDING_IMAGE_MB=0.5
+# UPLOAD_MAX_THUMBNAIL_MB=5

apps/dashboard/src/lib/features/course/api/presign.svelte.ts

@@ -15,11 +15,11 @@ export class PresignApi extends BaseApiWithErrors {
    * Gets a presigned upload URL for a document.
    * @returns { url, fileKey } on success
    */
-  async getDocumentUploadUrl(fileName: string, fileType: string) {
+  async getDocumentUploadUrl(fileName: string, fileType: string, fileSize?: number) {
     const result = await this.execute<DocumentUploadPresignRequest>({
       requestFn: () =>
         classroomio.course.presign.document.upload.$post({
-          json: { fileName, fileType }
+          json: { fileName, fileType, ...(fileSize != null && fileSize > 0 ? { fileSize } : {}) }
         }),
       logContext: 'getting document upload URL'
     });
@@ -47,11 +47,11 @@ export class PresignApi extends BaseApiWithErrors {
    * Gets a presigned upload URL for a video.
    * @returns { url, fileKey } on success
    */
-  async getVideoUploadUrl(fileName: string, fileType: string) {
+  async getVideoUploadUrl(fileName: string, fileType: string, fileSize?: number) {
     const result = await this.execute<VideoUploadPresignRequest>({
       requestFn: () =>
         classroomio.course.presign.video.upload.$post({
-          json: { fileName, fileType }
+          json: { fileName, fileType, ...(fileSize != null && fileSize > 0 ? { fileSize } : {}) }
         }),
       logContext: 'getting video upload URL'
     });

apps/dashboard/src/lib/features/course/components/exercise/edit-mode.svelte

@@ -44,8 +44,11 @@
   import SectionEditor from './section-editor.svelte';
   import type { Question } from '$features/course/types';
   import type { ExerciseEditorErrors } from './store';
+  import { getResolvedUploadLimits } from '$lib/utils/config/upload-limits-context';
 
   const flipDurationMs = 200;
+  const uploadLimits = getResolvedUploadLimits();
+  const platformMaxFileSizeMb = uploadLimits.exerciseFileMb;
   const initialQuestionsLength = $questionnaire.questions.length;
   type QuestionDndEvent = CustomEvent<{ items: Question[] }>;
 
@@ -390,6 +393,7 @@
           mode: 'edit',
           question: toExerciseQuestionModel(question),
           labels: questionLabels,
+          platformMaxFileSizeMb,
           onImageUpload: uploadImage
         }}
         onQuestionChange={(nextQuestion) => onSharedQuestionChange(question.id, nextQuestion)}

apps/dashboard/src/lib/features/course/components/exercise/view-mode.svelte

@@ -54,6 +54,7 @@
   import ChevronLeftIcon from '@lucide/svelte/icons/chevron-left';
   import ChevronRightIcon from '@lucide/svelte/icons/chevron-right';
   import type { Question } from '$features/course/types';
+  import { getResolvedUploadLimits } from '$lib/utils/config/upload-limits-context';
 
   interface Props {
     preview?: boolean;
@@ -65,6 +66,9 @@
 
   let { preview = false, exerciseId = '', isFetchingExercise = false, mySubmissions = [] }: Props = $props();
 
+  const uploadLimits = getResolvedUploadLimits();
+  const platformMaxFileSizeMb = uploadLimits.exerciseFileMb;
+
   let isSubmitting = $state(false);
   /** When true, do not re-apply a past submission over a fresh take (Try again). */
   let skipHydrateFromSubmissions = $state(false);
@@ -305,7 +309,8 @@
       file.type as
         | 'application/pdf'
         | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
-        | 'application/msword'
+        | 'application/msword',
+      file.size > 0 ? file.size : undefined
     );
     if (!uploadResult) {
       throw new Error('Failed to get upload URL');
@@ -946,6 +951,7 @@
             answer: $questionnaireMetaData.answers[sectionQuestionKey],
             labels: questionLabels,
             disabled: isSubmitting,
+            platformMaxFileSizeMb,
             onFileUpload: handleFileUpload,
             onVideoRecordingUpload: handleVideoRecordingUpload
           }}
@@ -1002,6 +1008,7 @@
                   answer: sharedCurrentAnswer,
                   labels: questionLabels,
                   disabled: isSubmitting,
+                  platformMaxFileSizeMb,
                   onFileUpload: handleFileUpload,
                   onVideoRecordingUpload: handleVideoRecordingUpload
                 }}

apps/dashboard/src/lib/features/course/components/lesson/document/add-document-modal.svelte

@@ -14,6 +14,7 @@
   import * as Dialog from '@cio/ui/base/dialog';
   import * as FileDropZone from '@cio/ui/custom/file-drop-zone';
   import type { FileRejectedReason } from '@cio/ui/custom/file-drop-zone';
+  import { getResolvedUploadLimits } from '$lib/utils/config/upload-limits-context';
 
   interface Props {
     lessonId?: string;
@@ -34,7 +35,8 @@
     'application/msword'
   ];
 
-  const MAX_DOCUMENT_SIZE = 5 * 1024 * 1024; // 5MB
+  const uploadLimits = getResolvedUploadLimits();
+  const maxDocumentSize = uploadLimits.documentBytes;
 
   const documentUploader = new DocumentUploader();
 
@@ -58,9 +60,9 @@
       return $t('course.navItem.lessons.materials.tabs.document.file_type_error');
     }
 
-    if (file.size > MAX_DOCUMENT_SIZE) {
+    if (file.size > maxDocumentSize) {
       return $t('course.navItem.lessons.materials.tabs.document.file_size_error', {
-        size: formatFileSize(MAX_DOCUMENT_SIZE)
+        size: formatFileSize(maxDocumentSize)
       });
     }
 
@@ -87,7 +89,7 @@
     if (opts.reason === 'Maximum file size exceeded') {
       snackbar.error(
         $t('course.navItem.lessons.materials.tabs.document.file_size_error', {
-          size: formatFileSize(MAX_DOCUMENT_SIZE)
+          size: formatFileSize(maxDocumentSize)
         })
       );
     } else if (opts.reason === 'File type not allowed') {
@@ -259,7 +261,7 @@
             accept=".pdf,.docx,.doc,application/pdf,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/msword"
             maxFiles={1}
             fileCount={0}
-            maxFileSize={MAX_DOCUMENT_SIZE}
+            maxFileSize={maxDocumentSize}
             onUpload={handleFilesUpload}
             onFileRejected={handleFileRejected}
           >

apps/dashboard/src/lib/features/course/components/lesson/video/upload-video.svelte

@@ -14,6 +14,7 @@
   import { mediaApi } from '$features/media/api';
   import { JobPoller, jobsApi, type MediaJobEnvelope } from '$features/jobs';
   import { onDestroy } from 'svelte';
+  import { getResolvedUploadLimits } from '$lib/utils/config/upload-limits-context';
 
   const ADD_VIDEO = 'course.navItem.lessons.materials.tabs.video.add_video';
   const PROCESSING_BASE = `${ADD_VIDEO}.processing`;
@@ -50,6 +51,9 @@
 
   const isDisabled = $derived($lessonVideoUpload.isUploading || $isFreePlan);
 
+  const uploadLimits = getResolvedUploadLimits();
+  const maxVideoSize = uploadLimits.videoBytes;
+
   const videoUploader = new VideoUploader();
   const mediaUploader = new MediaUploader();
 
@@ -401,7 +405,7 @@
         accept="video/*"
         maxFiles={1}
         fileCount={0}
-        maxFileSize={800 * FileDropZone.MEGABYTE}
+        maxFileSize={maxVideoSize}
         onUpload={handleUpload}
         {onFileRejected}
       >

apps/dashboard/src/lib/features/media/components/edit-asset-dialog.svelte

@@ -12,6 +12,7 @@
   import { snackbar } from '$features/ui/snackbar/store';
   import { t } from '$lib/utils/functions/translations';
   import { uploadImage } from '$lib/utils/services/upload';
+  import { getResolvedUploadLimits } from '$lib/utils/config/upload-limits-context';
 
   interface Props {
     open?: boolean;
@@ -22,7 +23,8 @@
 
   type AssetStatusValue = 'active' | 'archived';
 
-  const THUMBNAIL_MAX_SIZE = 5 * FileDropZone.MEGABYTE;
+  const uploadLimits = getResolvedUploadLimits();
+  const thumbnailMaxSize = uploadLimits.thumbnailBytes;
 
   let { open = $bindable(false), asset = null, isSaving = false, onSave = async () => {} }: Props = $props();
 
@@ -126,7 +128,7 @@
               accept={FileDropZone.ACCEPT_IMAGE}
               maxFiles={1}
               fileCount={0}
-              maxFileSize={THUMBNAIL_MAX_SIZE}
+              maxFileSize={thumbnailMaxSize}
               onUpload={handleThumbnailFilesUpload}
               onFileRejected={handleThumbnailRejected}
             >

apps/dashboard/src/lib/features/media/components/manage-thumbnails-dialog.svelte

@@ -14,6 +14,7 @@
   import { t } from '$lib/utils/functions/translations';
   import { uploadImage } from '$lib/utils/services/upload';
   import { classroomio } from '$lib/utils/services/api';
+  import { getResolvedUploadLimits } from '$lib/utils/config/upload-limits-context';
 
   function buildHlsUrl(asset: OrganizationAsset): string | null {
     if (!asset.hlsManifestKey) return null;
@@ -32,7 +33,8 @@
     onThumbnailSaved?: (asset: OrganizationAsset) => void;
   }
 
-  const THUMBNAIL_MAX_SIZE = 1 * FileDropZone.MEGABYTE;
+  const uploadLimits = getResolvedUploadLimits();
+  const thumbnailMaxSize = uploadLimits.thumbnailBytes;
   const REGEN_POLL_INTERVAL_MS = 2000;
   const REGEN_POLL_TIMEOUT_MS = 60_000;
   const SLOT_KEYS = ['start', 'middle', 'end'] as const;
@@ -289,7 +291,7 @@
                 accept={FileDropZone.ACCEPT_IMAGE}
                 maxFiles={1}
                 fileCount={0}
-                maxFileSize={THUMBNAIL_MAX_SIZE}
+                maxFileSize={thumbnailMaxSize}
                 onUpload={handleCustomUpload}
                 onFileRejected={handleUploadRejected}
               >

apps/dashboard/src/lib/features/ui/upload-widget/upload-widget.svelte

@@ -14,6 +14,7 @@
   import { InputField } from '@cio/ui/custom/input-field';
   import { Button } from '@cio/ui/base/button';
   import UploadCloudIcon from '@lucide/svelte/icons/upload-cloud';
+  import { getResolvedUploadLimits } from '$lib/utils/config/upload-limits-context';
 
   interface Props {
     imageURL?: string;
@@ -48,7 +49,8 @@
     alt_description: string;
   }[] = $state([]);
 
-  const MAX_IMAGE_SIZE = 500 * 1000;
+  const uploadLimits = getResolvedUploadLimits();
+  const maxLandingImageSize = uploadLimits.landingImageBytes;
 
   async function handleImageClick(img: string) {
     onchange?.(img);
@@ -58,7 +60,7 @@
   }
 
   function handleUnsupportedFile(file: File) {
-    if (file.size > MAX_IMAGE_SIZE) {
+    if (file.size > maxLandingImageSize) {
       snackbar.error('snackbar.landing_page_settings.error.file_size');
       return;
     }
@@ -130,7 +132,7 @@
               bind:src={cropperSrc}
               onCropped={handleCropped}
               onUnsupportedFile={handleUnsupportedFile}
-              maxFileSize={MAX_IMAGE_SIZE}
+              maxFileSize={maxLandingImageSize}
               accept=".jpg, .jpeg, .png, .webp"
               disabled={isUploading}
             >

apps/dashboard/src/lib/utils/config/upload-limits-context.ts

@@ -0,0 +1,23 @@
+import { getContext, setContext } from 'svelte';
+import { resolveUploadLimits, type UploadLimits } from '@cio/utils/config/upload-limits';
+import type { UploadLimits as DashboardUploadLimits } from './upload-limits';
+
+const UPLOAD_LIMITS_CONTEXT_KEY = Symbol('upload-limits');
+
+export function setUploadLimitsContext(limits: DashboardUploadLimits) {
+  setContext(UPLOAD_LIMITS_CONTEXT_KEY, limits);
+}
+
+export function getUploadLimitsContext(): DashboardUploadLimits | null {
+  return getContext<DashboardUploadLimits | null>(UPLOAD_LIMITS_CONTEXT_KEY) ?? null;
+}
+
+/** Built-in defaults when layout context is absent (e.g. Storybook, isolated tests). */
+export function getDefaultUploadLimits(): UploadLimits {
+  return resolveUploadLimits({});
+}
+
+/** Layout-provided limits, or built-in defaults outside the dashboard layout tree. */
+export function getResolvedUploadLimits(): UploadLimits {
+  return getUploadLimitsContext() ?? getDefaultUploadLimits();
+}

apps/dashboard/src/lib/utils/config/upload-limits.ts

@@ -0,0 +1,24 @@
+import { resolveUploadLimits, type UploadLimits } from '@cio/utils/config/upload-limits';
+import { env } from '$env/dynamic/private';
+
+let cachedLimits: UploadLimits | null = null;
+
+export function getUploadLimits(): UploadLimits {
+  if (cachedLimits) {
+    return cachedLimits;
+  }
+
+  cachedLimits = resolveUploadLimits({
+    UPLOAD_MAX_DOCUMENT_MB: env.UPLOAD_MAX_DOCUMENT_MB,
+    UPLOAD_MAX_IMAGE_MB: env.UPLOAD_MAX_IMAGE_MB,
+    UPLOAD_MAX_VIDEO_MB: env.UPLOAD_MAX_VIDEO_MB,
+    UPLOAD_MAX_EXERCISE_FILE_MB: env.UPLOAD_MAX_EXERCISE_FILE_MB,
+    UPLOAD_MAX_AGENT_DOCUMENT_MB: env.UPLOAD_MAX_AGENT_DOCUMENT_MB,
+    UPLOAD_MAX_LANDING_IMAGE_MB: env.UPLOAD_MAX_LANDING_IMAGE_MB,
+    UPLOAD_MAX_THUMBNAIL_MB: env.UPLOAD_MAX_THUMBNAIL_MB
+  });
+
+  return cachedLimits;
+}
+
+export type { UploadLimits };

apps/dashboard/src/lib/utils/services/courses/presign.ts

@@ -52,8 +52,12 @@ export class GenericUploader {
   async getPresignedUrl(file: File) {
     const result =
       this.uploadType === 'document'
-        ? await presignApi.getDocumentUploadUrl(file?.name ?? '', file?.type ?? '')
-        : await presignApi.getVideoUploadUrl(file?.name ?? '', file?.type ?? '');
+        ? await presignApi.getDocumentUploadUrl(
+            file?.name ?? '',
+            file?.type ?? '',
+            file.size > 0 ? file.size : undefined
+          )
+        : await presignApi.getVideoUploadUrl(file?.name ?? '', file?.type ?? '', file.size > 0 ? file.size : undefined);
 
     if (!result) {
       throw new Error('Failed to get presigned upload URL');

apps/dashboard/src/routes/+layout.server.ts

@@ -1,8 +1,10 @@
 import type { AccountOrg } from '$features/app/types';
 import type { MetaTagsProps } from 'svelte-meta-tags';
+import type { UploadLimits } from '$lib/utils/config/upload-limits';
 import { PUBLIC_IS_SELFHOSTED } from '$env/static/public';
 import { getBaseMetaTags } from '$lib/utils/functions/metaTags';
 import { getOrgSiteInfo } from '$features/app/layout-setup';
+import { getUploadLimits } from '$lib/utils/config/upload-limits';
 
 export const ssr = true;
 
@@ -15,6 +17,7 @@ interface LoadOutput {
   serverLang: string;
   localeCookie: string;
   locals: App.Locals;
+  uploadLimits: UploadLimits;
 }
 
 export const load = async ({ url, cookies, request, locals }): Promise<LoadOutput> => {
@@ -33,7 +36,8 @@ export const load = async ({ url, cookies, request, locals }): Promise<LoadOutpu
     baseMetaTags: getBaseMetaTags(url, orgSiteInfo),
     serverLang: request.headers?.get('accept-language') || '',
     localeCookie: cookies.get('classroomio_locale') || '',
-    locals
+    locals,
+    uploadLimits: getUploadLimits()
   };
 
   const loadMs = Math.round((performance.now() - loadStart) * 100) / 100;

apps/dashboard/src/routes/+layout.svelte

@@ -16,8 +16,12 @@
 
   import '../app.css';
 
+  import { setUploadLimitsContext } from '$lib/utils/config/upload-limits-context';
+
   let { data, children } = $props();
 
+  setUploadLimitsContext(data.uploadLimits);
+
   const metaTags = $derived(merge(data.baseMetaTags, page.data.pageMetaTags));
 
   onMount(() => {

apps/docs/content/docs/self-hosted/coolify.mdx

@@ -46,6 +46,9 @@ import { Callout } from 'fumadocs-ui/components/callout';
    storage instead? Point the same `OBJECT_STORAGE_*` variables at external **S3 / Cloudflare R2**
    and leave the `minio` profile off — see the [Cloudflare Setup](/docs/contributor-guides/cloudflare-setup) guide for R2.
 
+   **Upload size limits** (optional): set `UPLOAD_MAX_*_MB` in Coolify's env for both the `api` and
+   `dashboard` services (same values in each). See [Docker self-hosting → Upload file size limits](/docs/self-hosted/docker#optional--upload-file-size-limits).
+
 5. **Deploy.** Coolify pulls `classroomio/{api,dashboard,jobs}:${CIO_VERSION}`, starts Postgres + Redis, the API container runs database setup on first boot, then the dashboard and the **jobs worker** come up.
 
 ## Upgrades & rollback

apps/docs/content/docs/self-hosted/docker.mdx

@@ -210,6 +210,25 @@ The bundled **MinIO** is included by default and the startup script auto-configu
 | `LICENSE_KEY` | Enterprise features (SSO, token-auth, no-tracking) |
 | `PUBLIC_APP_TITLE`, `PUBLIC_APP_DESCRIPTION`, `PUBLIC_OG_IMAGE_URL` | Custom branding |
 
+### Optional — Upload file size limits
+
+Set these in the root `.env` to raise or lower upload caps (values are in **megabytes**). Compose passes them through to the `api` and `dashboard` containers. Unset = built-in defaults. On [Railway](/docs/self-hosted/railway) or [Coolify](/docs/self-hosted/coolify), set the same variables on both the API and dashboard services.
+
+| Variable | Default | Applies to |
+|----------|---------|------------|
+| `UPLOAD_MAX_DOCUMENT_MB` | 5 | Course lesson documents |
+| `UPLOAD_MAX_IMAGE_MB` | 5 | Avatars, media library, editor images |
+| `UPLOAD_MAX_VIDEO_MB` | 800 | Lesson video uploads |
+| `UPLOAD_MAX_EXERCISE_FILE_MB` | 2 | Student assignment file-upload questions |
+| `UPLOAD_MAX_AGENT_DOCUMENT_MB` | 5 | AI assistant document uploads |
+| `UPLOAD_MAX_LANDING_IMAGE_MB` | 0.5 | Org landing page cover images |
+| `UPLOAD_MAX_THUMBNAIL_MB` | 5 | Media thumbnail uploads |
+
+<Callout type="warn" title="Reverse proxy limits">
+  If you raise these values, also increase your reverse proxy body-size limit (e.g. nginx
+  `client_max_body_size`) so large uploads are not rejected before they reach ClassroomIO.
+</Callout>
+
 ## Common Commands
 
 ```zsh title="Terminal"

apps/docs/content/docs/self-hosted/railway.mdx

@@ -62,6 +62,8 @@ ALLOWED_EXTERNAL_DOMAINS="https://fonts.googleapis.com"
 
 Optional: add `PUBLIC_APP_TITLE`, `PUBLIC_APP_DESCRIPTION`, `PUBLIC_OG_IMAGE_URL` for custom branding. You can also use per-directive CSP vars (`CSP_SCRIPT_SRC_DOMAINS`, `CSP_MEDIA_SRC_DOMAINS`, etc.) instead of `ALLOWED_EXTERNAL_DOMAINS` for finer control.
 
+**Upload size limits** (optional): add the same `UPLOAD_MAX_*_MB` values to **cio-api** and **cio-dashboard** (e.g. `UPLOAD_MAX_DOCUMENT_MB=50`). See [Docker self-hosting → Upload file size limits](/docs/self-hosted/docker#optional--upload-file-size-limits).
+
 ## cio-jobs (background worker)
 
 The jobs worker has **no public domain** — it drains the Redis queue (video processing, transcription, AI course generation, and emails). It shares the same Postgres, Redis, storage, email, and OpenAI settings as the API: