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:
- 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
- Clone the Invoice Ninja repository:
git clone https://github.com/invoiceninja/invoiceninja.git
cd invoiceninja
composer install --no-dev
- Create an
.envfile and configure it:
cp .env.example .env
nano .env
- 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
ngrokto 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!
