STLVault

STLVault is a containerized 3D Model library manager and organizer, designed specifically for 3D printing enthusiasts. It provides a clean, modern web interface to manage your growing collection of STL, STEP, and 3MF files.

Note: This project is still in Beta. While the core functionality (importing, organizing, viewing) works, expect changes and improvements.

---

✨ Features

• 📖 Manuals: Include markdown manuals for every model, with github style compatibility.
• 📂 Nestable Folders: Organize your models into a deep hierarchy that makes sense to you.
• 🗃️ Print Groups: Create Print Groups for same-project or different-size models.
• 🪄 Open in Slicers: Let's you open the model direclty in your preferred slicers.
• 🔗 URL Import: Import multiple files from Printables or Makerworld, with granular file selection. (Only models URL)
• 🖱️ Drag n' Drop: Seamlessly import new models or move files between folders.
• 📦 Bulk Actions: Tag, move, delete, download, or upload multiple files at once.
• 👁️ 3D Preview: Integrated web-based 3D viewer for STL, 3MF, STEP and STP files, with Trackball/Orbit controls switch to allow full rotational freedom (beta)
• 🖼️ Custom Thumbnails: Generate a thumbnail of the model from the 3D viewer directly or upload an image to be shown as a thumbnail.
• 🏷️ Metadata Management: Add tags, descriptions, and metadata to your models for easy retrieval.
• 🔍 Global Search: Sidebar search and filtering to find models library-wide.

---

🛠️ Tech Stack

• Frontend: React (TS), Vite
• Backend: Python (FastAPI)
• Database: SQLite
• Package Manager: NPM, UV
• Containerization: Docker & Docker Compose

---

📸 Screenshots

---

🚀 Deployment

The recommended way to deploy STLVault is using Docker Compose or via a container management tool like Portainer.

Replace the variables or create a .env file to let docker handle the injection.

An example .env file is in the section below.

Docker Compose with Images

services:
  stlvbackend:
    image: moddroid94/stlvault-backend:latest
    environment:
      - FILE_STORAGE=/app/uploads #DO NOT CHANGE, MODIFY THE BINDS
      - MANUAL_STORAGE=/app/uploads/manuals #DO NOT CHANGE, MODIFY THE BINDS
      - DB_PATH=/app/data/data.db #DO NOT CHANGE, MODIFY THE BINDS
      - WEBUI_URL=${APP_URL}
    ports:
      - '8998:8080'
    volumes:
      - YOUR_FOLDER_PATH:/app/uploads
      - YOUR_FOLDER_PATH:/app/data
      - YOUR_FOLDER_PATH:/app/manuals #OPTIONAL
    restart: always

  stlvfrontend:
    image: moddroid94/stlvault-frontend:latest
    environment:
      - TERA_API_URL=${API_URL}
      - TERA_APP_URL=${APP_URL}
    volumes:
      - node_modules:/app/node_modules
    ports:
      - '8999:5173'
    depends_on:
      - stlvbackend
    restart: always

volumes:
  node_modules: null

Docker Compose (CLI)

1. Clone the repository:

   git clone https://github.com/moddroid94/STLVault.git
   cd STLVault
   

2. Configure Environment: Review the .env file. You can modify the ports/URL if necessary.

   # .env example
   APP_URL=http://192.168.0.17:8999
   API_URL=http://192.168.0.17:8998
   APP_PORT=8999
   API_PORT=8998
   UPLOAD_PATH=/your/mount/path
   DATA_PATH=/your/mount/otherpath
   

3. Start the Stack:

   docker-compose up -d
   

4. Access the App: Open your browser and navigate to http://localhost:8999 (or the port you configured).

GitOps (Deploy from Repo)

You can deploy STLVault directly from any git deploy compatible docker manager using the repository as a stack source.

1. Create a new Stack.
2. Select Repository as the build method.
3. Enter the repository URL: https://github.com/moddroid94/STLVault.
4. Environment Variables: Define the environment variables in the Docker Manager UI.

---

📂 Volume Configuration

The application requires two main volumes to persist data. If you are using the default docker-compose.yml, these are mapped automatically relative to the backend folder:

• /backend/uploads: Stores your actual 3D model files.
• /backend/data: Stores the SQLite database file.

---

🗺️ Roadmap

• Basic File Management (Upload, Move, Delete)
• 3D Viewer (STL, 3MF, STEP)
• Storage Template for saving files orderly