Repository navigation
Installation (Unraid and Docker)
GyroidVault is packaged as a lightweight Docker container designed to run seamlessly on Unraid, Docker Compose, TrueNAS, Synology, or any Linux/Mac/Windows Docker host.
Installing GyroidVault on Unraid takes less than a minute through Community Applications (CA):
- Open your Unraid WebGUI and head to the Apps tab.
- Search for GyroidVault in the search bar.
- Click Install.
- The template comes pre-configured. Ensure your volume paths match your storage layout:
- AppData (/app/data): Map to /mnt/user/appdata/gyroidvault. This holds your SQLite database, custom settings, and generated thumbnails.
- Library (/library): Most important mapping! Point this to the root share where your 3D models live (e.g. /mnt/user/3Dprints or /mnt/user/data/models).
- WebUI Port: Default container port is 3000, typically mapped to host port 3457 (or any free port you prefer).
- Click Apply. Unraid will download the image and launch the container.
💡 Read Permissions: GyroidVault reads your 3D files non-destructively. Ensure the container has read permissions on your 3D models share (and write permissions if you plan to upload/move files via the WebUI).
For Debian, Ubuntu, TrueNAS SCALE, Proxmox, or homelab Docker setups, Docker Compose is the most convenient method:
yaml services: gyroidvault: image: ghcr.io/teecodedev/gyroidvault:latest container_name: gyroidvault ports: - "3457:3000" volumes: - ./data:/app/data - /mnt/storage/3dprints:/library environment: - NODE_ENV=production - PORT=3000 - LIBRARY_PATH=/library healthcheck: test: ["CMD", "wget", "-qO-", "http://localhost:3000/healthz"] interval: 30s timeout: 5s retries: 3 restart: unless-stopped
Run:
ash docker compose up -d
Then open your browser to http://:3457.
ash docker run -d \ --name=gyroidvault \ -p 3457:3000 \ -v /path/to/appdata:/app/data \ -v /path/to/your/3dprints:/library \ -e LIBRARY_PATH=/library \ --restart unless-stopped \ ghcr.io/teecodedev/gyroidvault:latest
Starting in v2.2.0, GyroidVault exposes a lightweight health check endpoint at GET /healthz:
- Verifies application uptime and live SQLite database connectivity (SELECT 1).
- Returns HTTP 200 OK with {"status":"ok","version":"2.2.0","uptime":...}.
- Ideal for Docker health checks, Uptime Kuma, Homepage, or reverse proxies.
GyroidVault features an asynchronous background scanner and paginate-then-hydrate SQLite queries designed for large repositories:
- Sub-80ms Queries (v2.1.1+): Tested on libraries with 20,000+ models and 180,000+ files.
- Non-blocking indexing: Scanning runs in the background with event-loop yields without freezing the UI or web server.
- Configurable ZIP Scanning: Under Settings → General, you can toggle whether .zip archives should be deep-indexed or treated as regular files.
- Once the container is running, open http://:3457.
- The very first user account registered on a fresh instance is automatically granted the Administrator role.
- No registration token or invite code is needed for this initial admin account.