Deploying Inventaire

Introduction

Inventaire is an open-source book sharing platform that allows users to create inventories of their physical books and share them with others. By cataloging what you own and indicating whether items are available for giving, lending, or selling, Inventaire creates a collaborative network where books can find new readers instead of gathering dust on shelves.

Built on top of Wikidata, Inventaire leverages the power of linked open data to provide rich book metadata while contributing back to the commons. When users add books, they help improve the collective knowledge base that benefits everyone.

Key highlights of Inventaire:

• Book Inventory: Catalog your physical book collection easily
• Sharing Options: Mark items as available to give, lend, or sell
• Wikidata Integration: Rich metadata from the open knowledge base
• ISBN Scanning: Add books quickly by scanning barcodes
• Local Discovery: Find books and readers near you
• Groups: Create sharing communities around interests or locations
• Federated Future: Working toward ActivityPub federation
• Mobile Friendly: Responsive design for on-the-go cataloging
• Multilingual: Interface available in many languages
• Privacy Respecting: Control visibility of your inventory
• Open Source: AGPL licensed, community-driven development

This guide walks through deploying Inventaire on Klutch.sh using Docker, setting up your own book sharing community.

Why Deploy Inventaire on Klutch.sh

Deploying Inventaire on Klutch.sh provides several advantages for book sharing:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Inventaire without complex server configuration.

Persistent Storage: Attach persistent volumes for your database and user data. Your book inventories survive container restarts.

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

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Community Building: Host your own local book sharing community independent of the main inventaire.io instance.

Custom Domains: Assign a custom domain for your community’s book platform.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Inventaire configuration
• Basic familiarity with Docker and containerization concepts
• A CouchDB database (can be deployed separately)
• An Elasticsearch instance (for search functionality)

Understanding Inventaire Architecture

Inventaire is built with Node.js and requires several services:

Node.js Application: The main server handling API requests and serving the frontend.

CouchDB: Document database storing users, books, transactions, and all persistent data.

Elasticsearch: Powers the search functionality for finding books and users.

Client Application: Vue.js frontend for the web interface.

Preparing Your Repository

To deploy Inventaire on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

inventaire-deploy/
├── Dockerfile
├── config.js
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine

# Install build dependencies
RUN apk add --no-cache git python3 make g++

# Clone Inventaire
WORKDIR /app
RUN git clone https://github.com/inventaire/inventaire.git .
RUN git clone https://github.com/inventaire/inventaire-client.git client

# Install server dependencies
RUN npm ci

# Install and build client
WORKDIR /app/client
RUN npm ci
RUN npm run build

# Return to server directory
WORKDIR /app

# Set environment variables
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=3006

# CouchDB configuration
ENV COUCH_HOST=${COUCH_HOST:-couchdb}
ENV COUCH_PORT=${COUCH_PORT:-5984}
ENV COUCH_USERNAME=${COUCH_USERNAME}
ENV COUCH_PASSWORD=${COUCH_PASSWORD}

# Elasticsearch configuration
ENV ELASTIC_HOST=${ELASTIC_HOST:-elasticsearch}
ENV ELASTIC_PORT=${ELASTIC_PORT:-9200}

# Expose port
EXPOSE 3006

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3006/ || exit 1

# Start the server
CMD ["npm", "start"]

Configuration File (config.js)

Create a config.js for custom settings:

module.exports = {
  // Instance configuration
  name: 'My Book Community',

  // Host configuration
  host: process.env.HOST || '0.0.0.0',
  port: process.env.PORT || 3006,

  // Public URL
  publicUrl: process.env.PUBLIC_URL || 'https://books.example.com',

  // CouchDB
  db: {
    protocol: 'http',
    host: process.env.COUCH_HOST || 'localhost',
    port: parseInt(process.env.COUCH_PORT) || 5984,
    username: process.env.COUCH_USERNAME,
    password: process.env.COUCH_PASSWORD
  },

  // Elasticsearch
  elasticsearch: {
    host: process.env.ELASTIC_HOST || 'localhost',
    port: parseInt(process.env.ELASTIC_PORT) || 9200
  },

  // Email configuration (optional)
  mailer: {
    enabled: process.env.MAIL_ENABLED === 'true',
    from: process.env.MAIL_FROM,
    service: process.env.MAIL_SERVICE,
    auth: {
      user: process.env.MAIL_USER,
      pass: process.env.MAIL_PASS
    }
  }
}

