Deploying LibreKB

Introduction

LibreKB is a lightweight, open-source knowledge base and FAQ management system designed for organizations that need to organize and share information effectively. Built with simplicity in mind, LibreKB provides a straightforward platform for creating searchable article databases, FAQ sections, and documentation portals.

The application is built with PHP and stores content in a MySQL database, making it easy to deploy and maintain. LibreKB focuses on core knowledge base functionality without unnecessary complexity, making it ideal for support teams, internal documentation, and customer-facing help centers.

Key highlights of LibreKB:

• Article Management: Create, edit, and organize knowledge base articles
• Category System: Organize content into hierarchical categories
• Full-Text Search: Find articles quickly with built-in search functionality
• WYSIWYG Editor: Rich text editing for article content
• User Permissions: Control who can view, create, and edit articles
• View Statistics: Track article popularity and usage
• Attachments: Add files and images to articles
• Public and Private Content: Choose visibility for each article
• Simple Interface: Clean, easy-to-navigate design
• Low Resource Usage: Minimal server requirements

This guide walks through deploying LibreKB on Klutch.sh using Docker and setting up your knowledge base.

Why Deploy LibreKB on Klutch.sh

Deploying LibreKB on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds LibreKB from your Dockerfile. Push to GitHub, and your knowledge base deploys automatically.

Persistent Storage: Attach persistent volumes for your database and attachments. Your knowledge base survives restarts.

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

GitHub Integration: Connect your repository directly from GitHub for automatic redeployments.

Scalable Resources: Start with minimal resources and scale as your knowledge base grows.

Environment Variable Management: Securely store database credentials.

Custom Domains: Assign a professional domain for your knowledge base.

Always-On Availability: Your documentation remains accessible 24/7.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• A MySQL/MariaDB database
• (Optional) A custom domain for your knowledge base

Understanding LibreKB Architecture

LibreKB uses a simple architecture:

PHP Application: Core application handling article management and display.

MySQL/MariaDB Database: Stores articles, categories, and user data.

File Storage: Directory for uploaded attachments and images.

Web Server: Apache or Nginx serving the application.

Preparing Your Repository

Repository Structure

librekb-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

FROM php:8.1-apache

# Install required extensions
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    unzip \
    curl \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd mysqli pdo pdo_mysql \
    && rm -rf /var/lib/apt/lists/*

# Enable Apache rewrite module
RUN a2enmod rewrite

# Set working directory
WORKDIR /var/www/html

# Download LibreKB (adjust URL to actual release)
RUN curl -L https://github.com/LibreKB/librekb/archive/refs/heads/main.tar.gz | tar -xz --strip-components=1 || \
    echo "Manual upload required"

# Set permissions
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html

# Expose port
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

CMD ["apache2-foreground"]

Creating the .dockerignore File

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

Environment Variables Reference

Variable	Required	Default	Description
DB_HOST	Yes	-	MySQL server hostname
DB_NAME	Yes	librekb	Database name
DB_USER	Yes	-	Database username
DB_PASSWORD	Yes	-	Database password

Deploying LibreKB on Klutch.sh

Set Up MySQL/MariaDB Database

Deploy a MySQL database and create a database for LibreKB.

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial LibreKB deployment configuration"
git remote add origin https://github.com/yourusername/librekb-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 named “librekb” or “knowledge-base”.

Create a New App

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

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Add the following:

Variable	Value
DB_HOST	Your MySQL hostname
DB_NAME	librekb
DB_USER	Your database username
DB_PASSWORD	Your database password

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/var/www/html/uploads	5 GB	File attachments

Deploy Your Application

Click Deploy to start the build process.

Complete Installation

After deployment, access the setup wizard and configure your knowledge base.

Initial Configuration

Creating Categories

Organize your content:

1. Log in as administrator
2. Navigate to Category Management
3. Create top-level categories
4. Add subcategories as needed

Writing Articles

Add knowledge base content:

1. Click “New Article”
2. Select the appropriate category
3. Enter title and content
4. Set visibility (public/private)
5. Save and publish

User Management

Configure access:

1. Create user accounts for authors
2. Set appropriate permissions
3. Configure public access settings

Production Best Practices

Security Recommendations

• Use strong admin passwords
• Limit write access to trusted users
• Keep PHP and dependencies updated
• Enable HTTPS for all access

Performance Tips

• Enable PHP opcache
• Optimize database queries
• Use CDN for static assets if needed

Backup Strategy

1. Back up MySQL database regularly
2. Back up the uploads directory
3. Export articles periodically

Troubleshooting

Articles Not Displaying

• Check database connection
• Verify article status is published
• Clear any caching

Search Not Working

• Rebuild search index if available
• Check full-text search configuration
• Verify MySQL supports full-text search

Upload Errors

• Check file permissions on upload directory
• Verify PHP upload limits
• Check available disk space

Additional Resources

• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying LibreKB on Klutch.sh gives you a straightforward, self-hosted knowledge base with automatic builds and secure HTTPS access. Its simplicity makes it ideal for organizations that need a no-frills solution for organizing and sharing information.

With persistent storage and automatic deployments, you can focus on creating helpful content rather than managing infrastructure.