Deploying InvoiceShelf

Introduction

InvoiceShelf is a powerful open-source web and mobile application that helps you track expenses, payments, and create professional invoices and estimates. As a fork of Crater that focuses on stability, updates, and new features, InvoiceShelf provides a modern invoicing solution for individuals, freelancers, and businesses who want complete control over their financial data.

Built with Laravel and Vue.js, InvoiceShelf offers a responsive web interface alongside native mobile apps. The application handles the complete invoicing workflow from client management to payment tracking, with support for multiple currencies, taxes, and custom fields.

Key highlights of InvoiceShelf:

• Professional Invoices: Create and send customizable PDF invoices with your branding
• Estimates/Quotes: Generate quotes and convert them to invoices seamlessly
• Expense Tracking: Record and categorize business expenses
• Payment Recording: Track payments and outstanding balances
• Recurring Invoices: Automate billing for subscription services
• Multi-Currency: Invoice clients in different currencies with exchange rates
• Tax Management: Configure multiple tax rates and automatic calculations
• Custom Fields: Add custom data fields to invoices and clients
• Reports: Generate financial reports for business insights
• Mobile Apps: Native iOS and Android apps for on-the-go access
• Open Source: Actively maintained with regular updates and improvements

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

Why Deploy InvoiceShelf on Klutch.sh

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

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

Persistent Storage: Attach persistent volumes for your database and files. Your invoices, expenses, and configurations survive container restarts.

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

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

Scalable Resources: Allocate CPU and memory based on your needs. Scale as your business grows.

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

Custom Domains: Assign a custom domain for professional client-facing invoices.

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

Prerequisites

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

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

Understanding InvoiceShelf Architecture

InvoiceShelf uses a modern web application architecture:

Laravel Backend: PHP-based API handling business logic, PDF generation, and data management.

Vue.js Frontend: Single-page application providing a responsive user interface.

Database: Supports MySQL, PostgreSQL, or SQLite for data persistence.

File Storage: Stores uploaded files, generated PDFs, and company assets.

Queue Worker: Background job processing for emails and heavy operations.

Preparing Your Repository

To deploy InvoiceShelf on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM invoiceshelf/invoiceshelf:latest

# Environment variables configured via Klutch.sh
ENV APP_ENV=production
ENV APP_DEBUG=false
ENV LOG_CHANNEL=stderr

# Expose the web interface port
EXPOSE 80

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

Minimal Dockerfile with SQLite

For a lightweight deployment without external database:

FROM invoiceshelf/invoiceshelf:latest

# Use SQLite for simple deployments
ENV DB_CONNECTION=sqlite
ENV DB_DATABASE=/data/database.sqlite

# Create data directory
RUN mkdir -p /data

# Environment configuration
ENV APP_ENV=production
ENV APP_DEBUG=false

EXPOSE 80

Creating the .dockerignore File

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

Environment Variables Reference

Variable	Required	Default	Description
APP_KEY	Yes	-	Laravel application encryption key
APP_URL	Yes	-	Full URL of your InvoiceShelf instance
DB_CONNECTION	No	mysql	Database driver (mysql, pgsql, sqlite)
DB_HOST	Conditional	-	Database host (not needed for SQLite)
DB_PORT	Conditional	-	Database port
DB_DATABASE	Yes	-	Database name or SQLite file path
DB_USERNAME	Conditional	-	Database username
DB_PASSWORD	Conditional	-	Database password
MAIL_MAILER	No	smtp	Email driver
MAIL_HOST	No	-	SMTP server address

Deploying InvoiceShelf on Klutch.sh

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

Generate Your Application Key

Generate a Laravel application key:

php -r "echo 'base64:'.base64_encode(random_bytes(32));"

Or use OpenSSL:

echo "base64:$(openssl rand -base64 32)"

Save this key for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

Deploy Database (If Using MySQL/PostgreSQL)

If not using SQLite, deploy a database instance on Klutch.sh first. Note your database connection details.

Create a New App for InvoiceShelf

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

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

For SQLite deployment:

Variable	Value
APP_KEY	Your generated application key
APP_URL	https://your-app-name.klutch.sh
DB_CONNECTION	sqlite
DB_DATABASE	/data/database.sqlite

