Invoice Ninja on VPS: installation, configuration, and maintenance

Invoice Ninja on VPS is a powerful solution for automating invoicing, client management, and payment tracking. It provides full control over your financial data and helps you avoid monthly cloud service subscriptions, offering flexibility and security by deploying on your own virtual server.

What is Invoice Ninja and why choose it for VPS?

Invoice Ninja is an open-source platform for invoicing and project management, designed for freelancers, small, and medium-sized businesses. It provides a comprehensive set of tools to automate financial workflows, from creating professional invoices to managing payments and reports. The ability to deploy Invoice Ninja on a VPS allows you to fully control your data, customize the system to your unique business requirements, and ensure maximum performance without relying on third-party providers.

Key Features of Invoice Ninja

Invoice Ninja offers extensive functionality that makes it an attractive choice for many companies:

• Create and Send Invoices: Quickly generate professional invoices with support for various currencies, taxes, and discounts. Ability to send invoices via email directly from the system.
• Client Management: Centralized client database with a history of all interactions, invoices, and payments.
• Payment Tracking: Integration with over 40 payment gateways (PayPal, Stripe, Braintree, etc.) for accepting online payments. Automatic tracking of payment statuses and reminders for overdue invoices.
• Quotes and Estimates: Create and send quotes to clients, which can be easily converted into invoices upon approval.
• Time and Expense Tracking: Modules for tracking work time by project and recording expenses, which can then be included in invoices.
• Customizable Templates: Flexible invoice and quote templates that can be branded to match your company's style.
• Reports and Analytics: Detailed reports on income, expenses, overdue payments, and other financial metrics.
• Multi-currency and Multi-language: Support for multiple currencies and languages, convenient for international business.
• API: Extensive API for integration with other business tools.

Advantages of Invoice Ninja self-hosted solution on VPS

Choosing a self-hosted Invoice Ninja on a VPS offers several critically important advantages compared to cloud versions or other SaaS solutions:

• Full Data Control: All your financial data is stored on your own server, enhancing security and privacy. You are not dependent on the data retention policies of third-party companies.
• Flexibility and Customization: You can modify the code, integrate Invoice Ninja with your other systems, install your own plugins, and customize functionality to your specific business needs without limitations.
• Long-term Savings: While initial VPS setup is required, in the long run, a self-hosted solution often proves more cost-effective than monthly cloud service subscriptions, especially as your business grows.
• Performance: You can optimize VPS resources specifically for Invoice Ninja's needs, ensuring maximum operating speed and interface responsiveness, which is not always achievable in a multi-user cloud environment.
• Independence: You are not subject to sudden changes in pricing policies, service shutdowns, or other restrictions that might arise with a cloud provider.

Deploying Invoice Ninja on a server via Docker Compose significantly simplifies the installation and management process, isolating the application with all its dependencies in containers, ensuring stability and portability.

System Requirements for Invoice Ninja and VPS Selection

Before proceeding with Invoice Ninja installation, it's important to ensure that your VPS meets the minimum system requirements. While Docker greatly simplifies dependency management, basic server resources play a key role in application performance.

Minimum and Recommended Specifications

Invoice Ninja 5.x, especially when running via Docker, has fairly moderate requirements for small to medium workloads. However, like any web application, its performance directly depends on available resources.

Minimum Requirements for Invoice Ninja (for 1-5 users, up to 1000 invoices):

• Operating System: Ubuntu 20.04+, Debian 10+, CentOS 7+ (Ubuntu LTS is preferred for easier Docker installation).
• Processor (CPU): 1 vCPU with 2.0+ GHz clock speed.
• Random Access Memory (RAM): 2 GB (including OS and Docker).
• Disk Space: 20 GB NVMe SSD (for better database performance).
• PHP: 8.1+ (managed by Docker container).
• Database: MySQL 5.7+ or PostgreSQL 10+ (managed by Docker container).
• Web Server: Nginx or Apache (for reverse proxy).

Recommended Requirements for Invoice Ninja (for 5-20 users, up to 5000+ invoices):

• Operating System: Ubuntu 22.04 LTS.
• Processor (CPU): 2 vCPU with 2.5+ GHz clock speed.
• Random Access Memory (RAM): 4 GB.
• Disk Space: 40-60 GB NVMe SSD (for data growth and fast operations).
• PHP: 8.2+ (managed by Docker container).
• Database: MySQL 8.0+ or PostgreSQL 14+ (managed by Docker container).
• Web Server: Nginx with HTTP/2 and Brotli/Gzip compression.

