From 101af23418155f390f31fe67c1207b51cd28995b Mon Sep 17 00:00:00 2001 From: Tom Boullay Date: Tue, 12 May 2026 23:48:47 +0200 Subject: [PATCH] docs: clean upload documentation --- Dockerfile | 5 +---- README.md | 12 ++++++------ docker-entrypoint.sh | 2 +- lib/auth.ts | 3 +-- lib/blender.ts | 3 +-- lib/sanitize.ts | 3 +-- 6 files changed, 11 insertions(+), 17 deletions(-) diff --git a/Dockerfile b/Dockerfile index 6fee568..8d5605e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,7 +1,4 @@ -# ============================================================================= -# Upload GLTF — Dockerfile for Coolify -# Node 20 Debian · Blender (headless) · Multi-stage build -# ============================================================================= +# Coolify production image: Next.js standalone app with Blender for Draco compression. # --- Stage 1: Dependencies --------------------------------------------------- FROM node:20-slim AS deps diff --git a/README.md b/README.md index 3125ce1..4e311f1 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ A secure web interface for uploading `model.gltf` with its associated `.bin` fil - **Nextcloud Drive** — Archives the original files with automatic versioning (VF/V1/V2...), so artists always have a history of past versions - **GitHub** — Delivers Draco-compressed GLB assets by default, with an optional GLTF delivery mode for specific models -Built for La Fabrik Durable's internal use, but open-sourced for anyone looking for a similar solution. The app validates the upload locally, stages it server-side, then applies intelligent diffs to avoid unnecessary uploads and commits. The Drive upload serves as the source of truth and version history, while the GitHub upload delivers the prepared assets to developers +Built for La Fabrik Durable's internal use, but open-sourced for anyone looking for a similar solution. The app validates the upload locally, stages it server-side, then compares file diffs to avoid unnecessary uploads and commits. The Drive upload serves as the source of truth and version history, while the GitHub upload delivers the prepared assets to developers. ## Stack @@ -57,7 +57,7 @@ Invalid or unknown asset names still block the upload. ### Upload flow: Drive first, then Git 5. **Drive upload (archiving)** — Original files from the staging area are uploaded to the Nextcloud Drive with automatic versioning (see below). This serves as the artists' source of truth and version history. If the Drive upload fails, a modal asks the user whether to send to Git only or cancel entirely. -6. **Git upload (delivery to devs)** — The prepared Git payload is reused from staging. By default, Blender exports a single `model.glb` with Draco compression. For specific models, "Envoyer en GLTF" keeps the current separate `model.gltf` + `.bin` + compressed textures workflow. +6. **Git upload (delivery to devs)** — The prepared Git payload is reused from staging. By default, Blender exports a single `model.glb` with Draco compression. If Blender cannot process a specific model, the upload falls back to the separate `model.gltf` + `.bin` + compressed textures workflow and shows a warning. For specific models, "Envoyer en GLTF" keeps that separate GLTF delivery mode from the start. ### Drive versioning (Nextcloud WebDAV) @@ -123,13 +123,13 @@ Commit sections: Symbols: `✅` new — `🔄` modified — `↔️` unchanged (model always re-pushed) — `❌` deleted 7. Orphan files (present on remote but not in the new upload) are deleted in the same commit -8. Default Git delivery pushes `model.glb` only; "Envoyer en GLTF" pushes separate `model.gltf`, `.bin`, and compressed textures. +8. Default Git delivery pushes `model.glb` when Blender compression succeeds. If Blender fails, the app falls back to separate `model.gltf`, `.bin`, and compressed textures with a warning. "Envoyer en GLTF" always uses separate GLTF delivery. Uploaded models are pushed to `public/models//` in the target repo. ## Limitations -- Large uploads are faster than before because the folder is staged only once, but the Drive upload remains sequential. +- Large uploads are staged once, but the Drive upload remains sequential. - Git LFS batch uploads are sequential by batch. - Default GLB Draco delivery reduces Git LFS usage by replacing many support files with one compressed model file. - Uploads expect a single `model.gltf` file plus optional flat support files (`.bin`, `.png`, `.jpg`, `.jpeg`, `.webp`). @@ -222,7 +222,7 @@ NEXTCLOUD_BASE_PATH=Models | `UPLOAD_SECRET_KEY` | Secret key for upload authentication | Yes | | `GITHUB_TOKEN` | GitHub Personal Access Token (fine-grained, `Contents: Read and write`) | Yes | | `GIT_BRANCH` | Target branch (default: main) | No | -| `GIT_REPO_URL` | Target GitHub repository URL | Yes | +| `GIT_REPO_URL` | Target GitHub repository URL (`owner/repo`, HTTPS, or SSH) | Yes | | `NEXTCLOUD_URL` | Nextcloud instance URL | Yes | | `NEXTCLOUD_SHARE_TOKEN` | Public share token (the part after `/s/` in the share link) | Yes | | `NEXTCLOUD_SHARE_PASSWORD` | Public share password (empty if none) | No | @@ -245,7 +245,7 @@ docker run -p 3000:3000 \ upload-gltf ``` -The Docker image runs the Next.js app, Blender Draco compression, and server-side asset preparation in a single container. The `docker-entrypoint.sh` script checks for required environment variables before launching the app +The Docker image runs the Next.js app, Blender Draco compression, and server-side asset preparation in a single container. The `docker-entrypoint.sh` script creates the upload temp directory and reports Blender availability before launching the app. ## Supported Formats diff --git a/docker-entrypoint.sh b/docker-entrypoint.sh index 96f7f8b..3ba15b1 100644 --- a/docker-entrypoint.sh +++ b/docker-entrypoint.sh @@ -12,7 +12,7 @@ if command -v blender > /dev/null 2>&1; then echo "[upload-gltf] Blender found: $BLENDER_VERSION" echo "[upload-gltf] Draco compression is enabled." else - echo "[upload-gltf] WARNING: Blender not found. GLB Draco uploads will fail; use 'Envoyer en GLTF' if needed." + echo "[upload-gltf] WARNING: Blender not found. GLB Draco compression will fall back to separate GLTF delivery." fi echo "[upload-gltf] Ready. Launching application..." diff --git a/lib/auth.ts b/lib/auth.ts index 1d883bd..c7563d6 100644 --- a/lib/auth.ts +++ b/lib/auth.ts @@ -2,8 +2,7 @@ import { timingSafeEqual } from 'crypto' import { NextRequest, NextResponse } from 'next/server' /** - * Validate the upload secret from request headers. - * Returns null if valid, or a NextResponse error if invalid. + * Validate the shared upload secret before accepting mutation routes. */ export function validateUploadSecret(req: NextRequest): NextResponse | null { const secret = req.headers.get('x-upload-secret') diff --git a/lib/blender.ts b/lib/blender.ts index f6a66c4..8494279 100644 --- a/lib/blender.ts +++ b/lib/blender.ts @@ -7,8 +7,7 @@ const execFileAsync = promisify(execFile) /** * Compress a GLTF/GLB model using Blender's Draco compression. - * Returns { success: true } on success, or { success: false, error } on failure. - * GLB Draco is explicit: callers should fail instead of silently pushing heavy assets. + * Returns a structured result so callers can decide whether to fall back or stop. */ export async function compressWithBlender( inputPath: string, diff --git a/lib/sanitize.ts b/lib/sanitize.ts index 2f6d09a..abad689 100644 --- a/lib/sanitize.ts +++ b/lib/sanitize.ts @@ -1,8 +1,7 @@ import { basename } from 'path' /** - * Sanitize a filename: strip path components, replace special chars, - * collapse underscores, lowercase. + * Normalize uploaded filenames before storing them or writing Git paths. */ export function sanitizeFilename(name: string): string { return basename(name)