Deploying Manyfold

Introduction

Manyfold is a self-hosted digital asset manager specifically designed for 3D printing enthusiasts and professionals. It provides a powerful platform for organizing, previewing, and managing your collection of 3D model files, including STL, OBJ, 3MF, and other common formats used in 3D printing and modeling.

Built with Ruby on Rails, Manyfold offers features that go beyond simple file storage. It automatically generates previews, extracts metadata, and provides a searchable library that makes finding the right model easy, even in collections with thousands of files.

Key highlights of Manyfold:

• 3D File Support: Native support for STL, OBJ, 3MF, PLY, and other common formats
• Automatic Previews: Generates visual thumbnails and interactive 3D previews
• Metadata Extraction: Automatically extracts file dimensions, polygon counts, and more
• Library Organization: Tag, categorize, and organize models into collections
• Full-Text Search: Find models by name, tag, or description
• Multi-User Support: Share your library with others with role-based access
• File Scanning: Automatically scan folders and add new files
• Creator Attribution: Track where models came from (Thingiverse, Printables, etc.)
• Print History: Log which models you’ve printed and with what settings
• Responsive Design: Works on desktop and mobile devices
• Open Source: AGPLv3 licensed with active development

This guide walks through deploying Manyfold on Klutch.sh using Docker, organizing your 3D model library, and getting the most out of its management features.

Why Deploy Manyfold on Klutch.sh

Deploying Manyfold on Klutch.sh provides several advantages:

Centralized Library: Access your entire 3D model collection from any device, anywhere.

Always Available: Browse and download models 24/7 without keeping your home server running.

HTTPS by Default: Automatic SSL certificates ensure secure access to your library.

Persistent Storage: Your models and database persist across deployments.

Scalable Storage: Allocate storage based on your collection size.

Custom Domains: Use a memorable domain for your model library.

Prerequisites

Before deploying Manyfold on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Manyfold configuration
• Basic familiarity with Docker and containerization concepts
• 3D model files to manage (STL, OBJ, 3MF, etc.)

Understanding Manyfold Architecture

Manyfold consists of several components working together:

Rails Application: The core web application handling the UI, API, and business logic.

PostgreSQL Database: Stores model metadata, user information, and library organization.

Redis: Handles background job queuing for file processing.

File Storage: Stores your 3D model files and generated previews.

Background Workers: Process files, generate previews, and extract metadata.

Preparing Your Repository

To deploy Manyfold on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

manyfold-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/manyfold3d/manyfold:latest

# Environment configuration
ENV RAILS_ENV=production
ENV PORT=3214

# Database configuration
ENV DATABASE_URL=${DATABASE_URL}
ENV REDIS_URL=${REDIS_URL}

# Secret key for Rails
ENV SECRET_KEY_BASE=${SECRET_KEY_BASE}

# Storage configuration
ENV STORAGE_PATH=/libraries

# Create necessary directories
RUN mkdir -p /libraries

# Expose the web interface port
EXPOSE 3214

Advanced Dockerfile

For more control over configuration:

FROM ghcr.io/manyfold3d/manyfold:latest

# Core environment
ENV RAILS_ENV=production
ENV PORT=3214

# Database and cache
ENV DATABASE_URL=${DATABASE_URL}
ENV REDIS_URL=${REDIS_URL}

# Security
ENV SECRET_KEY_BASE=${SECRET_KEY_BASE}

# Storage
ENV STORAGE_PATH=/libraries

# Registration settings
ENV REGISTRATION_ENABLED=${REGISTRATION_ENABLED:-true}

# Multiuser mode
ENV MULTIUSER=${MULTIUSER:-true}

# Create directories
RUN mkdir -p /libraries /data

# Expose port
EXPOSE 3214

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL connection string
REDIS_URL	Yes	-	Redis connection string
SECRET_KEY_BASE	Yes	-	Rails secret key (64+ hex characters)
STORAGE_PATH	No	/libraries	Path to store model files
REGISTRATION_ENABLED	No	true	Allow new user registration
MULTIUSER	No	true	Enable multi-user mode

Deploying Manyfold on Klutch.sh

Manyfold requires PostgreSQL and Redis. You can use Klutch.sh’s managed databases or deploy them alongside Manyfold.

Generate a Secret Key

Generate a secure secret key for Rails:

openssl rand -hex 64

Save this key securely for the environment variables configuration.

Set Up PostgreSQL

Either use Klutch.sh’s managed PostgreSQL or deploy your own instance. You’ll need a connection string like:

postgresql://user:password@host:5432/manyfold

Set Up Redis

Either use a managed Redis service or deploy Redis on Klutch.sh. You’ll need a connection string like:

redis://host:6379/0

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore
git commit -m "Initial Manyfold deployment configuration"
git remote add origin https://github.com/yourusername/manyfold-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “manyfold” or “3d-library”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Manyfold Dockerfile.

Configure HTTP Traffic

Manyfold serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3214 (Manyfold’s default port)

Set Environment Variables

In the environment variables section, add:

