Makers Vault

Makers Vault is a home for all your 3D print files and creative images/illustrations. Tired of having basic folders on your desktop filled with 3D print files with inconsistent names? Tired of having to load a 3D print file into your slicer just to see what it is? Look no further. Create folders, tag your files, and preview them in 3D directly in your browser. Makers Vault is fully self-hostable using Docker and accessible through your web browser for ease of use and deployment.

Makers Vault Home Screen

Tech Stack

• Frontend: React + TypeScript (Vite), Tailwind CSS, three.js, occt-import-js.
• Backend: FastAPI (Python), SQLModel, SQLite.
• Slicer Bridge: Go (custom protocol handler).
• Deployment: Docker, Docker Compose.

Road Map

Version 5.1

• Open in Lightburn Setting
• MFA and multi-user
• New themes
• Bulk move
• View sub-folders in root folders.
• Robust handling for adding existing folders from OS.

Getting Started

Makers Vault is deployable using Docker pull or Docker Compose:

Docker Compose

version: "3.9"

services:
  api:
    image: ${API_IMAGE:-shotgunwilly555/makersvault-api:latest}
    restart: unless-stopped
    environment:
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      - AUTH_USERNAME=${AUTH_USERNAME:-admin}
      - AUTH_PASSWORD=${AUTH_PASSWORD:-super-secret}
      - AUTH_SECRET=${AUTH_SECRET:-changeme-secret}
      - AUTH_TOKEN_TTL=${AUTH_TOKEN_TTL:-43200}
      - FILE_STORAGE=/app/storage
      - DB_URL=sqlite:////app/data/app.db
      - PUBLIC_URL=${PUBLIC_URL:-}
      - CORS_ORIGINS=${CORS_ORIGINS:-}
      - IMPORT_MOUNT_PATH=${IMPORT_MOUNT_PATH:-/imports}
      - IMPORT_MOUNT_EXTS=${IMPORT_MOUNT_EXTS:-stl,3mf,step,stp,obj,svg,png,jpg,jpeg,webp,bmp,lbrn,lbrn2,zip}
      - IMPORT_MOUNT_INCLUDE_HIDDEN=${IMPORT_MOUNT_INCLUDE_HIDDEN:-false}
      - IMPORT_MOUNT_ON_STARTUP=${IMPORT_MOUNT_ON_STARTUP:-true}
    volumes:
      - makersvault_storage:/app/storage
      - makersvault_db:/app/data
      - ${IMPORT_MOUNT_PATH_HOST:-/path/to/imports}:/imports:ro
    ports:
      - "${API_PORT:-8000}:8000"

  web:
    image: ${WEB_IMAGE:-shotgunwilly555/makersvault-web:latest}
    restart: unless-stopped
    environment:
      - PUBLIC_URL=${PUBLIC_URL:-}
      - VITE_API_URL=${VITE_API_URL:-}
      - VITE_ALLOWED_HOSTS=${VITE_ALLOWED_HOSTS:-}
      - CORS_ORIGINS=${CORS_ORIGINS:-}
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
    ports:
      - "5173:5173"
    depends_on:
      - api

volumes:
  makersvault_storage:
  makersvault_db:

Docker Pull

docker pull shotgunwilly555/makersvault-api:latest
docker pull shotgunwilly555/makersvault-web:latest

docker run -d --name mv-api -p 8000:8000 \
  -e AUTH_USERNAME=admin -e AUTH_PASSWORD=super-secret \
  shotgunwilly555/makersvault-api:latest

docker run -d --name mv-web -p 5173:5173 \
  -e VITE_API_URL=http://10.0.0.160:8000 \
  shotgunwilly555/makersvault-web:latest

Setting up the .env file

Create a .env file in the same folder as docker-compose.yml. Start with this baseline:

PUID=1000
PGID=1000
API_IMAGE=shotgunwilly555/makersvault-api:latest
WEB_IMAGE=shotgunwilly555/makersvault-web:latest
FILE_STORAGE=/app/storage
DB_URL=sqlite:///./app.db
API_PORT=8000
PUBLIC_URL=
CORS_ORIGINS=
VITE_API_URL=
VITE_ALLOWED_HOSTS=
AUTH_USERNAME=admin
AUTH_PASSWORD=super-secret
AUTH_SECRET=replace-with-random-secret
AUTH_TOKEN_TTL=43200
IMPORT_MOUNT_PATH=/imports
IMPORT_MOUNT_PATH_HOST=/path/to/imports
IMPORT_MOUNT_EXTS=stl,3mf,step,stp,obj,svg,png,jpg,jpeg,webp,bmp,lbrn,lbrn2,zip
IMPORT_MOUNT_INCLUDE_HIDDEN=false
IMPORT_MOUNT_ON_STARTUP=true

