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 currently in Beta. While the core functionality (importing, organizing, viewing) works, expect changes and improvements.

---

✨ Features

• 📂 Nestable Folders: Organize your models into a deep hierarchy that makes sense to you.
• 🪄 Open in Slicer: Let's you open the model direclty in your slicer.
• 🔗 URL Import: Import multiple files from Printables URL, 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.

Docker Compose with Images

services:
  stlvbackend:
    image: moddroid94/stlvault-backend:latest
    pull_policy: build
    environment:
      - FILE_STORAGE=/app/uploads
      - DB_PATH=/app/data/data.db
      - WEBUI_URL=http://192.168.178.21:8999
    ports:
      - '8998:8080'
    volumes:
      - YOUR_FOLDER_PATH:/app/uploads
      - YOUR_FOLDER_PATH:/app/data
    restart: always
  stlvfrontend:
    image: moddroid94/stlvault-frontend:latest
    pull_policy: build
    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 stack.env file. You can modify the ports or URL if necessary, don't change the SEMVER tag.

   # stack.env example
   BASE_URL=http://0.0.0.0
   WWW_PORT=8989
   API_PORT=8988
   SEMVER=x.x.x

3. Start the Stack:

   docker-compose up -d

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

Portainer

You can deploy STLVault directly from Portainer 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 variables below in the Portainer UI (variable substitution will automatically update stack.env).

   Variable	Default	Description
   BASE_URL	http://0.0.0.0	The base URL for the application.
   WWW_PORT	8989	Port for the Frontend Web UI.
   API_PORT	8988	Port for the Backend API.

---

📂 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)
• Open in Slicer settings
• Thumbnails / 3D viewer for STEP
• Model import via Printables URL with interactive models selection.
• Backend folder structure follows frontend
• "All models" folder Pagination to speedup large collection first load.
• Zip Import
• Root folder Scan and import
• Generate thumbnail from 3D Preview (to fix bad oriented models or to choose a better angle)
• Models Collections (to group models for projects or variants)
• Multi-User with Authentication

---

🤝 Contributing

Contributions are welcome! Since this project uses a standard React + FastAPI stack, it is easy to set up for development.

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

---

📝 License

MIT License