upload-GLTF

A secure web interface for uploading model.glb and its associated textures with two outputs:

• Nextcloud Drive — Archives the original files with automatic versioning (VF/V1/V2...), so artists always have a history of past versions.
• GitHub — Delivers compressed models (Draco via Blender) and compressed textures to the dev team's repository, ready for integration.

Built for La Fabrik Durable.

Stack

• Next.js 16 (App Router) + React 19 + TypeScript
• Three.js (@react-three/fiber + @react-three/drei) for 3D preview
• Tailwind CSS for styling
• Octokit for pushing via the GitHub API
• Nextcloud WebDAV for Drive archiving with automatic versioning
• Blender (headless) for Draco mesh compression
• Coolify (Docker) for hosting

Installation

git clone https://github.com/La-Fabrik-Durable/upload-GLTF.git
cd upload-GLTF
npm install

Configuration

Copy .env.example to .env.local and fill in the values:

UPLOAD_SECRET_KEY=your-secret-key-here
GITHUB_TOKEN=ghp_your-github-personal-access-token
GIT_BRANCH=main
GIT_REPO_URL=https://github.com/your-org/your-repo.git
BLENDER_PATH=/Applications/Blender.app/Contents/MacOS/Blender

# Nextcloud Drive (public share WebDAV)
NEXTCLOUD_URL=https://cloud.example.com
NEXTCLOUD_SHARE_TOKEN=your-public-share-token
NEXTCLOUD_SHARE_PASSWORD=
NEXTCLOUD_BASE_PATH=Models

Variable	Description	Required
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
BLENDER_PATH	Path to Blender binary (default: blender)	No
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
NEXTCLOUD_BASE_PATH	Root folder on the Drive (default: Models)	No

To create a GitHub token: GitHub > Settings > Developer settings > Fine-grained personal access tokens > select the target repo > Permissions > Contents: Read and write.

Usage

Development

npm run dev

Access the app at http://localhost:3000

Note: Draco compression requires Blender installed locally. On macOS, Blender is typically at /Applications/Blender.app/Contents/MacOS/Blender. Set BLENDER_PATH in .env.local accordingly. If Blender is not available, models are pushed to GitHub without compression.

Local 3D preview is currently supported for .glb files only.

Production (Coolify / Docker)

docker build -t upload-gltf .
docker run -p 3000:3000 \
  -e UPLOAD_SECRET_KEY=your-key \
  -e GITHUB_TOKEN=ghp_xxx \
  -e GIT_REPO_URL=https://github.com/org/repo.git \
  -e NEXTCLOUD_URL=https://cloud.example.com \
  -e NEXTCLOUD_SHARE_TOKEN=your-share-token \
  upload-gltf

The Docker image includes Blender headless (installed once at build time). On startup, the entrypoint checks if Blender is available and logs its version. No extra configuration is needed in production — BLENDER_PATH defaults to blender which is in the container's PATH.

How it works

1. The user enters their access key
2. They select a folder containing:
   • model.glb (required)
   • Any associated textures (.png/.jpg/.jpeg/.webp)
3. The .glb model is displayed in a local 3D preview
4. On clicking "Envoyer":
   • The app uploads the folder once to a temporary server-side staging area
   • The app prepares the final Git payload from this staging area
   • The app checks the remote Git repo for existing files and computes diffs
   • If the folder doesn't exist, upload proceeds directly
   • If the folder exists and files differ, a confirmation dialog shows only the actual changes
   • If nothing changed, the upload is skipped entirely

Upload flow: Drive first, then Git

6. 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.
7. Git upload (delivery to devs) — The prepared Git payload is reused from staging: models are compressed with Blender Draco, textures are compressed server-side, then all changed files are pushed to GitHub in a single commit. This is what the dev team consumes in the application.

Drive versioning (Nextcloud WebDAV)

The Drive uses a VF (version finale) / Vx (archived versions) structure:

Models/
  VF/                    ← latest version
    coffeetest/
      model.glb
      color.jpg
  V1/                    ← first archive
    coffeetest/
  V2/                    ← second archive
    coffeetest/