For MySQL/PostgreSQL deployment:

Variable	Value
APP_KEY	Your generated application key
APP_URL	https://your-app-name.klutch.sh
DB_CONNECTION	mysql or pgsql
DB_HOST	Your database host
DB_PORT	3306 or 5432
DB_DATABASE	invoiceshelf
DB_USERNAME	Your database username
DB_PASSWORD	Your database password

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
/data	10 GB	Database (SQLite), uploads, and generated files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build and start your InvoiceShelf instance.

Complete Installation

Access your InvoiceShelf instance at https://your-app-name.klutch.sh. The setup wizard will guide you through initial configuration.

Initial Configuration

Setup Wizard

On first access, complete the installation wizard:

1. Requirements Check: Verify all system requirements are met
2. Database Setup: Confirm database connection
3. Company Information: Enter your business details
4. Admin Account: Create the administrator account
5. Complete Setup: Finalize installation

Company Configuration

After setup, configure your company:

1. Go to Settings > Company Information
2. Upload your company logo
3. Enter business address and contact details
4. Configure default currency
5. Set fiscal year settings

Invoice Customization

Customize your invoice appearance:

1. Navigate to Settings > Customization
2. Select or create invoice templates
3. Add your branding colors
4. Configure default payment terms
5. Set invoice numbering format

Managing Invoices

Creating Invoices

To create a new invoice:

1. Navigate to Invoices > New Invoice
2. Select or create a customer
3. Add line items with descriptions and amounts
4. Apply taxes and discounts
5. Set due date
6. Preview and save

Sending Invoices

Send invoices to clients:

1. Open the invoice
2. Click “Send Invoice”
3. Customize the email message
4. Send directly or schedule delivery

Recording Payments

Track received payments:

1. Open the invoice
2. Click “Record Payment”
3. Enter payment amount and date
4. Select payment method
5. Add any notes

Expense Management

Recording Expenses

Track business expenses:

1. Navigate to Expenses > New Expense
2. Select expense category
3. Enter amount and date
4. Attach receipt if available
5. Associate with customer if billable

Categories

Organize expenses with categories:

1. Go to Settings > Categories
2. Create expense categories
3. Set default categories for common expenses
4. Use for reporting and tax purposes

Production Best Practices

Security Recommendations

• APP_KEY Security: Never expose your application key
• Strong Passwords: Use complex passwords for admin accounts
• Database Security: Restrict database access to the application only
• Regular Updates: Keep InvoiceShelf updated for security patches
• Backup Encryption: Encrypt backup files containing financial data

Backup Strategy

1. Database Backups: Daily automated database backups
2. File Backups: Regular backups of uploads directory
3. Configuration Export: Export settings periodically
4. Off-Site Storage: Store backups in a separate location

Email Configuration

For sending invoices via email:

1. Configure SMTP settings in environment variables
2. Set up email templates in Settings > Email
3. Test email delivery before going live
4. Consider using transactional email services

Troubleshooting Common Issues

Application Key Errors

Symptoms: Encryption/decryption errors or session issues.

Solutions:

• Verify APP_KEY is set correctly
• Ensure key format includes “base64:” prefix
• Never change APP_KEY after initial setup (data loss)

Database Migration Errors

Symptoms: Schema errors or missing tables.

Solutions:

• Run migrations via artisan command
• Check database permissions
• Verify database connection settings

PDF Generation Issues

Symptoms: PDFs won’t generate or are corrupted.

Solutions:

• Check available disk space
• Verify PDF libraries are installed
• Review PHP memory limits

Additional Resources

• Official InvoiceShelf Documentation
• InvoiceShelf GitHub Repository
• Docker Installation Guide
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying InvoiceShelf on Klutch.sh gives you a modern, full-featured invoicing solution with automatic builds, persistent storage, and secure HTTPS access. The combination of InvoiceShelf’s comprehensive features and Klutch.sh’s deployment simplicity means you can focus on your business rather than infrastructure management.

With support for professional invoicing, expense tracking, payment management, and mobile access, InvoiceShelf provides everything needed to manage your business finances while keeping complete control over your data.