Variable	Value
DATABASE_URL	Your PostgreSQL connection string
REDIS_URL	Your Redis connection string
SECRET_KEY_BASE	Your generated secret key
REGISTRATION_ENABLED	true (or false after initial setup)

Attach Persistent Volumes

Persistent storage is essential for your model library. Add volumes:

Mount Path	Recommended Size	Purpose
/libraries	100+ GB	3D model files (adjust based on collection)
/data	10 GB	Application data and generated previews

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Manyfold container
• Provision an HTTPS certificate

Access Manyfold

Once deployment completes, access your instance at https://your-app-name.klutch.sh.

Initial Setup and Configuration

Creating Your Admin Account

When you first access Manyfold:

1. Click Sign Up or Register
2. Create your administrator account
3. This first account automatically has admin privileges

Creating Your First Library

1. Click Libraries in the navigation
2. Click New Library
3. Enter a name and path (e.g., /libraries/main)
4. Click Create

Scanning for Files

After creating a library:

1. Upload files to the library path via SFTP or other means
2. Click Scan on the library
3. Manyfold will discover and process new files
4. Preview generation happens in the background

Managing Your 3D Model Library

Uploading Models

Web Upload:

1. Navigate to your library
2. Click Upload
3. Drag and drop files or select from your computer

Direct to Storage: Upload directly to the persistent volume via SFTP for large collections.

Organizing Models

Collections: Group related models together

1. Create a collection from the library view
2. Add models to collections via the model page
3. Use nested collections for complex organization

Tags: Add searchable tags to models

1. Open a model’s detail page
2. Add relevant tags (e.g., “functional”, “miniature”, “vase mode”)
3. Use tags for filtering and searching

Creator Attribution: Track model sources

1. Add creator information (Thingiverse, Printables, etc.)
2. Link to original model pages
3. Respect licensing information

Viewing Models

3D Preview: Interactive 3D viewer for supported formats

• Rotate, zoom, and pan the model
• Toggle wireframe view
• View from preset angles

Metadata: Automatically extracted information

• File dimensions
• Polygon/vertex count
• File size
• Estimated print volume

Print Tracking

Log your prints:

1. Open a model’s page
2. Click Add Print
3. Record settings: material, printer, quality
4. Add notes about the print outcome

Multi-User Features

User Management

As an admin:

1. Go to Settings > Users
2. View all registered users
3. Modify roles and permissions
4. Disable or delete accounts

Roles and Permissions

Role	Capabilities
Admin	Full access, user management
Contributor	Upload, edit own models
Viewer	Browse and download only

Sharing

Share specific collections or libraries with different access levels.

Production Best Practices

Security Recommendations

• Disable Registration: After creating admin account, disable open registration
• Strong Passwords: Require strong passwords for all users
• Regular Updates: Keep Manyfold updated for security patches
• Backup Regularly: Back up both database and files

Storage Management

• Volume Sizing: Plan for growth in your 3D model collection
• Preview Storage: Generated previews add ~10-20% to storage needs
• Cleanup: Remove duplicate files and unused models

Performance Optimization

• Background Processing: Large files are processed asynchronously
• Preview Quality: Balance quality vs. storage for previews
• Database Maintenance: Regular database optimization

Uploading Large Collections

For large existing collections:

SFTP Upload

1. Access your persistent volume via SFTP
2. Organize files into a folder structure
3. Trigger a library scan in Manyfold

Batch Processing

Manyfold processes files in the background:

• Monitor progress in the admin panel
• Large collections may take hours to process
• Preview generation is the most time-intensive step

Troubleshooting Common Issues

Preview Generation Failing

Symptoms: Thumbnails don’t appear for some models.

Solutions:

• Check file format is supported
• Verify the file isn’t corrupted
• Check Redis connection for job processing
• Review logs for specific errors

Database Connection Issues

Symptoms: Application errors on startup.

Solutions:

• Verify DATABASE_URL is correct
• Ensure PostgreSQL is running and accessible
• Check connection string format
• Verify database exists

Files Not Discovered

Symptoms: Uploaded files don’t appear in library.

Solutions:

• Verify files are in the correct library path
• Trigger a manual scan
• Check file permissions
• Ensure supported file format

Slow Performance

Symptoms: Pages load slowly, especially library views.

Solutions:

• Increase allocated resources
• Optimize PostgreSQL settings
• Paginate large libraries
• Use filtering to reduce displayed items

Additional Resources

• Manyfold Official Website
• Manyfold GitHub Repository
• Manyfold Documentation
• Manyfold Discord Community
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Manyfold on Klutch.sh gives you a powerful platform for managing your 3D model library with features designed specifically for the 3D printing community. The combination of automatic preview generation, metadata extraction, and powerful organization tools makes it easy to maintain even large collections.

With persistent storage on Klutch.sh, your models are always accessible from anywhere, making it easy to send files to your printer or share models with friends. Whether you’re an individual hobbyist or running a print farm, Manyfold provides the tools you need to keep your library organized and your workflow efficient.

Take control of your 3D model collection with a self-hosted solution built by the community, for the community.