Which VPS to choose for Invoice Ninja on a server

Choosing the right VPS for Invoice Ninja on a server is critical for stable and fast operation. Valebyte offers a wide range of VPS plans that are ideally suited for such tasks. Here's what to consider when choosing:

1. Disk Type: Always choose a VPS with NVMe SSD. This significantly speeds up database operations and application loading, which is especially important for financial systems.
2. Server Location: Choose a data center that is geographically closer to your primary audience or to you to minimize latency.
3. Scalability: Ensure that the provider allows you to easily scale resources (CPU, RAM, disk) as your business needs grow.
4. Availability and Support: Reliable uptime and prompt technical support are important for any business-critical application.

The table below will help you navigate VPS configuration selection depending on the expected load:

Parameter	Low Load (1-5 users, up to 1000 invoices)	Medium Load (5-20 users, up to 5000 invoices)	High Load (20+ users, 5000+ invoices, integrations)
CPU	1 vCPU (2.0+ GHz)	2 vCPU (2.5+ GHz)	4+ vCPU (3.0+ GHz)
RAM	2 GB	4 GB	8+ GB
Disk	20 GB NVMe SSD	40-60 GB NVMe SSD	80-120 GB NVMe SSD
Traffic	500 GB - 1 TB	1 TB - 2 TB	2 TB+
Approximate Cost (Valebyte)	from ~$5-7/month	from ~$10-15/month	from ~$20-30+/month

To start, a plan with 2GB RAM and 1-2 vCPU on an NVMe disk will be an optimal choice for most users beginning with Invoice Ninja on VPS. As you grow, you can always increase resources.

Preparing the VPS for Invoice Ninja Installation

After selecting and configuring your VPS, you need to perform a series of preparatory steps. We will use Ubuntu 22.04 LTS as the most popular and well-supported operating system for server applications.

System Update and Dependency Installation

First, connect to your VPS via SSH. Make sure you are using a user with sudo privileges or root.

ssh user@your_vps_ip_address

Update the package list and installed packages to the latest versions:

sudo apt update
sudo apt upgrade -y

Install necessary utilities such as git (for cloning the Invoice Ninja Docker repository) and curl (for downloading Docker):

sudo apt install -y git curl

Installing Docker and Docker Compose

Invoice Ninja Docker is the recommended installation method as it simplifies dependency management and provides a consistent environment. Let's install Docker Engine and Docker Compose.

Installing Docker Engine:

Add Docker's official GPG key:

sudo apt update
sudo apt install ca-certificates curl gnupg -y
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Add the Docker repository to APT sources:

echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update

Install Docker Engine, containerd, and Docker Compose (cli):

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Add your user to the docker group so you don't need to use sudo for every Docker command (you'll need to log out and back in or restart your SSH session after this):

sudo usermod -aG docker $USER

Exit SSH and log in again for the changes to take effect.

Verify that Docker is installed correctly by running a test container:

docker run hello-world

If you see the message "Hello from Docker!", then the installation was successful.

Ensure Docker Compose (now part of Docker CLI) is working:

docker compose version

You should see the Docker Compose version.

Your VPS is now ready for Invoice Ninja installation using Docker Compose.

Installing Invoice Ninja on VPS with Docker Compose

Now that your VPS is prepared, we can proceed with the actual Invoice Ninja installation using official Docker images and Docker Compose. This method ensures that all dependencies are correctly configured and isolated.

Cloning the Repository and Environment Setup

Navigate to your home directory or any other directory where you want to store Invoice Ninja configuration files. Create a project directory and enter it:

mkdir -p ~/invoiceninja
cd ~/invoiceninja

Clone the official Invoice Ninja Dockerfiles repository. This contains the necessary docker-compose.yml file and other scripts:

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

Copy the example environment variables file and edit it. This file contains key settings for Invoice Ninja and the database. Pay attention to .env.example and .env.

cp .env.example .env
nano .env

In the .env file, you will need to configure the following parameters:

