Aug 25, 2024 3 min read

Invoice Ninja: The Ultimate Guide to Self-Hosting

Invoice Ninja: The Ultimate Guide to Self-Hosting
Table of Contents

Invoice Ninja is a powerful, open-source platform designed to simplify invoicing, expense tracking, and client management for businesses of all sizes. It’s an excellent self-hosting solution for developers and system administrators who need full control over their data and want to customize the application to meet specific needs. This guide walks you through deploying, configuring, and managing Invoice Ninja, covering installation, reverse proxies, logging, backups, updates, and advanced feature usage.

Installing Invoice Ninja

πŸ“¦ Docker/Docker Compose Setup

Docker is the quickest way to deploy Invoice Ninja. Below is a complete docker-compose.yml file tailored for Invoice Ninja:


version: '3.7'

services:

app:

image: invoiceninja/invoiceninja:latest

container_name: invoiceninja_app

restart: unless-stopped

ports:

- "8000:80" # Map application to localhost:8000

environment:

APP_ENV: production

APP_KEY: base64:YOUR_APP_KEY_HERE

APP_DEBUG: "false"

APP_URL: http://yourdomain.com

DB_HOST: db

DB_DATABASE: ninja

DB_USERNAME: ninja

DB_PASSWORD: secret

volumes:

- ./public:/var/www/app/public

- ./storage:/var/www/app/storage

db:

image: mysql:5.7

container_name: invoiceninja_db

restart: unless-stopped

environment:

MYSQL_ROOT_PASSWORD: root_password

MYSQL_DATABASE: ninja

MYSQL_USER: ninja

MYSQL_PASSWORD: secret

volumes:

- ./mysql:/var/lib/mysql

To deploy the application:


mkdir invoiceninja && cd invoiceninja

curl -O https://raw.githubusercontent.com/invoiceninja/dockerfiles/master/docker-compose.yml

docker-compose up -d

πŸš€ Manual Installation

For a manual installation on a Linux server, follow these steps:

  1. Update your system and install dependencies:

sudo apt update && sudo apt upgrade -y

sudo apt install -y php-cli php-fpm php-mysql php-zip php-curl php-xml php-bcmath php-mbstring unzip

  1. Clone the Invoice Ninja repository:

git clone https://github.com/invoiceninja/invoiceninja.git

cd invoiceninja

composer install --no-dev

  1. Create an .env file and configure it:

cp .env.example .env

nano .env

  1. Generate an encryption key and set permissions:

php artisan key:generate

chown -R www-data:www-data /path/to/invoiceninja

chmod -R 775 /path/to/invoiceninja/storage /path/to/invoiceninja/bootstrap/cache

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Use the following Nginx server block to proxy traffic to your Invoice Ninja instance:


server {

server_name yourdomain.com;

location / {

proxy_pass http://127.0.0.1:8000;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $scheme;

}

error_log /var/log/nginx/invoiceninja_error.log;

access_log /var/log/nginx/invoiceninja_access.log;

}

Save this file to /etc/nginx/sites-available/invoiceninja and enable it:


sudo ln -s /etc/nginx/sites-available/invoiceninja /etc/nginx/sites-enabled/

sudo nginx -t

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your domain with Let’s Encrypt:


sudo apt install certbot python3-certbot-nginx -y

sudo certbot --nginx -d yourdomain.com

Automate SSL renewal:


sudo crontab -e

0 0,12 * * * certbot renew --quiet

πŸ› οΈ Testing and Reloading Nginx

Test your configuration:


sudo nginx -t

Reload to apply changes:


sudo systemctl reload nginx

Logging and Debugging Invoice Ninja

πŸ—ƒοΈ Enabling Debug Logs

Enable debug-level logging by editing the .env file:


nano /path/to/invoiceninja/.env

Set the following values:


APP_DEBUG=true

LOG_LEVEL=debug

Restart the application to apply changes.

πŸ“„ Viewing Logs

For Docker users:


docker logs -f invoiceninja_app

For manual installs:


tail -f /path/to/invoiceninja/storage/logs/laravel.log

πŸ› οΈ Troubleshooting Common Issues

If you encounter errors such as a 500 Internal Server Error:

  • Check the Nginx error logs:

sudo tail -f /var/log/nginx/invoiceninja_error.log

πŸ“€ Exporting Logs

To forward logs to an external system, use Filebeat or similar tools to ship laravel.log to the ELK stack or other log aggregators.

Backup and Restore

πŸ—‚οΈ File-Based Backups

Create a tarball of important directories:


tar -czvf invoiceninja_backup.tar.gz /path/to/invoiceninja/public /path/to/invoiceninja/storage

πŸ”„ Database Backups

Export the database:


docker exec invoiceninja_db mysqldump -u ninja -psecret ninja > ninja_backup.sql

Restore it:


docker exec -i invoiceninja_db mysql -u ninja -psecret ninja < ninja_backup.sql

πŸ“… Automated Backup Scripts

Add a cron job to automate backups:


crontab -e

## Add the following line to back up daily:

0 2 * * * tar -czvf /backups/invoiceninja_$(date +\%F).tar.gz /path/to/invoiceninja

Updating and Upgrading Invoice Ninja

⬆️ Updating Docker Images

Pull and apply the latest Docker image:


docker-compose down

docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

For manual installations:


cd /path/to/invoiceninja

git pull origin main

composer install --no-dev

php artisan migrate

πŸ” Checking for Updates

Visit Invoice Ninja’s GitHub to check for the latest releases and announcements.

Leveraging Invoice Ninja’s Unique Features

πŸ”§ Enabling APIs

Enable the API by editing the .env file:


API_ENABLED=true

Test the API using curl:


curl -X POST https://yourdomain.com/api/v1/login \

-H 'Content-Type: application/json' \

-d '{"email": "[email protected]", "password": "password"}'

🌟 Advanced Configurations

Integrate with third-party tools using Zapier or Webhooks:

  • Create a webhook via the Invoice Ninja admin panel.

  • Use ngrok to test webhook endpoints locally:


ngrok http 8000

Wrapping Up

Self-hosting Invoice Ninja gives you full control over your invoicing system, while ensuring data privacy and customization. This guide covered every step from installation to advanced configurations, empowering you to deploy and manage Invoice Ninja effectively. Get started today and explore its rich feature set to streamline your business operations!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.