How To Install InvoicePlane on Debian 13

Managing invoices, quotes, and client payments doesn’t have to drain your budget with expensive subscription fees. InvoicePlane offers a powerful, self-hosted invoicing solution that gives you complete control over your financial data while eliminating recurring costs. This comprehensive guide walks you through installing InvoicePlane on Debian 13, from system preparation to final configuration.

Whether you’re a freelancer tracking client projects or a small business managing multiple invoices, InvoicePlane provides the tools you need without compromising data privacy. Built on open-source principles, this web-based application handles everything from invoice generation to payment tracking, all while running on your own server infrastructure. Let’s dive into the installation process and get your invoicing system up and running.

What is InvoicePlane?

InvoicePlane stands as a free, open-source invoicing application designed for freelancers, small businesses, and organizations seeking complete control over their billing systems. As the spiritual successor to FusionInvoice, this self-hosted solution eliminates the need for costly SaaS subscriptions while providing enterprise-grade functionality.

The platform excels at managing the complete invoicing lifecycle. Generate professional PDF invoices with customizable templates, track quotes from creation to conversion, and monitor payments across multiple currencies. The client management system maintains detailed contact records, project histories, and communication logs in one centralized location.

Beyond basic invoicing, InvoicePlane includes recurring invoice automation, expense tracking, and comprehensive payment gateway integration. Accept payments through PayPal, Stripe, or even cryptocurrency options like Bitcoin via Coinbase integration. The multi-language interface supports global operations, while the theming system allows complete branding customization.

Self-hosting delivers distinct advantages over cloud-based alternatives. Your financial data remains on infrastructure you control, meeting strict data sovereignty requirements. No monthly fees drain your budget, and unlimited users access the system without per-seat pricing. The community-driven development model ensures continuous improvements while maintaining transparency about the platform’s direction and security practices.

System Requirements and Prerequisites

Before beginning the installation process, verify your server meets the necessary specifications for running InvoicePlane smoothly. A Debian 13 system with at least 1GB RAM and 10GB free disk space provides adequate resources for small to medium deployments.

The software stack requires several core components working in harmony. MariaDB version 5.5 or higher handles database operations, though version 10.x is recommended for optimal performance and security. PHP 7.0 represents the minimum version, but Debian 13 typically ships with PHP 8.2 or 8.3, which offer significant performance improvements and security enhancements for web applications.

Apache2 serves as the preferred web server due to its extensive module ecosystem and straightforward configuration. PHP extensions form the backbone of InvoicePlane’s functionality, each serving specific purposes. The GD library processes images for logos and graphics, while Hash provides cryptographic functions for password security. JSON handles data serialization, Mbstring manages multi-byte character encoding for international support, and MySQLi facilitates database connectivity.

Additional extensions include OpenSSL for secure connections and SSL certificate management, XMLRPC for remote procedure calls, Zlib for file compression, and cURL for external API communications. The system also benefits from php-common for shared utilities and php-zip for archive handling.

Administrative access is essential. You’ll need root privileges or a user account with sudo permissions to install packages and modify system configurations. A registered domain name pointing to your server enhances professionalism, though an IP address suffices for testing environments. Basic Linux command-line familiarity helps troubleshoot issues, though this guide provides detailed explanations for each step.

Step 1: Update Debian 13 System

System updates form the foundation of secure server management. Outdated packages contain known vulnerabilities that attackers actively exploit, making this initial step critical for protecting your invoicing data.

Open your terminal and connect to your Debian 13 server via SSH. Execute the package repository update command to refresh the local package index with the latest available versions:

sudo apt update

This command contacts Debian’s package mirrors and downloads metadata about available updates without actually installing anything. The process typically completes within 30 seconds depending on your internet connection.

Next, upgrade all installed packages to their latest versions:

sudo apt upgrade -y

The -y flag automatically confirms the installation, preventing interactive prompts. This upgrade may take several minutes as the system downloads and installs security patches, bug fixes, and feature updates.

For comprehensive system maintenance, consider the distribution upgrade command:

sudo apt dist-upgrade -y

This advanced upgrade handles dependency changes more intelligently, sometimes required for major version transitions. If kernel updates were applied, reboot the server to ensure the new kernel loads properly. Check for reboot requirements by looking for the /var/run/reboot-required file presence.

Step 2: Install Apache Web Server