For direct/LAN mode, set VITE_API_URL to a browser-reachable API URL (for example, http://10.0.0.160:8000).

Reverse Proxy Support (Any Provider)

Makers Vault is reverse-proxy agnostic. Nginx Proxy Manager, Traefik, Nginx, Caddy, HAProxy, and Apache all work.

Required routes:

• / to web:5173
• /api/* to api:8000

Important: configure your proxy so public /api/assets reaches the API service route for /assets.

Recommended flow for proxied setups

Start containers:

docker compose -f docker-compose.yml up -d

1. Bring the stack up with Docker Compose.
2. Configure your reverse proxy routes (/ and /api/*).
3. Set PUBLIC_URL in .env (for example, https://makersvault.example.com) and restart.
4. Open Makers Vault at your public domain.

When served on standard proxy ports (80/443), Makers Vault automatically calls the API at <current-origin>/api.

Environment values when using a reverse proxy

• Set PUBLIC_URL to your public domain URL.
• Leave VITE_API_URL empty unless you intentionally want a non-default API target.
• Set CORS_ORIGINS as needed for direct/LAN access or additional origins.

Example:

PUBLIC_URL=https://makersvault.example.com
CORS_ORIGINS=https://makersvault.example.com,http://10.0.0.160:5173
VITE_API_URL=
VITE_ALLOWED_HOSTS=

Running as non-root: set PUID and PGID to your host user/group IDs (defaults to 1000). Containers create a matching user at startup so volume mounts stay writable.

Keeping API internal: when everything is behind a reverse proxy, you can remove ports from api and use expose: ["8000"] instead.

Quick troubleshooting

• Login fails with CORS error: add the public domain to CORS_ORIGINS.
• UI loads but API calls 404 under /api: fix proxy mapping so /api/* reaches API routes correctly.
• LetsEncrypt HTTP-01 challenge fails and returns app HTML: make sure external port 80 points to your reverse proxy (not directly to Makers Vault).
• Public login fails while LAN/direct works: clear/avoid hardcoded private-IP VITE_API_URL for proxied access.

Change the default credentials in .env before exposing the app publicly.

Contributing

Contributions are always welcome, whether it be bug fixes or feature improvements. For large changes, please open a discussion first!

Feature Requests and Bug Reporting

For bug reports or feature improvement requests, please open an issue or start a discussion thread.

Features, UI Walkthrough, and Supported File Types

Supported File Types

Makers Vault supports the following file types:

3D Print Files:

• STL
• STEP
• OBJ
• 3MF
• STP

Image Types:

• SVG
• PNG
• JPG
• WEBP
• BMP

Other File Types

Most other file types (docx, ppt, pdf, zip, etc.) are supported, but they will not render a preview. Makers Vault is mainly designed for 3D printing files, CAD, and artistic illustrations. If you need a document-focused solution, other tools may be more suitable. That said, feel free to request features if needed!

Feature List

Makers Vault is intentionally kept simple to remain user-friendly while still being feature-rich for its purpose:

• Create and delete folders.
• Tag any document uploaded to Makers Vault.
• Sort, search, and rename documents.
• Add notes to documents.
• Toggle between light and dark mode for better viewing of differently colored 3D models.
• Create username and password for added security when running behind a reverse proxy.
• Move or delete files from within the application.
• Drag and drop upload.
• Customization Themes.
• Open in Slicer (Beta).
• Import from link (MakerWorld, Thingiverse, and Printables).
• Batch tagging and batch deleting.
• Search at mount point for eligible file types.
• Robust handling of .zip imports.

UI and Feature Walkthrough

NOTE: For initial install instructions refer to the Getting Started section.

Logging in for the First Time

Log in using the default password set in the .env file, or a custom password if configured (recommended).

Landing Page / All Items

Uploading Files

Makers Vault supports both single-file, batch uploads, and drag and drop. To upload a file, click the Upload button in the top-right corner. To upload a folder, use the Upload Folder button and select the entire folder. This action can also be performed by utilizing the drag and drop function

NOTE: Depending on the number and size of the files, upload and preview generation may take some time. Please be patient.

Uploading Single/Multiple Files

Dragging and Dropping to Upload

Files that are dragged and dropped to upload will be placed in whatever folder is currently selected. For example: You are clicked into the folder "3D prints" and drag files into Makers Vault, it will upload to that location.

Importing via Link (Beta)

The currently supported 3D printing repository sites are:

• MakerWorld
• Printables
• Thingiverse

In the future there are plans to add support for more websites, but in this current release only the three listed will function. The root link from the respective repository can be used to import any models. Most models will import as a .zip file. When a zip file is imported a pop-up will appear prompting to either save as a zip or unzip and save. Unzip and save allows the user to select which files to keep and which to discard. This helps to ensure that unecessary "read-me" files aren't uploaded.

Model Rendering, Tagging, and Adding Notes

Makers Vault uses static 3D preview images in each tile to keep folder browsing fast. To view a fully interactive 3D preview, double-click the tile. In the pop-up window, you can rotate and inspect the 3D model interactively by clicking and holding with your mouse and dragging.

Individual files can be renamed by double-clicking the Name field. The file extension (STL, STEP, 3MF, etc.) will be preserved even if removed by mistake.

Tagging Files and Adding to Folders

To begin organizing files, click “New” at the top left to create a new folder. To create a sub folder click the "..." next to the newly created folder and select "+ Subfolder".

After creating a folder, assign files to it using the dropdown menu in each file tile. Alternatively, click the folder and then upload files directly — uploaded files will automatically be placed in the current folder.

<