Deploying InvoicePlane

Introduction

InvoicePlane is a self-hosted open source application for managing your invoices, clients, and payments. Downloaded more than 100,000 times from 193 countries, InvoicePlane provides a complete invoicing solution for freelancers, small businesses, and organizations who want full control over their financial data.

Built with PHP and using MySQL/MariaDB for data storage, InvoicePlane offers a modern web interface for creating professional invoices, tracking payments, and managing client relationships. The application handles everything from quote generation to recurring invoices and payment tracking.

Key highlights of InvoicePlane:

Complete Invoicing: Create, send, and track professional invoices with customizable templates
Quote Management: Generate quotes and convert them to invoices with one click
Client Management: Maintain detailed client records with contact information and history
Payment Tracking: Record payments and track outstanding balances
Recurring Invoices: Set up automatic recurring invoices for subscription-based services
Multi-Currency Support: Invoice clients in different currencies
Tax Configuration: Configure multiple tax rates and apply them automatically
Custom Fields: Add custom fields to invoices and quotes for specific needs
PDF Generation: Generate professional PDF invoices for download and email
Multi-Language: Interface available in numerous languages
Open Source: Licensed under MIT, completely free with no premium features

This guide walks through deploying InvoicePlane on Klutch.sh using Docker, configuring persistent storage for your financial data, and setting up the application for production use.

Why Deploy InvoicePlane on Klutch.sh

Deploying InvoicePlane on Klutch.sh provides several advantages for managing your invoicing:

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

Persistent Storage: Attach persistent volumes for your database and uploaded files. Your invoices, client data, and configurations survive container restarts and redeployments.

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

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

Scalable Resources: Allocate CPU and memory based on your business needs. Start small and scale as your client base grows.

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

Custom Domains: Assign a custom domain to your InvoicePlane instance for a professional, branded invoicing experience.

Always-On Availability: Your invoicing system remains accessible 24/7 without managing your own hardware.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your InvoicePlane configuration
Basic familiarity with Docker and containerization concepts
(Optional) A custom domain for your InvoicePlane instance

Understanding InvoicePlane Architecture

InvoicePlane follows a traditional LAMP stack architecture:

PHP Application: The core CodeIgniter-based application handling business logic, invoice generation, and user interface.

MySQL/MariaDB Database: Stores all application data including invoices, clients, products, payments, and user accounts.

Web Server: Nginx or Apache serving the PHP application and static assets.

File Storage: Uploaded files, generated PDFs, and custom templates stored on disk.

Preparing Your Repository

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

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM mhzawadi/invoiceplane:latest

# Set environment variables
ENV IP_URL=${IP_URL}
ENV MYSQL_HOST=${MYSQL_HOST}
ENV MYSQL_USER=${MYSQL_USER}
ENV MYSQL_PASSWORD=${MYSQL_PASSWORD}
ENV MYSQL_DATABASE=${MYSQL_DATABASE}

# Create directories for persistent data
RUN mkdir -p /var/lib/invoiceplane/uploads

# Expose the web interface port
EXPOSE 80

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

Creating the .dockerignore File

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

Environment Variables Reference

Variable	Required	Default	Description
`IP_URL`	Yes	-	Full URL of your InvoicePlane instance
`MYSQL_HOST`	Yes	-	MySQL/MariaDB database host
`MYSQL_USER`	Yes	-	Database username
`MYSQL_PASSWORD`	Yes	-	Database password
`MYSQL_DATABASE`	Yes	-	Database name
`ENCRYPTION_KEY`	No	-	Key for encrypting sensitive data
`ENCRYPTION_CIPHER`	No	-	Cipher algorithm for encryption

Deploying InvoicePlane on Klutch.sh

Once your repository is prepared, follow these steps to deploy InvoicePlane:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

Deploy MySQL First

InvoicePlane requires a MySQL or MariaDB database. Deploy a database instance on Klutch.sh first, or use an external managed database service. Note your database connection details.

Create a New App for InvoicePlane

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your InvoicePlane Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80 (default web port)

Set Environment Variables

In the environment variables section, add:

Variable	Value
`IP_URL`	`https://your-app-name.klutch.sh`
`MYSQL_HOST`	Your MySQL host address
`MYSQL_USER`	Your database username
`MYSQL_PASSWORD`	Your database password
`MYSQL_DATABASE`	`invoiceplane`

Attach Persistent Volumes

Add persistent storage for InvoicePlane data:

Mount Path	Recommended Size	Purpose
`/var/lib/invoiceplane`	10 GB	Uploaded files, PDFs, and application data

Deploy Your Application

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

Detect your Dockerfile automatically
Build the container image
Attach the persistent volumes
Start the InvoicePlane container
Provision an HTTPS certificate

Run the Setup Wizard

Once deployment completes, access your InvoicePlane instance at https://your-app-name.klutch.sh/setup. The setup wizard will guide you through:

Database configuration verification
Creating the admin account
Basic system settings

Initial Configuration

Completing Setup

After accessing the setup URL:

Verify database connection settings
Create your administrator account with a strong password
Configure your company information
Set default invoice preferences

Configuring Company Details

After setup, configure your business information:

Navigate to Settings > Company Information
Add your company name, address, and contact details
Upload your company logo
Configure default tax rates
Set your preferred currency

Customizing Invoice Templates

InvoicePlane includes customizable templates:

Go to Settings > Invoice Templates
Choose from available templates or create custom ones
Add your branding colors and logo
Configure header and footer text
Set default payment terms

Managing Clients

Adding Clients

To add new clients:

Navigate to Clients > Create Client
Enter client company name and contact information
Set payment terms and default currency
Add any custom field values
Save the client record

Client Portal

Enable client portal access:

Edit the client record
Generate portal login credentials
Clients can view their invoices and payment history
Configure which information clients can access

Creating Invoices

New Invoice

To create an invoice:

Navigate to Invoices > Create Invoice
Select the client
Add line items with descriptions, quantities, and prices
Apply taxes and discounts
Set due date and payment terms
Preview and save

Recurring Invoices

Set up automatic recurring invoices:

Create an invoice as a template
Navigate to Recurring Invoices
Configure frequency (weekly, monthly, yearly)
Set start and end dates
Enable automatic sending

Production Best Practices

Security Recommendations

Strong Passwords: Use complex passwords for admin and database accounts
ENCRYPTION_KEY: Generate and configure a secure encryption key
Regular Backups: Back up database and uploaded files regularly
Access Control: Limit admin access to trusted personnel
HTTPS Only: Ensure all traffic uses HTTPS (handled by Klutch.sh)

Backup Strategy

Protect your financial data:

Database Backups: Schedule daily MySQL dumps
File Backups: Back up the uploads directory
Export Invoices: Periodically export invoice data to CSV
Test Restores: Regularly verify backup integrity

Performance Optimization

Database Indexing: Ensure proper indexes on frequently queried tables
File Storage: Use adequate storage for growing invoice archives
Memory Allocation: Increase PHP memory for large invoice generation

Troubleshooting Common Issues

Database Connection Errors

Symptoms: Application won’t start or shows connection errors.

Solutions:

Verify MySQL is running and accessible
Check database credentials in environment variables
Ensure database exists and user has proper permissions
Review connection string format

PDF Generation Issues

Symptoms: PDFs won’t generate or appear blank.

Solutions:

Check PHP extensions are installed (GD, mbstring)
Verify disk space for temporary files
Review PHP error logs for specific issues
Increase PHP memory limit if needed

Email Not Sending

Symptoms: Invoices don’t send via email.

Solutions:

Configure SMTP settings in Settings > Email
Verify SMTP credentials and server address
Check for firewall blocking outbound mail
Review email logs for delivery issues

Additional Resources

Conclusion

Deploying InvoicePlane on Klutch.sh gives you a powerful, self-hosted invoicing solution with automatic builds, persistent storage, and secure HTTPS access. The combination of InvoicePlane’s comprehensive features and Klutch.sh’s deployment simplicity means you can focus on running your business rather than managing infrastructure.

With support for professional invoice templates, client management, recurring billing, and payment tracking, InvoicePlane provides everything needed to manage your business finances while keeping complete control over your data.