Apache HTTP Server powers millions of websites worldwide, offering reliability and extensive configuration options. Begin installation with the apt package manager:

sudo apt install apache2 -y

Once installed, start the Apache service immediately:

sudo systemctl start apache2

Configure Apache to launch automatically when the system boots:

sudo systemctl enable apache2

Verify Apache runs correctly by checking its service status:

sudo systemctl status apache2

A green “active (running)” status confirms successful operation. If you’re using UFW (Uncomplicated Firewall), open the necessary ports for web traffic. Allow both HTTP and HTTPS connections:

sudo ufw allow 'Apache Full'

Alternatively, open specific ports:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Apache modules extend functionality beyond basic file serving. Enable URL rewriting for clean InvoicePlane URLs:

sudo a2enmod rewrite

Activate the headers module for HTTP header manipulation:

sudo a2enmod headers

For future SSL configuration, enable the SSL module:

sudo a2enmod ssl

Restart Apache to apply module changes:

sudo systemctl restart apache2

Test the installation by navigating to http://your-server-ip in a web browser. The default Apache welcome page confirms successful configuration.

Step 3: Install MariaDB Database Server

Database systems store all InvoicePlane information, from client records to invoice details. MariaDB provides MySQL compatibility with enhanced performance characteristics.

Install both the server and client components:

sudo apt install mariadb-server mariadb-client -y

Start the database service:

sudo systemctl start mariadb

Enable automatic startup:

sudo systemctl enable mariadb

Confirm MariaDB operates correctly:

sudo systemctl status mariadb

Fresh MariaDB installations contain several security weaknesses. The secure installation script addresses these vulnerabilities interactively:

sudo mysql_secure_installation

The script prompts several questions. Initially, no root password exists, so press Enter when asked for the current password. Choose Yes to set a new root password, then enter a strong passphrase combining uppercase letters, lowercase letters, numbers, and special characters.

Remove anonymous users by selecting Yes. These default accounts exist for testing but present security risks in production. Disallow root login remotely to prevent brute-force attacks against the administrative account. Remove the test database, which serves no purpose in production environments. Finally, reload privilege tables to apply all changes immediately.

Test database access by logging in with the new root credentials:

sudo mysql -u root -p

Enter your password when prompted. The MariaDB prompt confirms successful authentication. Exit the database shell:

EXIT;

Step 4: Install PHP and Required Extensions

PHP processes InvoicePlane’s dynamic content, transforming code into the web interface users interact with. Debian 13 includes modern PHP versions with significant performance improvements over older releases.

Install PHP along with all necessary extensions in a single command:

sudo apt install php php-cli php-fpm php-mysql php-gd php-mbstring php-curl php-xml php-xmlrpc php-zip php-intl php-json php-common libapache2-mod-php -y

Each package serves specific functions within the InvoicePlane ecosystem. The base php package provides core functionality, while php-cli enables command-line script execution. PHP-FPM offers FastCGI process management for improved performance, though Apache’s module works well for most installations.

Database connectivity comes from php-mysql, image manipulation from php-gd, and multi-byte string handling from php-mbstring. External communications require php-curl, XML parsing needs php-xml and php-xmlrpc, and archive handling uses php-zip. Internationalization support comes from php-intl, data serialization from php-json, and shared functions from php-common.

Optimize PHP settings for InvoicePlane operations. Edit the Apache PHP configuration file:

sudo nano /etc/php/8.2/apache2/php.ini

Note: Replace 8.2 with your actual PHP version. Check with php -v if uncertain.

Locate and modify these directives:

upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M
max_execution_time = 300
date.timezone = Asia/Jakarta

These settings allow larger file uploads for logos and attachments, provide adequate memory for complex operations, extend script execution time for large invoice batches, and set the correct timezone for accurate timestamps.

Verify PHP installation by creating a temporary info file:

sudo nano /var/www/html/info.php

Add this single line:

<?php phpinfo(); ?>

Access http://your-server-ip/info.php in your browser. The detailed PHP configuration page confirms successful installation and displays all loaded extensions. Remove this file immediately after verification:

sudo rm /var/www/html/info.php

Restart Apache to load the new PHP configuration:

sudo systemctl restart apache2

Step 5: Create InvoicePlane Database and User

Isolating InvoicePlane data in a dedicated database with restricted user privileges follows security best practices. This approach limits potential damage if credentials are compromised.

Log into MariaDB with administrative privileges:

