Follow the instructions below to install InvoicePlane on your preferred platform.

1. Prerequisites
2. Installation Methods
   • Using the .zip File (Production)
   • Cloning the Repository (Development)
3. Development Workflow
   • Prepare: Initial Setup
   • StartMeUp: Start Development Environment
   • Workflow: Daily Development
4. Platform-Specific Instructions
   • Windows
   • macOS
   • Linux
5. Docker Installation
6. Post-Installation
7. Troubleshooting

• Web Server: Apache or Nginx
• PHP: Version 8.2 or higher (PHP 8.3 and 8.4 supported)
• Database: MariaDB
• For Development: Docker (recommended), Composer, Yarn/npm

This method is recommended for production deployments:

1. Download:

   • Get the latest version from the InvoicePlane website.

2. Extract:

   • Unzip the package and upload the contents to your web server.

3. Configuration:

   • Rename ipconfig.php.example to ipconfig.php.
   • Edit ipconfig.php and set your base URL and database credentials.

4. Setup:

   • Navigate to http://your-domain.com/index.php/setup in your browser and follow the on-screen instructions.

This method is recommended for development and contributing to InvoicePlane:

See Development Workflow section below for detailed steps.

This section outlines the three-phase workflow for developing InvoicePlane:

The Prepare phase sets up your development environment for the first time.

1. Clone the Repository:

   git clone https://github.com/InvoicePlane/InvoicePlane.git
   cd InvoicePlane

2. Install PHP Dependencies:

   composer install

   This installs all PHP packages defined in composer.json.

3. Install JavaScript Dependencies:

   yarn install

   This installs all frontend dependencies (Bootstrap, jQuery, etc.).

4. Build Frontend Assets:

   yarn build

   This compiles SASS to CSS and minifies JavaScript files using Grunt.

5. Configure Application (optional — only if you're not using docker-compose.yml's automatic config generation, see below):

   cp ipconfig.php.example ipconfig.php

   Edit ipconfig.php to set:

   • Database credentials (use the values from docker-compose.yml for local dev: DB_HOSTNAME=db, DB_USERNAME=ipdevdb, DB_PASSWORD=ipdevdb, DB_DATABASE=invoiceplane_db)
   • IP_URL=http://ivpl.local for local dev (see the hostname note below)
   • Environment settings

The StartMeUp phase launches your development environment. Two Docker setups are available — see resources/docker/README.md for the full comparison.

docker-compose.yml provides separated php/nginx/db/phpmyadmin services that bind-mount your working tree, so PHP/frontend edits are reflected immediately without a rebuild — this is the one to use for active development. (compose.yml is the other option: a single self-contained image, good for quickly spinning up InvoicePlane to test something, but not for iterating on code — see resources/docker/README.md.)

Add 127.0.0.1 ivpl.local to your /etc/hosts file first — the bundled nginx config expects that hostname, not localhost.

Start Docker:

docker compose -f docker-compose.yml up -d --build

ipconfig.php is generated automatically on first run if you skipped step 5 above.

View Logs:

docker compose -f docker-compose.yml logs -f

Stop Services:

docker compose -f docker-compose.yml down

Access Points:

• InvoicePlane: http://ivpl.local
• phpMyAdmin: http://localhost:8081
  • Username: ipdevdb
  • Password: ipdevdb

If you're not using Docker, ensure you have:

• PHP 8.2+ installed and configured
• MariaDB running locally
• Nginx or Apache configured to serve the project directory

The Workflow phase covers your day-to-day development activities.

1. Start Docker Environment (if using Docker):

   docker compose -f docker-compose.yml up -d

2. Make Code Changes:

   • Edit PHP files in application/ directory
   • Edit SASS files in assets/ directory
   • Edit JavaScript files in assets/ directory

3. Build Assets (if you changed frontend files):

   # One-time build
   yarn build
   
   # Or use watch mode for automatic rebuilds
   grunt watch

4. Run Linters (before committing):

   # Run all code quality checks
   composer check
   
   # Or run individually
   composer rector    # Automated refactoring
   composer phpcs     # PHP CodeSniffer
   composer pint      # Laravel Pint (PSR-12)