• New folder (doesn't exist in VF/): files are uploaded directly to VF/{folderName}/
• Replace (folder exists in VF/ with diffs): VF/{folderName} is moved to Vx/{folderName} (next available version), then all files are re-uploaded to VF/{folderName}/
• No changes: nothing happens on the Drive

All files are uploaded to VF/ (not just diffs), because the move operation empties the previous folder.

Upload safeguards

• The upload flow prevents duplicate submissions on the client (Envoyer, overwrite confirmation, and "Git only" confirmation are locked while processing)
• The server applies a lightweight per-folder lock on Drive and Git routes to avoid duplicate commits and concurrent writes
• The folder is staged server-side so the browser sends the payload only once during the full upload flow

Commit messages

All changes are pushed in a single commit with a grouped formatted message:

New folder:

update: upload-gltf add a new model -> my-model

📦 Model
  ✅ model.glb (compressed)
🎨 Textures (color)
  ✅ color_porte.jpg (compressed)

🪶 Textures (roughness)
  ✅ roughness_tuyaux.png (compressed)

🧩 Assets
  ✅ opacity_fenetre.png (compressed)

Update (only one texture changed):

update: upload-gltf update -> coffeetest

📦 Model
  ↔️ model.glb (compressed)

🎨 Textures (color)
  🔄 color_tuyaux.jpg (compressed)

Sections currently used:

• 📦 Model
• 🎨 Textures (color)
• 🪶 Textures (roughness)
• 🧭 Textures (normal)
• 🔩 Textures (metalness)
• 🧩 Assets
• 🗑 Deleted

Symbols: ✅ new — 🔄 modified — ↔️ unchanged (model always re-pushed) — ❌ deleted

8. Orphan files (present on remote but not in the new upload) are deleted in the same commit
9. If Blender is unavailable, the original model is pushed as-is (graceful fallback)

Uploaded models are pushed to public/models/<folderName>/ in the target repo.

Current Limitations

• Large uploads are faster than before because the folder is staged only once, but the Drive upload remains sequential.
• Git LFS uploads are still sequential.
• The current upload contract still expects a single model.glb file and a flat texture set.

Project Structure

app/
├── api/upload/
│   ├── stage/route.ts     # POST: upload folder once to temporary staging
│   ├── check/route.ts     # POST: prepare staged Git assets and compare with remote files
│   ├── drive/route.ts     # POST: upload staged originals to Nextcloud Drive (VF/Vx versioning)
│   └── git/route.ts       # POST: push staged prepared assets to GitHub
├── globals.css            # Tailwind + CSS variable fonts
├── layout.tsx             # Root layout (next/font/google)
└── page.tsx               # Home page
components/
├── ui/
│   ├── icons.tsx              # Shared SVG icon components
│   └── Modal.tsx              # Shared modal wrapper + ModalActions
├── upload/
│   ├── SecretInput.tsx        # Access key input
│   ├── FolderDropzone.tsx     # Folder drag & drop / picker
│   ├── FolderCard.tsx         # Folder status card (Drive + Git)
│   ├── DriveStatusLine.tsx    # Drive/Git status sub-line
│   ├── WarningBanner.tsx      # Missing texture warnings
│   ├── OverwriteConfirmModal.tsx  # Diff confirmation dialog
│   ├── NoChangesModal.tsx     # "No changes detected" dialog
│   ├── DriveErrorModal.tsx    # "Drive failed, continue?" dialog
│   └── ActionButtons.tsx      # Upload / Cancel / Reset buttons
├── UploadZone.tsx         # Main upload page (rendering only)
├── ModelViewer.tsx        # Lazy wrapper for 3D viewer
└── SceneViewer.tsx        # Three.js Canvas
hooks/
├── useSecret.ts               # Secret key state management
├── useFolderEntries.ts        # Folder entries state management
└── useUploadOrchestrator.ts   # Upload pipeline orchestration (Drive → Git)
lib/
├── constants.ts           # Shared constants and extensions
├── types.ts               # Server types (ParsedFile, FileDiff, staged asset metadata, etc.)
├── client-types.ts        # Client types (FolderEntry, DriveStatus, etc.)
├── upload-api.ts          # Client-side API helpers (stage, check, uploadDrive, uploadGit)
├── diff-files.ts          # File diff classification (new/changed/unchanged/deleted)
├── sanitize.ts            # Filename sanitization
├── auth.ts                # Upload secret validation (timing-safe)
├── github.ts              # Octokit helpers (getRemoteFolder, pushAllToGitHub)
├── nextcloud.ts           # Nextcloud WebDAV client (native fetch, cached config)
├── upload-staging.ts      # Temporary server-side staging and prepared asset reuse
├── upload-lock.ts         # Lightweight in-memory per-folder upload lock
├── asset-classification.ts # Group assets by family for commit messages
├── blender.ts             # Blender Draco compression
├── commit-message.ts      # Commit message builder
├── parse-upload.ts        # FormData parser + validation
├── validate-folder.ts     # Client-side folder validation (discriminated union)
└── format-bytes.ts        # Byte formatting utility
scripts/
└── compress.py            # Blender Draco compression script
Dockerfile                 # Multi-stage build: Node 20 slim + Blender headless + tini
docker-entrypoint.sh       # Startup: Blender check + launch

Supported Formats

Type	Extensions
3D Models	.glb
Textures	.png, .jpg, .jpeg, .webp

License

MIT