Skip to content
Klutch.sh Docs

Deploying Shelf

Introduction

Shelf is a modern, self-hosted asset management and inventory tracking system designed for small to medium organizations. It provides an intuitive interface for tracking physical assets, equipment, and inventory with features like QR code labels, custom fields, location tracking, and custody management.

Built with Remix on the frontend and a modern Node.js backend, Shelf offers a responsive user experience that works well on both desktop and mobile devices. The QR code integration allows for quick asset lookups by scanning labels, making it ideal for equipment check-out systems and inventory audits.

Key highlights of Shelf:

  • QR Code Labels: Generate and print QR codes for asset tracking
  • Custom Fields: Define custom attributes for different asset types
  • Location Tracking: Organize assets by locations and sub-locations
  • Custody Management: Track who has which equipment
  • Categories and Tags: Flexible asset organization
  • Asset Images: Attach photos to asset records
  • CSV Import/Export: Bulk data management
  • Search and Filtering: Find assets quickly
  • Activity Log: Track asset history and changes
  • 100% Open Source: Licensed under AGPL-3.0

This guide walks through deploying Shelf on Klutch.sh using Docker, setting up your asset database, and organizing your inventory.

Why Deploy Shelf on Klutch.sh

Deploying Shelf on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles container orchestration without complex setup.

Persistent Storage: Attach persistent volumes for database and asset images.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access.

Mobile Access: Access your asset database from anywhere for quick lookups.

Custom Domains: Use your own domain for a professional asset management system.

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your Shelf configuration
  • Basic familiarity with Docker and containerization concepts
  • A PostgreSQL database

Preparing Your Repository

Create a GitHub repository with your Shelf configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/shelf-nu/shelf:latest


# Environment variables
ENV NODE_ENV=production
ENV DATABASE_URL=${DATABASE_URL}
ENV SESSION_SECRET=${SESSION_SECRET}
ENV SERVER_URL=${SERVER_URL}


# SMTP configuration (optional)
ENV SMTP_HOST=${SMTP_HOST:-}
ENV SMTP_PORT=${SMTP_PORT:-587}
ENV SMTP_USER=${SMTP_USER:-}
ENV SMTP_PWD=${SMTP_PWD:-}
ENV SMTP_FROM=${SMTP_FROM:-}


# Expose the web interface port
EXPOSE 3000

Environment Variables Reference

VariableRequiredDefaultDescription
DATABASE_URLYes-PostgreSQL connection string
SESSION_SECRETYes-Secret for session encryption
SERVER_URLYes-Public URL of your Shelf instance
SMTP_HOSTNo-SMTP server for email notifications
SMTP_PORTNo587SMTP server port
SMTP_USERNo-SMTP username
SMTP_PWDNo-SMTP password
SMTP_FROMNo-Email sender address
INVITE_EXPIRY_TTL_DAYSNo7Days until invite links expire

Deploying Shelf on Klutch.sh

    Set Up Database

    Shelf requires a PostgreSQL database. Deploy a PostgreSQL instance or use a managed database service.

    Generate Session Secret

    Generate a secure session secret:

    Terminal window
    openssl rand -hex 32

    Push Your Repository to GitHub

    Initialize and push your repository:

    Terminal window
    git init
    git add Dockerfile .dockerignore
    git commit -m "Initial Shelf deployment configuration"
    git remote add origin https://github.com/yourusername/shelf-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 with a descriptive name like “shelf” or “asset-management”.

    Create a New App

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

    Configure HTTP Traffic

    In the deployment settings:

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

    Set Environment Variables

    Add the following environment variables:

    VariableValue
    DATABASE_URLpostgresql://user:password@host:5432/shelf
    SESSION_SECRETYour generated secret
    SERVER_URLhttps://your-app-name.klutch.sh

    Attach Persistent Volumes

    Add the following volume:

    Mount PathRecommended SizePurpose
    /app/public/uploads10 GBAsset images and attachments

    Deploy Your Application

    Click Deploy to start the build process.

    Access Shelf

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

Initial Configuration

Creating Your Account

  1. Navigate to your Shelf instance
  2. Click Sign Up to create an admin account
  3. Verify your email if SMTP is configured
  4. Log in to access the dashboard

Setting Up Locations

  1. Go to Locations in the sidebar
  2. Click New Location
  3. Enter location name and description
  4. Create sub-locations for detailed organization

Creating Categories

  1. Go to Categories
  2. Click New Category
  3. Set category name and color
  4. Categories help organize different asset types

Adding Custom Fields

  1. Go to Custom Fields
  2. Click New Custom Field
  3. Configure:
    • Field name
    • Field type (text, number, date, boolean, option)
    • Required/optional
  4. Assign to categories

Managing Assets

Adding Assets

  1. Click New Asset
  2. Enter asset details:
    • Title and description
    • Category
    • Location
    • Custom field values
  3. Upload images
  4. Save the asset

QR Code Labels

  1. Open an asset
  2. Click the QR code icon
  3. Print or download the QR code
  4. Attach to the physical asset
  5. Scan with mobile to view asset details

Custody Tracking

  1. Open an asset
  2. Click Assign Custody
  3. Select the person or team
  4. Add notes if needed
  5. Track check-outs and returns

Bulk Import

  1. Go to Settings > Import
  2. Download the CSV template
  3. Fill in asset data
  4. Upload and import

Troubleshooting

Database Connection Error

Symptoms: Application fails to start or shows database errors.

Solutions:

  • Verify DATABASE_URL is correct
  • Ensure database server is accessible
  • Check database user permissions
  • Run migrations if needed

Images Not Loading

Symptoms: Asset images don’t display.

Solutions:

  • Verify persistent volume is mounted
  • Check file permissions
  • Ensure SERVER_URL is correct

QR Codes Not Scanning

Symptoms: Mobile scanning fails to open asset page.

Solutions:

  • Verify SERVER_URL matches your actual URL
  • Ensure HTTPS is working
  • Check QR code print quality

Additional Resources

Conclusion

Deploying Shelf on Klutch.sh gives you a modern asset management system that makes tracking equipment and inventory straightforward. With QR code labels, custom fields, and custody tracking, Shelf provides the tools you need to keep your physical assets organized and accountable.