5. Test Your Changes:

   • Access http://localhost in your browser
   • Manually test the features you changed
   • Check for any console errors or warnings

6. Commit Your Changes:

   git add .
   git commit -m "Brief description of your changes"
   git push

• Using XAMPP or similar is not recommended.
• Recommended approach: Use Docker Desktop for Windows (see Docker Installation)
• Alternative: Use WSL2 (Windows Subsystem for Linux) with Docker
• Follow the standard Development Workflow steps

• Recommended: Use Docker Desktop for Mac (see Docker Installation)
• Alternative with Laravel Herd:
  • Install Laravel Herd.
  • Place InvoicePlane files in the Herd sites directory.
  • Follow the standard installation steps.
• Manual Setup: Install PHP 8.1+ via Homebrew and follow Linux instructions

• Nginx + MariaDB + PHP Setup (LEMP Stack):
  • Install required packages:

    # Ubuntu/Debian
    sudo apt-get update
    sudo apt-get install nginx mariadb-server php8.1-fpm php8.1-mysql php8.1-mbstring php8.1-xml php8.1-curl

  • Configure Nginx to serve InvoicePlane (see Docker nginx config for reference)
  • Follow the Development Workflow steps
• Docker: Recommended for consistent environment (see Docker Installation)

Docker provides the easiest and most consistent development environment for InvoicePlane. This repository ships two different compose files for two different purposes — see resources/docker/README.md for the full comparison. This section covers docker-compose.yml, the one for active development.

• Docker: Install Docker
• Docker Compose: Usually included with Docker Desktop

1. Clone Repository:

   git clone https://github.com/InvoicePlane/InvoicePlane.git
   cd InvoicePlane

2. Install Dependencies:

   composer install
   yarn install
   yarn build

3. Add the required hostname — the bundled nginx config expects ivpl.local, not localhost:

   echo "127.0.0.1 ivpl.local" | sudo tee -a /etc/hosts

4. Configure Application (optional): ipconfig.php is generated automatically on first start. To configure it yourself instead:

   cp ipconfig.php.example ipconfig.php

   Edit ipconfig.php with these settings for Docker:

   # Database settings — DB_HOSTNAME is the compose service name, not the container name
   DB_HOSTNAME=db
   DB_USERNAME=ipdevdb
   DB_PASSWORD=ipdevdb
   DB_DATABASE=invoiceplane_db
   DB_PORT=3306
   
   # URL settings — the config key is IP_URL, not URL_BASE
   IP_URL=http://ivpl.local

5. Start Services:

   docker compose -f docker-compose.yml up -d --build

6. Complete Setup:

   • Navigate to http://ivpl.local/index.php/setup
   • Follow the setup wizard
   • Use the database credentials from step 4

• PHP-FPM: PHP 8.2
• Nginx: Web server on port 80 (http://ivpl.local)
• MariaDB: Database server on port 3306
• phpMyAdmin: Database management on port 8081

# View logs
docker compose -f docker-compose.yml logs -f

# View logs for specific service
docker compose -f docker-compose.yml logs -f php

# Restart services
docker compose -f docker-compose.yml restart

# Stop services
docker compose -f docker-compose.yml down

# Rebuild containers (after Dockerfile changes)
docker compose -f docker-compose.yml up -d --build

# Access PHP container shell
docker exec -it invoiceplane-php bash

# Access database
docker exec -it invoiceplane-db mysql -u ipdevdb -pipdevdb invoiceplane_db

• Access http://your-domain.com/index.php/setup to complete the installation.
• It will guide you through the install wizard.
• Log in with the credentials you provided in the wizard
• In the settings you can set up InvoicePlane to your liking
• Add Invoice Groups, Product Families, Product Units, etcetera
• Start using InvoicePlane

If you encounter issues during installation or setup, follow these steps:

1. Visit the Community Forums - Engage with other users and developers for help.
2. Join our Discord Server - Get real-time assistance from the community.
3. Check the InvoicePlane Wiki - Look for documented solutions to common problems.