Skip to content

Installation (Unraid and Docker)

TeeCodeDev edited this page Sep 27, 2026 · 3 revisions

Installation Guide

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.


1. Unraid Setup (Recommended)

Installing GyroidVault on Unraid takes less than a minute through Community Applications (CA):

  1. Open your Unraid WebGUI and head to the Apps tab.
  2. Search for GyroidVault in the search bar.
  3. Click Install.
  4. 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).
  5. 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).


2. Docker Compose

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.


3. Standard Docker CLI (docker run)

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


4. Container Health Check Endpoint (/healthz)

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.

5. Large Libraries & 2TB+ Performance Tips

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.

6. First Boot & Admin Setup

  1. Once the container is running, open http://:3457.
  2. The very first user account registered on a fresh instance is automatically granted the Administrator role.
  3. No registration token or invite code is needed for this initial admin account.

Clone this wiki locally