sudo mysql -u root -p

Enter your root password when prompted. Create a new database exclusively for InvoicePlane:

CREATE DATABASE invoiceplane;

The database name can be customized, but remember your choice for configuration steps. Create a dedicated user account:

CREATE USER 'invoiceplane_user'@'localhost' IDENTIFIED BY 'your_strong_password_here';

Replace your_strong_password_here with a genuinely strong password. Use a password manager to generate random strings containing at least 16 characters with mixed case, numbers, and symbols.

Grant this user complete control over the InvoicePlane database:

GRANT ALL PRIVILEGES ON invoiceplane.* TO 'invoiceplane_user'@'localhost';

This permission scope limits access to only the InvoicePlane database, preventing interference with other applications sharing the server.

Apply privilege changes immediately:

FLUSH PRIVILEGES;

Exit the database shell:

EXIT;

Test the new credentials to confirm proper configuration:

mysql -u invoiceplane_user -p invoiceplane

Successful authentication validates the database setup. Exit and proceed to downloading InvoicePlane.

Step 6: Download InvoicePlane

InvoicePlane releases are distributed through GitHub, ensuring authenticity and version tracking. Install download utilities if not already present:

sudo apt install curl wget unzip -y

Navigate to a temporary working directory:

cd /tmp

Two download methods exist, each with distinct advantages. The direct version download specifies an exact release:

wget https://github.com/InvoicePlane/InvoicePlane/releases/download/v1.6.1/v1.6.1.zip

This approach guarantees consistency, valuable for production environments requiring specific versions. Alternatively, fetch the latest release dynamically using GitHub’s API:

downloadURL=$(curl -s https://api.github.com/repos/InvoicePlane/InvoicePlane/releases/latest | grep browser_download_url | cut -d '"' -f 4)
wget -O invoiceplane.zip $downloadURL

This method always retrieves the newest version, ideal for test environments and staying current with security patches. The command queries GitHub’s API, extracts the download URL, and saves the archive as invoiceplane.zip.

Verify the download completed successfully:

ls -lh invoiceplane.zip

The file size should exceed several megabytes. Corrupted or incomplete downloads show unusually small sizes.

Step 7: Extract and Configure InvoicePlane Files

With InvoicePlane downloaded, prepare the web directory and configure database connectivity. Create the installation directory:

sudo mkdir -p /var/www/html/invoiceplane

Extract the archive contents directly into this location:

sudo unzip invoiceplane.zip -d /var/www/html/invoiceplane

For version-specific downloads, the archive contains a versioned folder requiring an additional move:

unzip v1.6.1.zip
sudo mv InvoicePlane-v1.6.1/* /var/www/html/invoiceplane/

Navigate to the installation directory:

cd /var/www/html/invoiceplane

InvoicePlane includes a sample configuration requiring customization. Copy this template:

sudo cp ipconfig.php.example ipconfig.php

Edit the configuration file with your preferred text editor:

sudo nano ipconfig.php

Modify these critical parameters to match your environment:

define('IP_URL', 'http://yourdomain.com/invoiceplane');
define('DISABLE_SETUP', false);
define('DB_HOSTNAME', 'localhost');
define('DB_USERNAME', 'invoiceplane_user');
define('DB_PASSWORD', 'your_strong_password_here');
define('DB_DATABASE', 'invoiceplane');
define('DB_PORT', '3306');

The IP_URL determines how InvoicePlane generates links within the application. Use your actual domain name or server IP address. Keep DISABLE_SETUP set to false initially, enabling the web-based installation wizard. Enter the database credentials created earlier, ensuring the hostname remains localhost for local database connections.

File permissions control access to InvoicePlane directories and files. Set ownership to the Apache user:

sudo chown -R www-data:www-data /var/www/html/invoiceplane

Apply appropriate permission levels:

sudo chmod -R 755 /var/www/html/invoiceplane

These permissions allow Apache to read files while preventing unauthorized modifications. Two directories require write access for uploads and logging:

sudo chmod -R 777 /var/www/html/invoiceplane/uploads
sudo chmod -R 777 /var/www/html/invoiceplane/application/logs

While 777 permissions grant universal access, these specific directories need write permissions for the web server to function correctly. More restrictive alternatives include setting ownership and 775 permissions if security requirements are stringent.

Step 8: Configure Apache Virtual Host

Virtual hosts allow Apache to serve multiple websites from one server. Create a dedicated configuration for InvoicePlane:

sudo nano /etc/apache2/sites-available/invoiceplane.conf

Insert this comprehensive virtual host configuration:

<VirtualHost *:80>
    ServerAdmin admin@yourdomain.com
    ServerName yourdomain.com
    ServerAlias www.yourdomain.com
    DocumentRoot /var/www/html/invoiceplane
    
    <Directory /var/www/html/invoiceplane/>
        Options +FollowSymlinks
        AllowOverride All
        Require all granted
    </Directory>
    
    ErrorLog ${APACHE_LOG_DIR}/invoiceplane_error.log
    CustomLog ${APACHE_LOG_DIR}/invoiceplane_access.log combined
</VirtualHost>

Replace placeholder values with your actual domain and email address. The ServerName directive sets the primary domain, while ServerAlias handles the www variant. DocumentRoot points to the InvoicePlane installation directory.

The Directory block configures behavior within the application path. FollowSymlinks allows symbolic link traversal, AllowOverride All enables .htaccess files for URL rewriting, and Require all granted permits public access to the application. Separate error and access logs facilitate troubleshooting and monitoring.

Disable the default Apache site to prevent conflicts:

sudo a2dissite 000-default.conf

Enable the InvoicePlane configuration:

sudo a2ensite invoiceplane.conf

Test the configuration syntax for errors:

sudo apache2ctl configtest

A “Syntax OK” message indicates proper configuration. Any errors require correction before proceeding. Restart Apache to activate the new virtual host:

sudo systemctl restart apache2

Step 9: Complete Web-Based Installation

InvoicePlane’s installation wizard simplifies the remaining setup through an intuitive web interface. Open your browser and navigate to your domain or server IP address. The setup screen appears automatically with DISABLE_SETUP set to false.

Click the prominent “Setup” button to begin the installation process. The first screen requests language selection. Choose your preferred language from the dropdown menu and click Continue. This setting affects the installer interface and the default application language.

The prerequisites check automatically validates your server environment. Green checkmarks indicate successful configuration, while red X marks highlight missing requirements. Common issues include disabled PHP extensions or incorrect file permissions. Address any failures before proceeding, as they prevent successful installation.

Database configuration happens automatically using the ipconfig.php settings. The wizard attempts connection with the credentials you specified earlier. Successful connection displays a confirmation message. Connection failures indicate incorrect database credentials, nonexistent databases, or MariaDB service issues.

The database installation phase creates all necessary tables, indexes, and default data. This process takes 10-20 seconds depending on server performance. Progress indicators show completion status.

Administrator account creation establishes your primary access credentials. Enter a valid email address for account recovery and system notifications. Create a strong password different from your database password. Provide your full name and business street address for invoice personalization.

Optional fields include city, state, ZIP code, country, and phone number. While not mandatory, complete information produces more professional invoices. Click Continue to finalize the installation.

The success screen confirms InvoicePlane is ready for use. Click the provided link to access the login page. Enter your administrator email and password to access the dashboard for the first time.

Step 10: Initial Configuration and Setup

The InvoicePlane dashboard provides access to all system functionality. Several configuration steps optimize the application for your specific business needs.

Navigate to System Settings through the gear icon menu. Company Information forms the foundation of professional invoices. Upload your business logo in PNG or JPG format, ensuring dimensions are reasonable to prevent layout issues. Enter your complete business name, address, and contact details.

The currency and date format settings affect how InvoicePlane displays financial information. Select your primary currency from the extensive list, then configure date formats to match local conventions. These settings apply globally but can be overridden for specific clients operating in different regions.

Invoice numbering schemes maintain organization across hundreds or thousands of invoices. Configure the starting number, prefix, and padding length. Common formats include “INV-0001” or “2025-0001” depending on your preference. Test the numbering by creating a sample invoice to verify the format.

Tax configuration becomes critical if you collect sales tax, VAT, or GST. Define tax rates with precise percentages, then assign descriptive names like “VAT 21%” or “Sales Tax 8.5%”. Multiple tax rates accommodate products with different taxation rules.

Email settings enable automatic invoice delivery directly from InvoicePlane. Configure SMTP server details including hostname, port, authentication credentials, and encryption method. Most businesses use services like Gmail, SendGrid, or Amazon SES for reliable email delivery. Test the configuration by sending a test invoice to your own email address.

Invoice templates control the visual presentation of your documents. InvoicePlane includes several professional templates with different layouts. Preview each template with sample data, then customize the selected template with your brand colors and fonts if desired.

Payment gateway integration allows clients to pay invoices directly through the application. Configure PayPal by entering your business account email. Stripe requires API keys from your Stripe dashboard. Each gateway has specific setup instructions accessible through the payment settings section.

User management becomes important for teams or virtual assistants handling invoicing. Create additional user accounts with appropriate permission levels. Administrator accounts control all aspects, while limited users access only necessary functions like creating invoices or viewing reports.

Security hardening includes one final critical step. Edit the ipconfig.php file and change DISABLE_SETUP to true:

sudo nano /var/www/html/invoiceplane/ipconfig.php

This change prevents unauthorized users from re-running the installation wizard, which could potentially overwrite your database.

Step 11: Security Hardening

Production environments demand additional security measures beyond basic installation. Start with file permission review to ensure sensitive files aren’t world-readable.

Restrict the configuration file to prevent unauthorized access:

sudo chmod 640 /var/www/html/invoiceplane/ipconfig.php

This permission allows Apache to read the file while preventing other system users from viewing database credentials.

SSL/TLS encryption protects data transmitted between browsers and your server. Let’s Encrypt provides free SSL certificates with automated renewal. Install the Certbot tool:

sudo apt install certbot python3-certbot-apache -y

Obtain a certificate for your domain:

sudo certbot --apache -d yourdomain.com -d www.yourdomain.com

Certbot automatically configures Apache for HTTPS, creates renewal hooks, and sets up a systemd timer for automatic certificate renewal. Test the SSL configuration by accessing your site via HTTPS.

Firewall configuration restricts network access to essential services only. If using UFW, verify it’s active:

sudo ufw status

Ensure SSH, HTTP, and HTTPS are allowed:

sudo ufw allow OpenSSH
sudo ufw allow 'Apache Full'

Database security extends beyond user permissions. Regular backups protect against data loss from hardware failure, software bugs, or security incidents. Create database backups with mysqldump:

mysqldump -u invoiceplane_user -p invoiceplane > invoiceplane-backup-$(date +%Y%m%d).sql

This command creates a dated backup file. Automate backups with cron jobs running daily or weekly depending on invoice volume.

File backups complement database backups by preserving uploaded documents and customizations:

sudo tar -czf invoiceplane-files-$(date +%Y%m%d).tar.gz /var/www/html/invoiceplane

Store backups on separate servers or cloud storage to protect against complete server loss.

Troubleshooting Common Issues

Even carefully followed instructions occasionally encounter issues. These solutions address the most common InvoicePlane installation problems.

Blank pages after installation typically indicate PHP errors. Check Apache error logs for specific messages:

sudo tail -f /var/log/apache2/invoiceplane_error.log

Missing PHP extensions appear as undefined function errors. Verify all required extensions are loaded:

php -m | grep -E 'gd|mysqli|mbstring|curl|xml'

Missing extensions require installation via apt and Apache restart.

Database connection failures prevent InvoicePlane from accessing stored data. Double-check credentials in ipconfig.php match the database user created earlier. Test database connectivity manually:

mysql -u invoiceplane_user -p invoiceplane

Successful login confirms credentials work, suggesting configuration file typos. MariaDB service status verification ensures the database server runs properly.

404 errors on internal pages indicate mod_rewrite issues. Verify the module is enabled:

sudo apache2ctl -M | grep rewrite

Check that .htaccess exists in the InvoicePlane directory and that AllowOverride All appears in the virtual host configuration.

Upload errors when adding logos or attachments suggest permission problems or PHP limitations. Verify uploads directory permissions allow Apache write access. Check PHP upload settings in php.ini match or exceed your intended file sizes.

Email sending failures require SMTP configuration review. Test with different SMTP providers to isolate whether the issue stems from your mail server or InvoicePlane configuration. Check PHP error logs for specific SMTP error messages guiding troubleshooting.

Additional support resources include the official InvoicePlane documentation at wiki.invoiceplane.com, the community forum for peer assistance, and the GitHub issues page for bug reports and feature requests.

Congratulations! You have successfully installed InvoicePlane. Thanks for using this tutorial for installing the InvoicePlane self host invoice system on Debian 13 “Trixie”. For additional help or useful information, we recommend you check the official InvoicePlane website.