Deploying Koillection

Introduction

Koillection is a self-hosted collection management application that helps you organize and catalog any type of collection. Whether you collect books, video games, vinyl records, trading cards, or anything else, Koillection provides a beautiful, customizable way to track your items and showcase your collection.

Built with PHP and Symfony, Koillection offers a modern interface with support for custom fields, tags, wishlists, and detailed statistics about your collections. The application emphasizes visual presentation with gallery views, making it a joy to browse through your items.

Key highlights of Koillection:

• Any Collection Type: Track books, games, movies, comics, or any custom category
• Custom Fields: Define exactly what information to track per collection
• Visual Galleries: Beautiful grid and list views with cover images
• Tags and Wishlists: Organize items with tags and track wanted items
• Statistics: View insights about your collection size, value, and more
• Templates: Reuse field configurations across similar collections
• Data Import: Import from CSV or other collection managers
• Multi-User: Share collections with family or keep them private
• Loan Tracking: Keep track of items lent to others
• Mobile Friendly: Responsive design works on all devices
• Dark Mode: Easy on the eyes with dark theme support

This guide walks through deploying Koillection on Klutch.sh using Docker, configuring persistent storage, and setting up your first collection.

Why Deploy Koillection on Klutch.sh

Deploying Koillection on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds Koillection from your Dockerfile without managing PHP infrastructure.

Persistent Storage: Store your database and collection images persistently.

HTTPS by Default: Secure access to your collection with automatic SSL certificates.

Remote Access: View and manage your collection from anywhere.

Always Available: Your collection catalog is accessible 24/7.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker
• A PostgreSQL database (recommended) or MySQL

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

FROM koillection/koillection:latest

# Environment variables configured via Klutch.sh dashboard
# DB_DRIVER - Database driver (pdo_pgsql or pdo_mysql)
# DB_HOST - Database host
# DB_PORT - Database port
# DB_NAME - Database name
# DB_USER - Database user
# DB_PASSWORD - Database password
# APP_SECRET - Application secret key

EXPOSE 80

Environment Variables Reference

Variable	Required	Description
DB_DRIVER	Yes	pdo_pgsql or pdo_mysql
DB_HOST	Yes	Database server hostname
DB_PORT	Yes	Database port (5432 or 3306)
DB_NAME	Yes	Database name
DB_USER	Yes	Database username
DB_PASSWORD	Yes	Database password
DB_VERSION	No	Database version for Doctrine
APP_SECRET	Yes	Random secret for security
APP_DEBUG	No	Enable debug mode (0 or 1)
PHP_TZ	No	PHP timezone
HTTPS_ENABLED	No	Set to 1 behind HTTPS proxy

Creating the .dockerignore File

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

Deploying Koillection on Klutch.sh

Set Up PostgreSQL Database

Koillection works best with PostgreSQL:

• Use a managed PostgreSQL service
• Deploy PostgreSQL on Klutch.sh

Create a database for Koillection:

CREATE DATABASE koillection;
CREATE USER koillection WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE koillection TO koillection;

Generate App Secret

openssl rand -hex 32

Save this for environment variables.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore
git commit -m "Initial Koillection deployment configuration"
git remote add origin https://github.com/yourusername/koillection-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 “koillection” or “my-collection”.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Koillection repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80

Set Environment Variables

Variable	Value
DB_DRIVER	pdo_pgsql
DB_HOST	Your database host
DB_PORT	5432
DB_NAME	koillection
DB_USER	koillection
DB_PASSWORD	Your database password
APP_SECRET	Your generated secret
HTTPS_ENABLED	1
PHP_TZ	Your timezone

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/uploads	5 GB	Collection images and files

Deploy Your Application

Click Deploy to start the build process.

Access Koillection

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

Initial Setup

Creating Your Account

On first access:

1. Click Register to create your account
2. Enter username, email, and password
3. Log in to access your dashboard

Creating Your First Collection

Start organizing:

1. Click New Collection
2. Enter a name (e.g., “Video Games”, “Vinyl Records”)
3. Optionally add a description and cover image
4. Choose visibility settings

Defining Custom Fields

Customize what you track:

1. Go to collection settings
2. Add fields (text, number, date, image, etc.)
3. Mark fields as required or optional
4. Arrange field order

Example fields for a video game collection:

• Platform (list)
• Release Date (date)
• Publisher (text)
• Genre (tags)
• Condition (list)
• Purchase Price (number)
• Cover Art (image)

Organizing Collections

Adding Items

Populate your collection:

1. Navigate to your collection
2. Click Add Item
3. Fill in the custom fields
4. Upload images if desired
5. Save the item

Using Tags

Organize across collections:

1. Add tags when creating/editing items
2. Browse by tag from the sidebar
3. Use tags for cross-collection organization

Wishlists

Track items you want:

1. Create a wishlist in the sidebar
2. Add items you’re looking for
3. Move to collection when acquired

Loan Tracking

Keep track of lent items:

1. On an item, click Loan
2. Enter who borrowed it and when
3. Mark as returned when applicable

Data Management

Importing Data

Migrate from other systems:

1. Go to Settings > Import
2. Upload CSV file with your data
3. Map columns to Koillection fields
4. Review and confirm import

Exporting Data

Back up your collection:

1. Go to Settings > Export
2. Choose format (JSON, CSV)
3. Download your data

Using Templates

Reuse field configurations:

1. Create a template from an existing collection
2. Apply templates when creating new collections
3. Modify as needed for variations

Statistics and Insights

Collection Statistics

View analytics:

• Total items across collections
• Items added over time
• Value tracking (if configured)
• Most common tags

Calendar View

See your collection timeline:

• Items by acquisition date
• Release date calendar
• Loan due dates

Multi-User Setup

User Registration

Enable or disable public registration:

1. Go to Settings > Users
2. Configure registration settings
3. Set default permissions

Sharing Collections

Control visibility:

• Private: Only you can see
• Internal: Logged-in users can view
• Public: Anyone can view

Production Best Practices

Data Protection

• Regular Backups: Back up PostgreSQL and uploads volume
• Export Data: Periodically export collection data
• Image Storage: Ensure adequate space for cover images

Performance

• Image Optimization: Use appropriately sized images
• Database Indexing: PostgreSQL handles this automatically
• Caching: Koillection includes internal caching

Security

• Strong APP_SECRET: Use a cryptographically secure secret
• HTTPS: Always enabled with Klutch.sh
• Strong Passwords: Enforce good password practices

Troubleshooting Common Issues

Database Connection Errors

Solutions:

• Verify database credentials
• Check database driver matches your database type
• Ensure database exists and user has permissions

Images Not Uploading

Solutions:

• Verify uploads volume is mounted
• Check file size limits
• Ensure proper file permissions

Migration Errors

Solutions:

• Run database migrations manually if needed
• Check database version compatibility
• Review application logs

Additional Resources

• Koillection Website
• Koillection Wiki
• Koillection GitHub
• Koillection Docker Hub
• Klutch.sh Persistent Volumes

Conclusion

Deploying Koillection on Klutch.sh gives you a beautiful, self-hosted collection management system with automatic builds, persistent storage, and secure HTTPS access. The combination of Koillection’s flexible schema and Klutch.sh’s deployment simplicity means you can focus on cataloging your treasures rather than managing infrastructure.

Whether you’re tracking a small book collection or managing an extensive catalog of collectibles, Koillection on Klutch.sh provides the tools to organize, visualize, and enjoy your collections.