Deploying LedgerSMB

Introduction

LedgerSMB is a comprehensive open-source accounting and enterprise resource planning (ERP) system designed for small to medium-sized businesses. Forked from SQL-Ledger in 2006, LedgerSMB has evolved into a robust, security-focused platform that provides professional-grade financial management capabilities without the licensing costs of proprietary solutions.

Built on Perl with a PostgreSQL backend, LedgerSMB implements proper double-entry bookkeeping principles and offers extensive functionality for managing the complete financial lifecycle of a business. The application supports multi-currency transactions, making it suitable for international operations, and includes role-based access control for secure multi-user environments.

Key highlights of LedgerSMB:

• Double-Entry Accounting: Full implementation of generally accepted accounting principles (GAAP) with automatic journal entries
• Accounts Receivable/Payable: Complete customer and vendor management with aging reports and payment tracking
• Invoicing System: Generate professional invoices with customizable templates and automatic tax calculations
• Inventory Management: Track stock levels, manage warehouses, and handle purchase orders
• Point of Sale: Integrated POS functionality for retail operations
• Multi-Currency Support: Handle transactions in multiple currencies with automatic exchange rate management
• Financial Reporting: Generate balance sheets, income statements, and customizable financial reports
• Tax Compliance: Configurable tax rules supporting various jurisdictions and reporting requirements
• Bank Reconciliation: Match transactions and maintain accurate cash flow records
• Role-Based Security: Granular permissions system for protecting sensitive financial data

This guide walks through deploying LedgerSMB on Klutch.sh using Docker, configuring the PostgreSQL database, and setting up the application for production use.

Why Deploy LedgerSMB on Klutch.sh

Deploying LedgerSMB on Klutch.sh provides several advantages for managing your business finances:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds LedgerSMB without complex orchestration. Push to GitHub, and your accounting system deploys automatically.

Persistent Storage: Attach persistent volumes for your PostgreSQL database and uploaded documents. Your financial records survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring encrypted access to sensitive financial data from anywhere.

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

Scalable Resources: Allocate CPU and memory based on your business size and transaction volume. Start small and scale as your needs grow.

Environment Variable Management: Securely store database credentials and configuration through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain for a professional, branded experience when accessing your accounting system.

Always-On Availability: Your financial data remains accessible 24/7 without managing your own infrastructure.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your LedgerSMB configuration
• Basic familiarity with Docker and containerization concepts
• A PostgreSQL database (can be deployed alongside LedgerSMB or as a separate service)
• (Optional) A custom domain for your LedgerSMB instance

Understanding LedgerSMB Architecture

LedgerSMB is built on a proven technology stack:

Perl Backend: The core application is written in Perl, providing stability and extensive library support for financial calculations and reporting.

PostgreSQL Database: All financial data is stored in PostgreSQL, leveraging its advanced features like stored procedures and strong data integrity constraints.

Starman Web Server: The application runs on the Starman PSGI server for handling web requests efficiently.

Template System: LaTeX and HTML templates power the invoice and report generation system.

REST API: Modern REST endpoints enable integration with external systems and automation.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ledgersmb/ledgersmb:1.11

# Environment configuration
ENV POSTGRES_HOST=${POSTGRES_HOST:-postgres}
ENV POSTGRES_PORT=${POSTGRES_PORT:-5432}
ENV DEFAULT_DB=${DEFAULT_DB:-ledgersmb}
ENV SSMTP_ROOT=${SSMTP_ROOT}
ENV SSMTP_MAILHUB=${SSMTP_MAILHUB}
ENV SSMTP_HOSTNAME=${SSMTP_HOSTNAME}

# Create directories for templates and uploads
RUN mkdir -p /var/lib/ledgersmb/templates /var/lib/ledgersmb/uploads

# Expose the web interface port
EXPOSE 5762

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

Creating the .dockerignore File

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

Environment Variables Reference

Variable	Required	Default	Description
POSTGRES_HOST	Yes	postgres	PostgreSQL server hostname
POSTGRES_PORT	No	5432	PostgreSQL server port
DEFAULT_DB	No	ledgersmb	Default database name
SSMTP_ROOT	No	-	Email address for system emails
SSMTP_MAILHUB	No	-	SMTP server for outgoing emails
SSMTP_HOSTNAME	No	-	Hostname for email identification

Deploying LedgerSMB on Klutch.sh

Set Up PostgreSQL Database

LedgerSMB requires PostgreSQL. You can deploy PostgreSQL as a separate Klutch.sh app or use a managed database service. Ensure PostgreSQL has the required extensions enabled (pg_trgm, btree_gist).

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial LedgerSMB deployment configuration"
git remote add origin https://github.com/yourusername/ledgersmb-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. Name it something descriptive like “ledgersmb” or “accounting”.

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

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Add the following environment variables:

Variable	Value
POSTGRES_HOST	Your PostgreSQL hostname
POSTGRES_PORT	5432
DEFAULT_DB	ledgersmb
SSMTP_ROOT	Your admin email (optional)
SSMTP_MAILHUB	Your SMTP server (optional)

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/var/lib/ledgersmb	10 GB	Templates, uploads, and application data

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Initialize the Database

After deployment, access LedgerSMB at your app URL. Use the setup interface to create your company database:

1. Navigate to https://your-app.klutch.sh/setup.pl
2. Enter your PostgreSQL credentials
3. Create a new company database
4. Follow the setup wizard to configure your chart of accounts

Initial Configuration

Setting Up Your Company

After database initialization:

1. Log in with the admin credentials you created
2. Configure company information (name, address, tax ID)
3. Set up your fiscal year and accounting periods
4. Import or create your chart of accounts
5. Configure tax rates for your jurisdiction

User Management

Create accounts for your team:

1. Navigate to System > Users
2. Create user accounts with appropriate roles
3. Assign permissions based on job functions (AP, AR, GL access)

Configuring Email

For invoice delivery and notifications:

1. Configure SMTP settings in the environment variables
2. Test email functionality from the system settings
3. Set up email templates for invoices and statements

Production Best Practices

Security Recommendations

• Use strong passwords for all user accounts
• Enable SSL/TLS for database connections
• Regularly backup your PostgreSQL database
• Keep LedgerSMB updated to receive security patches
• Implement IP restrictions if accessing from known locations

Backup Strategy

1. Schedule regular PostgreSQL backups using pg_dump
2. Back up the /var/lib/ledgersmb directory for templates and uploads
3. Test restore procedures periodically
4. Store backups in a separate location

Performance Optimization

• Index frequently queried columns in the database
• Archive old transactions to maintain performance
• Allocate sufficient memory for PostgreSQL
• Use connection pooling for high-traffic environments

Troubleshooting

Cannot Connect to Database

• Verify PostgreSQL is running and accessible
• Check environment variables for correct credentials
• Ensure required PostgreSQL extensions are enabled
• Verify network connectivity between containers

Login Issues

• Reset user passwords through the database if locked out
• Check that the user account is active
• Verify role assignments are correct

Report Generation Errors

• Ensure LaTeX is properly installed for PDF generation
• Check template syntax for errors
• Verify sufficient disk space for temporary files

Additional Resources

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

Conclusion

Deploying LedgerSMB on Klutch.sh gives you a powerful, self-hosted accounting system with automatic builds, persistent storage, and secure HTTPS access. Whether you’re managing a small business or growing enterprise, LedgerSMB provides the financial management tools you need while maintaining complete control over your data.

With proper configuration and regular maintenance, LedgerSMB on Klutch.sh delivers professional-grade accounting capabilities that scale with your business needs.