229 lines
6.9 KiB
Markdown
229 lines
6.9 KiB
Markdown
# 📦 MakerStash
|
|
|
|
> **Your personal stash for 3D models**
|
|
|
|
A powerful 3D model file manager for makers and 3D printing enthusiasts. Organize, view, and manage your STL, OBJ, and 3MF files with an intuitive web interface featuring interactive 3D previews and automatic thumbnail generation.
|
|
|
|
*Browse, organize, and view your 3D models in an intuitive interface*
|
|
|
|
## ⚡ Quick Start
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/dlawler489/makerstash.git
|
|
cd makerstash
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Setup environment
|
|
cp .env.example .env
|
|
|
|
# Run the application
|
|
npm start
|
|
```
|
|
|
|
Visit **http://localhost:3000** and register a new account!
|
|
|
|
## Features
|
|
|
|
- **Interactive 3D Viewer** - View and rotate STL, OBJ, and 3MF models directly in the browser with Three.js
|
|
- **Automatic Thumbnails** - Auto-generated isometric preview images for STL, OBJ, and 3MF files
|
|
- **Browse & Organize** - View and manage your 3D model collection with an intuitive interface
|
|
- **Collections** - Group related models together for better organization
|
|
- **Tags** - Categorize models with custom tags and colors
|
|
- **Search** - Quickly find models by name, description, creator, or tags
|
|
- **Metadata Management** - Add descriptions, creator info, source URLs, notes, and support status
|
|
- **File Support** - Upload STL, OBJ, 3MF, GCODE, and ZIP files
|
|
- **User Authentication** - Secure registration and login system
|
|
- **Responsive Design** - Works on desktop, tablet, and mobile devices
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Node.js, Express
|
|
- **Database**: SQLite3
|
|
- **Frontend**: Vanilla JavaScript, HTML5, CSS3
|
|
- **3D Visualization**: Three.js with STLLoader and OBJLoader
|
|
- **File Uploads**: Multer
|
|
- **Authentication**: JWT, bcrypt
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 16 or higher
|
|
- npm or yarn
|
|
|
|
## Installation
|
|
|
|
1. Clone or download this repository
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
cd makerstash
|
|
npm install
|
|
```
|
|
|
|
3. Create a `.env` file in the root directory (or copy from `.env.example`):
|
|
```env
|
|
PORT=3000
|
|
DATABASE_PATH=./database.sqlite
|
|
UPLOAD_DIR=./uploads
|
|
JWT_SECRET=your-secret-key-change-this
|
|
SESSION_SECRET=your-session-secret-change-this
|
|
NODE_ENV=development
|
|
```
|
|
|
|
**Important**: Change the `JWT_SECRET` and `SESSION_SECRET` to random, secure values in production!
|
|
|
|
## Usage
|
|
|
|
### Development Mode
|
|
|
|
Run the server with auto-reload:
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production Mode
|
|
|
|
Run the server:
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
The application will be available at `http://localhost:3000`
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
makerstash/
|
|
├── server/
|
|
│ ├── database.js # Database setup and schema
|
|
│ ├── index.js # Express server entry point
|
|
│ ├── middleware/
|
|
│ │ └── auth.js # Authentication middleware
|
|
│ ├── routes/
|
|
│ │ ├── auth.js # Authentication endpoints
|
|
│ │ ├── models.js # Model CRUD endpoints
|
|
│ │ ├── collections.js # Collection endpoints
|
|
│ │ └── tags.js # Tag endpoints
|
|
│ └── services/
|
|
│ └── thumbnailGenerator.js # 3D model thumbnail generation
|
|
├── client/
|
|
│ ├── index.html # Main HTML file
|
|
│ ├── styles.css # Application styles (Bambu Lab green theme)
|
|
│ ├── app.js # Frontend JavaScript
|
|
│ └── viewer3d.js # 3D model viewer
|
|
├── uploads/
|
|
│ ├── files/ # Uploaded 3D model files (STL, OBJ, etc.)
|
|
│ └── images/ # Generated thumbnail images
|
|
├── .env # Environment variables
|
|
├── .env.example # Example environment file
|
|
├── package.json # Dependencies
|
|
└── README.md # This file
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/auth/register` - Register new user
|
|
- `POST /api/auth/login` - Login
|
|
- `GET /api/auth/me` - Get current user (requires auth)
|
|
|
|
### Models
|
|
- `GET /api/models` - List all models (supports search, tag, collection filters)
|
|
- `GET /api/models/:id` - Get single model
|
|
- `POST /api/models` - Upload new model (requires auth)
|
|
- `PUT /api/models/:id` - Update model metadata (requires auth)
|
|
- `DELETE /api/models/:id` - Delete model (requires auth)
|
|
- `GET /api/models/:id/download` - Download model file
|
|
|
|
### Collections
|
|
- `GET /api/collections` - List all collections
|
|
- `GET /api/collections/:id` - Get collection with models
|
|
- `POST /api/collections` - Create collection (requires auth)
|
|
- `PUT /api/collections/:id` - Update collection (requires auth)
|
|
- `DELETE /api/collections/:id` - Delete collection (requires auth)
|
|
|
|
### Tags
|
|
- `GET /api/tags` - List all tags
|
|
- `GET /api/tags/:id/models` - Get models by tag
|
|
- `POST /api/tags` - Create tag (requires auth)
|
|
- `PUT /api/tags/:id` - Update tag (requires auth)
|
|
- `DELETE /api/tags/:id` - Delete tag (requires auth)
|
|
|
|
## Features in Detail
|
|
|
|
### User Registration & Authentication
|
|
- Secure password hashing with bcrypt
|
|
- JWT-based authentication
|
|
- 7-day token expiration
|
|
|
|
### Model Upload
|
|
- Drag and drop or browse to upload
|
|
- Automatic file validation
|
|
- Support for multiple 3D file formats
|
|
- 100MB file size limit (configurable)
|
|
- Rich metadata support
|
|
|
|
### Search & Filtering
|
|
- Full-text search across model names, descriptions, and creators
|
|
- Filter by tags
|
|
- Filter by collections
|
|
- Real-time search with debouncing
|
|
|
|
### Collections & Tags
|
|
- Create unlimited collections to organize models
|
|
- Add colorful tags for categorization
|
|
- View model counts for each collection and tag
|
|
|
|
## Future Enhancements
|
|
|
|
- [ ] Advanced 3D model preview with Three.js STL/OBJ loader
|
|
- [ ] Thumbnail generation for models
|
|
- [ ] Batch upload support
|
|
- [ ] Export collections as ZIP
|
|
- [ ] Model versioning
|
|
- [ ] Print history tracking
|
|
- [ ] Filament usage calculator
|
|
- [ ] Public sharing and privacy controls
|
|
- [ ] ActivityPub federation support
|
|
- [ ] Advanced search with faceted filtering
|
|
- [ ] Model duplicate detection
|
|
- [ ] PostgreSQL support
|
|
- [ ] S3/Object storage support
|
|
|
|
## Security Notes
|
|
|
|
- Always change the default `JWT_SECRET` and `SESSION_SECRET` in production
|
|
- Use HTTPS in production
|
|
- Consider adding rate limiting for API endpoints
|
|
- Implement file type validation on the server side
|
|
- Add virus scanning for uploaded files in production
|
|
- Use environment variables for sensitive data
|
|
|
|
## Contributing
|
|
|
|
This is a powerful 3D model management system. Feel free to fork and modify for your needs!
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Acknowledgments
|
|
|
|
- Built with love for makers and the 3D printing community
|
|
|
|
## Support
|
|
|
|
For issues or questions, please check the code and documentation or modify as needed for your use case.
|
|
|
|
## Quick Start Guide
|
|
|
|
1. **Install dependencies**: `npm install`
|
|
2. **Start the server**: `npm start`
|
|
3. **Open browser** to `http://localhost:3000`
|
|
4. **Register** a new account
|
|
5. **Upload** your first 3D model (STL, OBJ, or 3MF)
|
|
6. **Click the 3D cube button** to view models in interactive 3D!
|
|
7. **Create collections and tags** to organize your models
|
|
8. **Enjoy** managing your 3D printing files!
|