Environment Variables Reference

Variable	Required	Default	Description
NODE_ENV	No	production	Node.js environment
HOST	No	0.0.0.0	Server bind address
PORT	No	3006	Server port
PUBLIC_URL	Yes	-	Public URL of your instance
COUCH_HOST	Yes	-	CouchDB hostname
COUCH_PORT	No	5984	CouchDB port
COUCH_USERNAME	Yes	-	CouchDB admin username
COUCH_PASSWORD	Yes	-	CouchDB admin password
ELASTIC_HOST	Yes	-	Elasticsearch hostname
ELASTIC_PORT	No	9200	Elasticsearch port

Deploying Inventaire on Klutch.sh

Due to Inventaire’s multi-service requirements, deploy supporting services first:

Deploy CouchDB

Create a CouchDB app on Klutch.sh:

1. Create a new app with the CouchDB image
2. Configure admin credentials
3. Attach persistent volume for data
4. Note the connection details

Deploy Elasticsearch

Create an Elasticsearch app:

1. Use Elasticsearch image (version 7.x recommended)
2. Configure persistent volume for indices
3. Note the connection details

Push Your Repository to GitHub

git init
git add Dockerfile config.js .dockerignore
git commit -m "Initial Inventaire deployment configuration"
git remote add origin https://github.com/yourusername/inventaire-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 “books” or “inventaire”.

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 Inventaire Dockerfile.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

In the environment variables section, add:

Variable	Value
PUBLIC_URL	https://your-app-name.klutch.sh
COUCH_HOST	Your CouchDB hostname
COUCH_USERNAME	CouchDB admin username
COUCH_PASSWORD	CouchDB admin password
ELASTIC_HOST	Your Elasticsearch hostname

Deploy Your Application

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

• Detect your Dockerfile automatically
• Build the container image
• Start the Inventaire server
• Provision an HTTPS certificate

Access Inventaire

Once deployment completes, access your Inventaire instance at https://your-app-name.klutch.sh. Create your first account to get started.

Using Inventaire

Adding Books

Add books to your inventory:

1. By ISBN: Enter ISBN or scan barcode
2. By Search: Search by title or author
3. Manual Entry: Create entries for unlisted books

Inventory Actions

For each book, set its transaction status:

Status	Description
Giving	Free to a good home
Lending	Available to borrow
Selling	For sale at a price
Inventorying	Just cataloging, not sharing

Finding Books

Discover books in your community:

1. Search by title, author, or ISBN
2. Browse nearby inventory (if location enabled)
3. View what’s available in groups you’ve joined

Groups

Create communities around shared interests:

1. Create a Group: For your neighborhood, school, or interest
2. Invite Members: Share invite links
3. Group Inventory: See combined books from all members

Requesting Books

When you find a book you want:

1. Click the request button
2. Message the owner
3. Arrange the transaction
4. Mark as completed when done

Wikidata Integration

Inventaire leverages Wikidata for book metadata:

• Automatic Enrichment: Books gain rich metadata
• Contribution: Missing data can be added to Wikidata
• Linked Data: Connect to the wider knowledge graph

Troubleshooting Common Issues

CouchDB Connection Errors

Symptoms: Application fails to connect to database.

Solutions:

• Verify CouchDB host and credentials
• Ensure CouchDB is running and accessible
• Check network connectivity between services

Search Not Working

Symptoms: Book searches return no results.

Solutions:

• Verify Elasticsearch is running
• Rebuild search indices
• Check Elasticsearch connection settings

Slow Performance

Symptoms: Application responds slowly.

Solutions:

• Increase Node.js memory allocation
• Optimize CouchDB indexes
• Check Elasticsearch cluster health

Additional Resources

• Inventaire.io (Public Instance)
• Inventaire Server GitHub
• Inventaire Client GitHub
• Inventaire Wiki
• Wikidata
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Inventaire on Klutch.sh enables you to create a local book sharing community where physical books can find new readers. By leveraging Wikidata’s open knowledge, your community contributes to and benefits from a global collaborative effort.

Whether you’re building a neighborhood book exchange, a university lending library, or a special interest group’s shared collection, Inventaire on Klutch.sh provides the platform for connecting books with readers who will appreciate them.