math-pixel/upload-gltf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update: fix readme + add license

Browse Source
This commit is contained in:
Tom Boullay
2026-04-27 23:57:12 +02:00
parent dddecbb11c
commit 2679d29ab4
2 changed files with 93 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+72 -85
View File
@@ -1,61 +1,21 @@
# upload-GLTF
Version: `1.0.0`
A secure web interface for uploading `model.gltf` with its associated `.bin` file and 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 GLTF assets and compressed textures to the dev team's repository, ready for integration.
- **Nextcloud Drive** — Archives the original files with automatic versioning (VF/V1/V2...), so artists always have a history of past versions
- **GitHub** — Delivers GLTF assets and compressed textures to the dev team's repository, ready for integration
Built for La Fabrik Durable.
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
## 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
- **Sharp** for server-side texture compression
- **Coolify** (Docker) for hosting
## Installation
```bash
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:
```env
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
# 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 |
| `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.
- [**Next.js 16** (App Router)](https://nextjs.org/docs/app/getting-started/installation) + [React 19](https://react.dev/learn/creating-a-react-app) + [TypeScript](https://www.typescriptlang.org/docs/)
- [**Three.js**](https://threejs.org/docs/#manual/en/introduction/Creating-a-scene) ([React Three Fiber](https://r3f.docs.pmnd.rs/getting-started/introduction) + [Drei](https://drei.docs.pmnd.rs/getting-started/introduction)) for 3D preview
- [**Tailwind CSS**](https://v3.tailwindcss.com/docs/installation) for styling
- [**Octokit**](https://github.com/octokit/rest.js/#readme) for pushing via the GitHub API
- [**Nextcloud WebDAV**](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/index.html) for Drive archiving with automatic versioning
- [**Sharp**](https://sharp.pixelplumbing.com/install/) for server-side texture compression
- [**Coolify** (Docker)](https://coolify.io/docs/applications/build-packs/dockerfile) for hosting
## Usage
@@ -64,40 +24,7 @@ NEXTCLOUD_BASE_PATH=Models
```bash
npm run dev
```
Access the app at `http://localhost:3000`
> **Note:** Uploads accept `model.gltf` and preserve it as GLTF. `.glb` uploads are rejected by validation.
>
> Local 3D preview supports `model.gltf` folders by resolving dropped companion files such as `model.bin` and textures through local object URLs.
> The preview also shows a small model stats helper with estimated draw calls, meshes, triangles, materials, and texture count.
> Opacity helper textures can be named `opacity.png` for the whole model or `opacity_part-name.png` to target a mesh/material whose name contains `part-name`; alpha-channel PNGs are converted to alpha maps for the preview.
> If `model.gltf` references a missing `.bin` but the folder contains exactly one other `.bin`, the preview can use it as a local fallback and shows a warning because the final upload may still be broken until the `.bin` filename matches the GLTF reference.
### Asset naming convention
Texture filenames must start with a known asset family. Use `asset.png` to apply a texture to the whole model, or `asset_object.png` to target a specific object.
Allowed families are defined in `lib/asset-naming.ts`: `color`, `diffuse`, `roughness`, `normal`, `metalness`, `height`, `opacity`.
Valid examples: `color.png`, `diffuse_lampe.png`, `normal_cable1.png`, `opacity_lampe.png`.
Invalid examples: `lampe_opacity.png`, `cable1_base_color.png`, `normal_opengl_cable1.png`, `metallic_pied.png`. Invalid or unknown asset names block the upload.
### Production (Coolify / Docker)
```bash
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 runs the Next.js app and server-side asset preparation in a single container.
The app runs on `http://localhost:3000` with hot reload. The upload API routes are available under `http://localhost:3000/api/upload/*`
## How it works
@@ -115,6 +42,13 @@ The Docker image runs the Next.js app and server-side asset preparation in a sin
- If the folder exists and files differ, a confirmation dialog shows **only the actual changes**
- If nothing changed, the upload is skipped entirely
### Asset naming convention
Texture filenames must start with a known asset family. Use `asset.png` to apply a texture to the whole model, or `asset_object.png` to target a specific object.
Allowed families are defined in `lib/asset-naming.ts`: `color`, `diffuse`, `roughness`, `normal`, `metalness`, `height`, `opacity`.
Valid examples: `color.png`, `diffuse_lampe.png`, `normal_cable1.png`, `opacity_lampe.png`.
Invalid examples: `lampe_opacity.png`, `cable1_base_color.png`, `normal_opengl_cable1.png`, `metallic_pied.png`. Invalid or unknown asset names 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.
@@ -262,6 +196,59 @@ Dockerfile # Multi-stage build: Node 20 slim + tini
docker-entrypoint.sh # Startup check + launch
```
## Installation
```bash
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:
```env
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
# 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 |
| `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
> To create a Nextcloud public share token: Nextcloud > Files > select folder > Share > Create public share > set permissions (write access required) > copy the share link and extract the token
### Production (Coolify / Docker)
```bash
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 runs the Next.js app and server-side asset preparation in a single container. The `docker-entrypoint.sh` script checks for required environment variables before launching the app
## Supported Formats
| Type | Extensions |
@@ -272,4 +259,4 @@ docker-entrypoint.sh # Startup check + launch
## License
MIT
[MIT](LICENSE) - Copyright (c) 2026 La Fabrik Durable.