Tom Boullay
106 lines
3.2 KiB
Markdown
106 lines
3.2 KiB
Markdown
# upload-GLTF
|
|
|
|
A secure web interface for uploading 3D assets (GLTF/GLB + textures) with automatic Draco compression and GitHub push. 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
|
|
- **Blender** (headless) for Draco mesh 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
|
|
```
|
|
|
|
| Variable | Description | Required |
|
|
|----------|-------------|----------|
|
|
| `UPLOAD_SECRET_KEY` | Secret key for upload authentication | Yes |
|
|
| `GITHUB_TOKEN` | GitHub Personal Access Token (scope `repo`) | 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 |
|
|
|
|
> To create a token: GitHub > Settings > Developer settings > Personal access tokens > Generate new token (classic) with the `repo` scope.
|
|
|
|
## Usage
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Access the app at `http://localhost:3000`
|
|
|
|
> **Note:** Draco compression requires Blender installed locally. If Blender is not available, models are pushed to GitHub without compression.
|
|
|
|
### 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 \
|
|
upload-gltf
|
|
```
|
|
|
|
The Dockerfile includes Blender headless for automatic Draco compression.
|
|
|
|
## How it works
|
|
|
|
1. The user enters their access key
|
|
2. They select a folder containing:
|
|
- `model.glb` or `model.gltf` (required)
|
|
- Textures: `roughness`, `normal`, `metalness`, `color`, `displace` (`.png/.jpg/.webp`, optional)
|
|
3. The model is displayed in a 3D preview
|
|
4. On clicking "Upload & Push to GitHub", each file is sent to the `/api/upload` endpoint
|
|
5. For models: the file is written to `/tmp`, compressed with Blender Draco, then the compressed version is pushed to GitHub
|
|
6. For textures: pushed directly to GitHub without compression
|
|
7. If Blender is unavailable, the original model is pushed as-is (graceful fallback)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
app/
|
|
├── api/upload/route.ts # API: validation + Draco compression + GitHub push
|
|
├── globals.css # Tailwind + Google Fonts
|
|
├── layout.tsx # Root layout
|
|
└── page.tsx # Home page
|
|
components/
|
|
├── UploadZone.tsx # UI: key input, folder picker, validation, upload
|
|
├── ModelViewer.tsx # Lazy wrapper for the 3D viewer
|
|
└── SceneViewer.tsx # Three.js Canvas
|
|
scripts/
|
|
└── compress.py # Blender Draco compression script
|
|
```
|
|
|
|
## Supported Formats
|
|
|
|
| Type | Extensions |
|
|
|------|------------|
|
|
| 3D Models | `.glb`, `.gltf` |
|
|
| Textures | `.png`, `.jpg`, `.jpeg`, `.webp` |
|
|
|
|
## License
|
|
|
|
MIT
|