Day 26: InvoiceShelf – Open Source Invoicing Application – 7 Days of Docker

In today’s digital age, efficient invoicing is crucial for businesses of all sizes. While there are numerous cloud-based solutions available, self-hosting your invoicing software offers greater control, privacy, and customization options. InvoiceShelf is an excellent open-source option that can be easily self-hosted using Docker. This guide will walk you through the entire process of setting up InvoiceShelf on your own server.

What is InvoiceShelf?

InvoiceShelf is a powerful open-source invoicing application designed for individuals and businesses. It’s a fork of Crater that focuses on stability, updates, and new features. Built with Laravel and VueJS for the web application and React Native for mobile apps, InvoiceShelf offers a modern and user-friendly interface.

Key Features

• Professional Invoice & Estimate Creation: Create customizable, professional-looking invoices and estimates.
• Expense Tracking: Keep track of all your business expenses in one place.
• Payment Management: Record and manage payments from clients.
• Multi-Currency Support: Work with clients globally using multiple currencies.
• Customizable Tax Rates: Set up different tax rates for various products or services.
• Recurring Invoices: Automate billing for regular clients.
• Multiple Companies: Manage multiple businesses within a single installation.
• Customer Portal: Allow clients to view and pay invoices online.
• PDF Customization: Create custom templates for your PDF invoices and estimates.
• Multilingual Support: Available in multiple languages including English, French, German, Dutch, Arabic, and more.

Docker Installation

Docker simplifies the deployment process by packaging InvoiceShelf with all its dependencies into a container. This approach ensures consistent behavior across different environments and makes installation and updates much easier.

Prerequisites

• A server or computer with Docker and Docker Compose installed
• Basic knowledge of Docker and command-line operations
• A domain name (optional, but recommended for production use)

Step 1: Install Docker

If you haven’t already installed Docker, you can follow the official instructions for your operating system at https://docs.docker.com/install/.

Step 2: Clone the Docker Repository

Open your terminal and clone the InvoiceShelf Docker repository:

Step 3: Prepare Docker Compose

Navigate to the cloned repository folder and copy one of the example files to create your docker-compose.yml file:

Choose the database option you prefer:

For SQLite (simplest option, no additional database server required):

For MySQL:

For PostgreSQL:

Step 4: Configure Docker Compose

Edit the docker-compose.yml file to adjust the configuration to your needs. You may want to modify:

• Port mappings
• Database credentials (if using MySQL or PostgreSQL)
• Time zone settings
• Application URL and domain
• Volume paths for data persistence

Here’s an example of what you might customize in the docker-compose.yml file:

Step 5: Launch InvoiceShelf

After configuring your docker-compose.yml file, start the application with:

The -d flag runs the containers in detached mode, allowing them to run in the background.

Step 6: Complete the Installation Wizard

Open your web browser and navigate to the URL you specified in your configuration (or http://localhost:YOUR_PORT if you’re running it locally). You’ll be greeted with the InvoiceShelf installation wizard.

Follow the steps in the wizard to complete the setup:

1. Accept the license agreement
2. Choose your language
3. Configure your database connection:
   • For SQLite: Leave the default path as is
   • For MySQL/PostgreSQL:
     • Database Host: invoiceshelf (or as specified in your docker-compose.yml)
     • Database Name: invoiceshelf (or as specified in your docker-compose.yml)
     • Database Username: invoiceshelf (or as specified in your docker-compose.yml)
     • Database Password: The password you set in your docker-compose.yml
4. Create your admin account
5. Configure your company information

Once the installation wizard is complete, you’ll be redirected to the login page where you can start using InvoiceShelf.

Docker Image Tags and Versions

InvoiceShelf provides different Docker image tags to suit various deployment scenarios:

Docker Tag	Purpose	Source Branch	Build Frequency
:latest, :number (e.g., :2.1.0)	Latest stable released version	master (stable release)	On release
:nightly, :dev	Latest stable unreleased version	master (pending release)	Nightly
:alpha	Latest alpha/unstable version	develop (latest code)	Nightly

Which Tag Should You Use?

• For production environments: Use :latest or a specific version number like :2.1.0 for stability
• For testing environments: Use :nightly or :dev to get features that will be in the next release
• For development/adventurous users: Use :alpha to get the very latest code (may be unstable)

Advanced Configuration Options

Environment Variables

InvoiceShelf’s Docker image supports numerous environment variables to customize your installation. Here are some of the most important ones:

• App Configuration:
  • APP_NAME: Your application name (default: InvoiceShelf)
  • APP_ENV: Application environment (production, local, etc.)
  • APP_DEBUG: Enable debug mode (true/false)
  • APP_URL: Your application URL
• Database Configuration:
  • DB_CONNECTION: Database type (sqlite, mysql, pgsql)
  • DB_HOST: Database host (for MySQL/PostgreSQL)
  • DB_PORT: Database port
  • DB_DATABASE: Database name
  • DB_USERNAME: Database username
  • DB_PASSWORD: Database password
• Session and Security:
  • SESSION_DOMAIN: Your domain for session cookies
  • SANCTUM_STATEFUL_DOMAINS: Domains for API authentication
• Docker-specific:
  • PHP_TZ: PHP timezone
  • TIMEZONE: Application timezone
  • STARTUP_DELAY: Delay before starting services (useful for database dependencies)

Using Docker Secrets

For sensitive information like passwords, you can use Docker secrets instead of environment variables:

Supported secret files include:

• DB_PASSWORD_FILE
• REDIS_PASSWORD_FILE
• MAIL_PASSWORD_FILE
• ADMIN_PASSWORD_FILE

Custom PHP and Nginx Configuration

To customize PHP configuration:

1. Mount a custom php.ini file to /etc/php/8.2/fpm/php.ini, or
2. Override specific parameters using PHP_VALUE directive in a custom nginx.conf file

To customize Nginx configuration:

1. Use the default.conf file as a base
2. Modify it according to your needs
3. Mount it to /etc/nginx/nginx.conf

Additional Nginx directives can be added by mounting files to /etc/nginx/conf.d/.

Thoughts

Self-hosting InvoiceShelf with Docker provides you with a powerful invoicing solution that you fully control. The Docker installation process makes it easy to get started, even if you’re not experienced with server administration.

With InvoiceShelf, you can create professional invoices, track expenses, manage payments, and much more—all while keeping your data private and secure on your own infrastructure.

Resources

• InvoiceShelf Website
• InvoiceShelf GitHub Repository
• InvoiceShelf Docker Repository
• InvoiceShelf Documentation
• Docker Hub – InvoiceShelf
• Docker Installation Guide