• APP_URL: Specify the domain name through which Invoice Ninja will be accessible (e.g., https://invoice.yourdomain.com). This is critically important for the application to function correctly.
• APP_KEY: This is the encryption key. If it's not present, it will be automatically generated on the first run, but it's better to ensure it's there.
• DB_PASSWORD: Set a strong password for the MySQL/MariaDB database user. This is very important for security.
• MYSQL_ROOT_PASSWORD: Set a strong password for the root user of the MySQL/MariaDB database.
• APP_DEBUG: In production, set to false. For debugging, you can temporarily set it to true.

Example fragment of the .env file:

APP_URL=https://invoice.valebyte.com
APP_KEY=SomeRandomStringOf32CharactersOrMore # If not present, it will be generated
APP_DEBUG=false
APP_ENV=production

# Database Settings
DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=ninja
DB_USERNAME=ninja
DB_PASSWORD=YOUR_STRONG_DB_PASSWORD

# MySQL Root Password (Used by docker-compose to create the database)
MYSQL_ROOT_PASSWORD=YOUR_STRONG_MYSQL_ROOT_PASSWORD

# Timezone (e.g., Europe/Moscow)
APP_TIMEZONE=UTC

Save changes (Ctrl+O, then Enter) and close the editor (Ctrl+X).

Starting Invoice Ninja Containers

Now that the .env file is configured, you can start all services using Docker Compose. The -d command runs containers in the background (detached mode).

docker compose up -d

This command will download the necessary Docker images (nginx, php-fpm, mysql/mariadb) and start the containers. The process may take several minutes depending on your internet connection speed.

After starting the containers, ensure they are all running:

docker compose ps

You should see an Up status for all services (app, db, nginx).

Now you need to perform database migrations and create an administrator. For this, we will use the php artisan command inside the app container:

docker compose exec app php artisan migrate --seed --force

This command will execute all necessary database migrations and populate it with initial data (--seed). The --force flag is required because we are running migrations in a production environment.

Next, create the first administrator. You will be prompted to enter a name, email, and password:

docker compose exec app php artisan ninja:create-admin

After successfully executing these commands, the basic Invoice Ninja installation is complete. The application is now running inside Docker containers and accessible via port 8080 of your VPS (or another port if you changed it in docker-compose.yml). However, for full functionality with a domain name and HTTPS, we will need to configure a reverse proxy.

If you are interested in deploying other useful business tools on your VPS, we recommend checking out our article on NocoDB on VPS: installation, configuration, and maintenance, which also uses Docker.

Configuring Reverse Proxy and HTTPS for Invoice Ninja

To ensure secure and convenient access to Invoice Ninja via a domain name (e.g., https://invoice.yourdomain.com) and to use HTTPS, you need to configure a reverse proxy. We will cover two popular options: Nginx and Caddy.

Before you begin, make sure your domain or subdomain points to your VPS's IP address (A or CNAME records in your DNS zone).

Configuring Nginx as a Reverse Proxy

Nginx is a high-performance web server that is excellent for acting as a reverse proxy. If you haven't installed Nginx yet, do so:

sudo apt install nginx -y

Create a new configuration file for Invoice Ninja in the /etc/nginx/sites-available/ directory:

sudo nano /etc/nginx/sites-available/invoice.conf

Insert the following configuration, replacing invoice.yourdomain.com with your domain name:

server {
    listen 80;
    server_name invoice.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name invoice.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/invoice.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/invoice.yourdomain.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/invoice.yourdomain.com/chain.pem;

    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    root /var/www/html/public; # Path to Invoice Ninja files, if Docker Nginx is not used
    index index.php index.html index.htm;

    location / {
        proxy_pass http://localhost:8080; # Port on which the Invoice Ninja Docker Nginx container listens
        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;
        proxy_redirect off;
    }

    # Optional: Deny access to .env file if it's somehow exposed
    location ~ /\.env {
        deny all;
    }

    # Optional: Deny access to storage directory if it's somehow exposed
    location ~ /storage {
        deny all;
    }
}

Save and close the file.

Create a symbolic link to this file in the sites-enabled directory so Nginx picks it up:

sudo ln -s /etc/nginx/sites-available/invoice.conf /etc/nginx/sites-enabled/

Check the Nginx configuration for errors:

sudo nginx -t

If there are no errors, restart Nginx:

sudo systemctl restart nginx

Installing an SSL certificate with Let's Encrypt (Certbot):

Install Certbot and the Nginx plugin:

sudo apt install certbot python3-certbot-nginx -y

Obtain and install the SSL certificate. Certbot will automatically configure Nginx:

sudo certbot --nginx -d invoice.yourdomain.com

Follow the on-screen instructions. Certbot will ask you for an email for notifications and to agree to the terms. After that, it will automatically update your Nginx configuration to use HTTPS.

If you use Nginx as a reverse proxy for other applications, such as for Kanboard on VPS, the setup process will be similar.

Configuring Caddy as a Reverse Proxy

Caddy is a modern web server with automatic HTTPS support via Let's Encrypt, which greatly simplifies configuration. If you prefer Caddy, first install it:

Installing Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

Create a Caddyfile for Invoice Ninja:

sudo nano /etc/caddy/Caddyfile

Add the following configuration, replacing invoice.yourdomain.com with your domain name:

invoice.yourdomain.com {
    reverse_proxy localhost:8080 # Port on which the Invoice Ninja Docker Nginx container listens
}

Save and close the file.

Check the Caddy configuration:

sudo caddy validate --config /etc/caddy/Caddyfile

Restart Caddy to apply the changes:

sudo systemctl reload caddy

Caddy will automatically obtain and configure an SSL certificate for your domain. You can now access Invoice Ninja at https://invoice.yourdomain.com.

Invoice Ninja Maintenance: Backups, Updates, and Monitoring

Regular maintenance is key to the stable and secure operation of any application, especially one as critical as an invoicing system. This includes data backup, timely updates, and system health monitoring.

Data Backup Strategies

Backup is the most important aspect of maintenance. Your invoices, client data, and payment information must be securely protected. Invoice Ninja stores data in two main locations: the database (MySQL/MariaDB) and the file system (uploaded logos, attached files, PDF invoices).

1. Database Backup:

The database is the heart of Invoice Ninja. Perform a database backup from the container:

docker compose exec db mysqldump -u ninja -pYOUR_STRONG_DB_PASSWORD ninja > ~/invoiceninja_backup/ninja_db_$(date +%F_%H-%M-%S).sql

Replace YOUR_STRONG_DB_PASSWORD with your actual password from the .env file. First, create a directory for backups: mkdir -p ~/invoiceninja_backup.

2. File Backup:

You need to copy the storage directory from the app container, as well as your .env file:

cp ~/invoiceninja/.env ~/invoiceninja_backup/.env_$(date +%F_%H-%M-%S)
docker cp invoiceninja-app-1:/var/www/app/storage ~/invoiceninja_backup/storage_$(date +%F_%H-%M-%S)

Note that the container name may vary (e.g., invoiceninja-app-1). Check it using docker compose ps.

Automating Backups:

To automate the process, use Cron. Create a script backup_invoiceninja.sh:

#!/bin/bash

BACKUP_DIR="/root/invoiceninja_backup"
DATE=$(date +%F_%H-%M-%S)
DB_PASSWORD="YOUR_STRONG_DB_PASSWORD" # Use a secure method for storing the password

mkdir -p $BACKUP_DIR

# Backup database
docker compose exec db mysqldump -u ninja -p$DB_PASSWORD ninja > $BACKUP_DIR/ninja_db_$DATE.sql

# Backup .env file
cp /root/invoiceninja/.env $BACKUP_DIR/.env_$DATE

# Backup storage directory
docker cp invoiceninja-app-1:/var/www/app/storage $BACKUP_DIR/storage_$DATE

# Optional: Compress backups
tar -czvf $BACKUP_DIR/invoiceninja_backup_$DATE.tar.gz -C $BACKUP_DIR ninja_db_$DATE.sql .env_$DATE storage_$DATE

# Optional: Clean up old backups (e.g., keep last 7 days)
find $BACKUP_DIR -type f -name "*.sql" -mtime +7 -delete
find $BACKUP_DIR -type f -name "*.tar.gz" -mtime +7 -delete
find $BACKUP_DIR -type d -name "storage_*" -mtime +7 -exec rm -rf {} +

Make the script executable: chmod +x ~/backup_invoiceninja.sh.

Add it to Cron (crontab -e) for daily execution, for example, at 3 AM:

0 3 * * * /root/backup_invoiceninja.sh >> /var/log/invoiceninja_backup.log 2>&1

External Storage: It is crucial to transfer backups to external storage (S3, Google Drive, another VPS). For this, you can use tools like Restic on VPS.

Invoice Ninja Update Process

Updating Invoice Ninja deployed via Docker Compose consists of several steps:

1. Stop containers:

   cd ~/invoiceninja
   docker compose down

2. Update the Dockerfiles repository:

   git pull origin master

   This will update docker-compose.yml and other scripts to the latest versions.

3. Update Docker images:

   docker compose pull

   This command will download the latest versions of all Docker images used in your docker-compose.yml.

4. Start containers:

   docker compose up -d

5. Perform database migrations and clear cache:

   docker compose exec app php artisan migrate --force
   docker compose exec app php artisan optimize:clear

Always perform a full backup before updating!

Monitoring and Troubleshooting

To ensure stable operation of Invoice Ninja:

• Monitor VPS resources: Use utilities like htop, free -h, df -h to track CPU, RAM, and disk usage.
• Docker logs: Check container logs if problems arise:

  docker compose logs -f app
  docker compose logs -f db
  docker compose logs -f nginx

• Invoice Ninja logs: The application also keeps its own logs, which are located inside the app container in the /var/www/app/storage/logs/ directory. You can access them via docker compose exec app tail -f /var/www/app/storage/logs/laravel.log.

Remember that regular monitoring will help identify problems before they become critical.

Choosing the Optimal VPS Configuration for Real-World Load

The choice of VPS configuration for Invoice Ninja directly depends on the scale of your business, the number of users, and the intensity of application usage. Under-resourcing can lead to slow performance, failures, and productivity loss, while excessive resources lead to unnecessary expenses.

Assessing Your Business Needs

To determine the optimal configuration, answer the following questions:

1. Number of active users: How many people will be working with Invoice Ninja simultaneously? A single freelancer, a small team of 5, or a large department of 20+ employees? Each active user consumes CPU and RAM.
2. Number of invoices and clients: How many invoices do you plan to create per month? How many active clients do you have? A large number of database records requires more disk space and faster disk operations (NVMe).
3. Frequency of use: Will Invoice Ninja be used constantly throughout the day or only a few times a week? Peak loads require more resources.
4. Integrations: Do you plan to use the API for integration with other systems (CRM, ERP)? This can increase server load.
5. Additional services on VPS: Will other applications run on the same VPS (e.g., Firefly III for personal finance or other tools)? If so, overall resource requirements will increase.

Valebyte Recommendations

Based on experience deploying similar applications, Valebyte offers the following recommendations for choosing a VPS for Invoice Ninja on VPS:

1. For freelancers and small businesses (1-3 users, up to 500 invoices per month):
   • CPU: 1 vCPU (2.0+ GHz)
   • RAM: 2 GB
   • Disk: 20 GB NVMe SSD
   • Justification: This is sufficient for Invoice Ninja to run in an isolated Docker container. NVMe will ensure fast database performance even with modest CPU and RAM.
2. For growing small and medium businesses (4-10 users, up to 2000 invoices per month):
   • CPU: 2 vCPU (2.5+ GHz)
   • RAM: 4 GB
   • Disk: 40 GB NVMe SSD
   • Justification: Additional cores and RAM will allow for more simultaneous requests, improve report generation speed, and overall system responsiveness as the number of users increases.
3. For medium and large businesses (10+ users, 2000+ invoices per month, active integrations):
   • CPU: 4+ vCPU (3.0+ GHz)
   • RAM: 8+ GB
   • Disk: 80-120 GB NVMe SSD
   • Justification: Such a load requires significant resources to maintain high performance. A large amount of RAM will help cache data, and a powerful CPU will quickly process complex queries and generate reports. Increased NVMe disk space will provide not only speed but also enough room for data growth.

Always start with a configuration that matches your current needs and be prepared to scale. The advantage of Valebyte's VPS is the ability to easily upgrade your server's resources as your business grows. Choose plans with NVMe disks to ensure maximum data access speed for your Invoice Ninja on the server.

Conclusion

Invoice Ninja on VPS provides unparalleled control, security, and flexibility for managing your business finances, freeing you from cloud subscriptions. Using Invoice Ninja Docker significantly simplifies the Invoice Ninja installation process and subsequent maintenance, ensuring stability and portability. For most scenarios, a VPS with 2-4 GB RAM and an NVMe disk will be optimal, allowing for efficient handling of invoicing and client management operations.