InvoicePlane Docker

Complete Docker-based development environment for InvoicePlane

A containerized development stack featuring PHP, Nginx, MariaDB, Redis, and more. Built on Laradock and optimized for InvoicePlane development with support for PHP 7.4 through 8.4.

🚀 Quick Start

Clone the repository

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

Create your environment file
```
cp .env.example .env.docker
```

Configure your setup (optional)

# Edit .env.docker to customize:
# - PHP version (8.1, 8.2, 8.3, 8.4)
# - Database settings
# - Port mappings
nano .env.docker

Build and start containers
```
./builddmeup.sh
```

Verify installation

docker compose --env-file .env.docker ps

Your development environment is now ready! 🎉

📖 Setting Up Your First Project (InvoicePlane)

This guide will walk you through setting up InvoicePlane v1 step by step.

Step 1: Prepare Your Project Directory

First, make sure your projects directory exists. By default, this is ~/projects:

# Create the projects directory if it doesn't exist
mkdir -p ~/projects

# Clone InvoicePlane v1 into your projects directory
cd ~/projects
git clone https://github.com/InvoicePlane/InvoicePlane.git ivplv1
cd ivplv1

💡 Note: The folder name ivplv1 will be used in the next steps. You can choose any name you like, but remember to use it consistently.

Step 2: Configure Your Environment

Open your .env.docker file in the InvoicePlane-Docker directory:

cd /path/to/InvoicePlane-Docker
nano .env.docker

Find the line that says APP_CODE_PATH_HOST and make sure it points to your projects directory:

# This should match where you created your projects folder
APP_CODE_PATH_HOST=~/projects/

💡 Tip: If you used a different path for your projects, update this line accordingly. For example, if your projects are in /home/username/myprojects/, use that path instead.

Step 3: Create Your Nginx Configuration

Now we'll tell Nginx how to serve your InvoicePlane project:

Copy the example configuration:

cd /path/to/InvoicePlane-Docker
cp sites/copyme.conf.example sites/ivplv1.conf

Open the configuration file:
```
nano sites/ivplv1.conf
```
Replace all instances of copyme with ivplv1 and remove /public from the root path (there are 4 places to change):
- Line 5: server_name copyme.local; → server_name ivplv1.test;
- Line 6: root /var/www/projects/copyme/public; → root /var/www/projects/ivplv1; (also remove /public)
- Line 34: error_log /var/log/nginx/copyme_error.log; → error_log /var/log/nginx/ivplv1_error.log;
- Line 35: access_log /var/log/nginx/copyme_access.log; → access_log /var/log/nginx/ivplv1_access.log;
💡 Why remove /public? InvoicePlane v1 doesn't use a public directory like some frameworks. The main files are in the root of the project.

💡 Why use .test instead of .local? The .test domain is reserved for testing and won't conflict with real domains. You can use .local if you prefer, just be consistent.
Save and close the file (in nano: press Ctrl+X, then Y, then Enter)

Step 4: Add Domain to Your Hosts File

Tell your computer that ivplv1.test should point to your local Docker environment:

On Linux/Mac:

sudo nano /etc/hosts

On Windows: Open Notepad as Administrator, then open:

C:\Windows\System32\drivers\etc\hosts

Add this line:

127.0.0.1    ivplv1.test

Save and close the file.

Step 5: Start Docker

Now start your Docker environment:

cd /path/to/InvoicePlane-Docker
./starmeup.sh

💡 What's happening? Docker is:

Building the containers (first time takes 5-10 minutes)

Starting PHP, Nginx, MariaDB, and other services

Reading your ivplv1.conf file to know how to serve your project

Making your project available at http://ivplv1.test

You'll see lots of output in your terminal. This is normal! Look for messages saying containers are starting.

Step 6: Verify Everything is Running

In a new terminal window (keep Docker running in the first one):

cd /path/to/InvoicePlane-Docker
docker compose --env-file .env.docker ps

You should see all services with "Up" status:

NAME                STATUS
workspace           Up
php-fpm             Up
nginx               Up
mariadb             Up
redis               Up

Step 7: Access Your Project

Open your web browser and go to:

http://ivplv1.test

You should see your InvoicePlane installation! 🎉

Step 8: Stop Docker When Done

When you're finished working, stop Docker:

Option 1: Stop from terminal (if Docker is running in foreground)

Press Ctrl+C in the terminal where Docker is running

Option 2: Stop and remove everything

./down.sh

This stops all containers and removes them (but keeps your code safe).

Step 9: Restart Docker Later

When you want to work again, just run:

./starmeup.sh

This is much faster than the first build! ⚡

🆘 Troubleshooting

Problem: Can't access http://ivplv1.test

Solution: Make sure you added 127.0.0.1 ivplv1.test to your hosts file
Solution: Make sure Docker is running (docker compose ps)
Solution: Try http://localhost instead

Problem: "Port already in use"

Solution: Another service is using port 80. Either stop it, or change the port in .env.docker:
```
NGINX_HOST_HTTP_PORT=8080
```
Then restart Docker for the change to take effect:
```
./down.sh
./starmeup.sh
```
Access your site at http://ivplv1.test:8080

Problem: "Permission denied" errors

Solution: Check your PUID and PGID in .env.docker match your user:

id -u  # This is your PUID
id -g  # This is your PGID

Problem: Changes to nginx config not working

Solution: Restart Docker to reload the configuration:
```
./down.sh
./starmeup.sh
```

📦 What's Included

Services

PHP-FPM - PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 (configurable)
Workspace - CLI tools, Composer, Node.js, Git
Nginx - Web server with optimized configuration
MariaDB - Database server
Redis - Caching and session storage
Beanstalkd - Queue management
phpMyAdmin - Database management interface
Redis Web UI - Redis monitoring interface

Features

✅ Multiple PHP versions support
✅ Xdebug with trigger mode
✅ Pre-configured for Laravel and CodeIgniter
✅ Helper scripts for common tasks
✅ GitHub Actions CI/CD
✅ Optimized Docker layer caching

🛠️ Helper Scripts

All scripts include error handling and validation to ensure a smooth experience.

🔨 Building

Build and start containers:

Script	Mode	Description
`./buildmeup.sh`	Foreground	Build and start with live logs
`./builddmeup.sh`	Background	Build and start in detached mode

▶️ Starting/Stopping

Control existing containers:

Script	Mode	Description
`./starmeup.sh`	Foreground	Start with live logs
`./startmeup.sh`	Background	Start in detached mode
`./down.sh`	-	Stop and remove all containers and volumes

🖥️ Accessing Containers

Enter a running container:

Script	Container	User	Use Case
`./workmeup.sh`	workspace	ivpldock	Development tasks, Composer, NPM
`./rootmeup.sh`	workspace	root	System administration
`./phpmeup.sh`	php-fpm	root	PHP-FPM debugging
`./worker.sh`	php-worker	root	Queue worker debugging

🚀 Running Commands

Execute commands inside containers from your host using docker-exec.sh:

Syntax:

./docker-exec.sh <container> <project> <command>

Common Examples:

# 📦 Composer Operations
./docker-exec.sh workspace myproject "composer install"
./docker-exec.sh workspace myproject "composer update"
./docker-exec.sh workspace myproject "composer require vendor/package"

# 🎨 Laravel/Artisan Commands
./docker-exec.sh php-fpm invoiceplane "php artisan migrate"
./docker-exec.sh php-fpm invoiceplane "php artisan migrate --force"
./docker-exec.sh workspace invoiceplane "php artisan test"
./docker-exec.sh workspace invoiceplane "php artisan db:seed"

# 📊 Database Operations
./docker-exec.sh workspace invoiceplane "php artisan migrate:fresh --seed"
./docker-exec.sh workspace invoiceplane "php artisan migrate:rollback"

# 🔧 NPM Operations
./docker-exec.sh workspace myapp "npm install"
./docker-exec.sh workspace myapp "npm run build"
./docker-exec.sh workspace myapp "npm run dev"
./docker-exec.sh workspace myapp "npm run watch"

# 🧪 Testing
./docker-exec.sh workspace myproject "php artisan test"
./docker-exec.sh workspace myproject "vendor/bin/phpunit"
./docker-exec.sh workspace myproject "php artisan test --filter UserTest"

🔄 Continuous Integration

This repository includes automated GitHub Actions workflows that test Docker builds.

Tested PHP Versions:

✅ PHP 8.2
✅ PHP 8.3
✅ PHP 8.4

CI Pipeline Verifies:

✅ All containers build successfully
✅ PHP extensions are properly installed (zip, etc.)
✅ Services start correctly
✅ Basic functionality works

Workflow Triggers:

Push to main branches
Pull requests
Manual dispatch

📁 Directory Structure

Directory	Purpose
`.docker/`	All Dockerfile definitions for services
`sites/`	Nginx site configurations
`.github/workflows/`	GitHub Actions CI/CD pipelines
`*.sh`	Helper scripts for common operations

⚙️ Configuration

Basic Setup

Edit .env.docker to customize your environment:

Core Settings:

# PHP Version
PHP_VERSION=8.1  # Options: 7.4, 8.0, 8.1, 8.2, 8.3, 8.4

# Project Path
APP_CODE_PATH_HOST=../projects/

# Database
MARIADB_VERSION=latest
MARIADB_DATABASE=default
MARIADB_USER=default
MARIADB_PASSWORD=secret

# Ports
NGINX_HOST_HTTP_PORT=80
MARIADB_PORT=3306
REDIS_PORT=6379

🐳 Docker Build Caching

Docker automatically caches build layers to speed up subsequent builds.

How It Works:

Docker Compose checks if dependent services need building
Uses cached layers if Dockerfile and context haven't changed
Only rebuilds layers that have changed

Benefits:

⚡ Faster rebuild times
💾 Efficient resource usage
🔄 Smart dependency management

Tips for Better Caching:

# Docker keeps built images in cache even after stopping containers
docker compose --env-file .env.docker ps

# Force complete rebuild only when necessary
docker compose --env-file .env.docker build --no-cache php-fpm

# Build specific service
docker compose --env-file .env.docker build workspace

# Parallel builds for multiple services
docker compose --env-file .env.docker build --parallel

Example Workflow:

# First build (takes longer)
docker compose --env-file .env.docker build php-fpm
# ⏱️ 5 minutes

# Build dependent service (uses cache)
docker compose --env-file .env.docker build beanstalkd
# ⏱️ 30 seconds (php-fpm cached!)

🐛 Xdebug Configuration

Xdebug is configured in trigger mode to prevent connection warnings during builds while maintaining full debugging capability.

Activation Methods

1️⃣ Browser Debugging (Web Requests)

Using Browser Extension:

Install Xdebug Helper for Chrome
Or Xdebug Helper for Firefox
Click the extension icon to enable debugging

Using Query Parameter:

http://your-app.local?XDEBUG_TRIGGER=1

Using Cookie:

document.cookie = "XDEBUG_TRIGGER=1; path=/";

2️⃣ CLI Debugging (Command Line)

Inside Container:

# Enter workspace
./workmeup.sh

# Run with Xdebug
XDEBUG_TRIGGER=1 php artisan test
XDEBUG_TRIGGER=1 php script.php
XDEBUG_TRIGGER=1 vendor/bin/phpunit

From Host:

# Single command with Xdebug
./docker-exec.sh workspace myproject "XDEBUG_TRIGGER=1 php artisan test"

# Composer with Xdebug
./docker-exec.sh workspace myproject "XDEBUG_TRIGGER=1 composer install"

3️⃣ Persistent Debugging (Environment Variable)

# Inside container
export XDEBUG_TRIGGER=1
php artisan test  # Now always uses Xdebug

IDE Configuration

PHPStorm Setup:

Go to Settings → PHP → Debug
Set port to 9003
Go to Settings → PHP → Servers
Add server named ivpldock
Set path mappings:
- Local: /path/to/your/project
- Remote: /var/www/projects/yourproject
Click "Start Listening for PHP Debug Connections" (phone icon)

VS Code Setup:

Install PHP Debug extension

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/projects/yourproject": "${workspaceFolder}"
      }
    }
  ]
}

Press F5 to start debugging

Configuration Files

# Xdebug settings locations
.docker/php-fpm/xdebug.ini       # PHP-FPM container
.docker/workspace/xdebug.ini     # Workspace container

Default Port: 9003 (configurable in .env.docker)

Troubleshooting Xdebug

# Verify Xdebug is installed
docker compose --env-file .env.docker exec workspace php -v
# Should show: "with Xdebug v3.x.x"

# Check Xdebug configuration
docker compose --env-file .env.docker exec workspace php -i | grep xdebug

# Test Xdebug trigger
docker compose --env-file .env.docker exec workspace bash -c "XDEBUG_TRIGGER=1 php -v"

# View Xdebug logs
docker compose --env-file .env.docker exec workspace cat /tmp/xdebug.log

🔧 Troubleshooting

Common Issues

❌ Container Won't Start

Check environment file exists:

ls -la .env.docker

View detailed logs:

docker compose --env-file .env.docker logs -f <container_name>
# Examples:
docker compose --env-file .env.docker logs -f workspace
docker compose --env-file .env.docker logs -f php-fpm

Check container status:

docker compose --env-file .env.docker ps
docker compose --env-file .env.docker ps -a  # Include stopped containers

🔌 Port Already in Use

Check what's using the port:

# Linux/Mac
sudo lsof -i :80
sudo lsof -i :3306

# Or use netstat
netstat -tlnp | grep :80

Solution: Change port in .env.docker:

NGINX_HOST_HTTP_PORT=8080  # Instead of 80
MARIADB_PORT=3307          # Instead of 3306

🔐 Permission Denied Errors

Check and fix PUID/PGID:

# Get your user and group ID
id -u  # Your user ID
id -g  # Your group ID

# Update .env.docker
WORKSPACE_PUID=1000  # Your user ID
WORKSPACE_PGID=1000  # Your group ID
PHP_FPM_PUID=1000
PHP_FPM_PGID=1000

# Rebuild containers
docker compose --env-file .env.docker build workspace php-fpm
docker compose --env-file .env.docker up -d

🐌 Slow Performance (macOS/Windows)

Use cached volume flag:

# In .env.docker
APP_CODE_CONTAINER_FLAG=:cached

Consider Docker Sync for large projects:

Significant performance improvement
See docker-sync documentation

🗄️ Database Connection Failed

Verify database is running:

docker compose --env-file .env.docker ps mariadb

Check database credentials:

# In .env.docker
MARIADB_DATABASE=default
MARIADB_USER=default
MARIADB_PASSWORD=secret

# In your app's .env
DB_HOST=mariadb  # Not localhost!
DB_PORT=3306
DB_DATABASE=default
DB_USERNAME=default
DB_PASSWORD=secret

Test connection:

docker compose --env-file .env.docker exec workspace mysql -h mariadb -u default -psecret

🧹 Clean Up Issues

Remove all containers and volumes:

# WARNING: This deletes all data!
docker compose --env-file .env.docker down -v

Full Docker cleanup:

# Remove unused containers, networks, images
docker system prune -a

# Remove all volumes (BE CAREFUL!)
docker volume prune

📦 Build Failures

Clear build cache and rebuild:

docker compose --env-file .env.docker build --no-cache --pull <service>

Check Docker disk space:

docker system df

Getting Help

Collect diagnostic information:

# Docker version
docker --version
docker compose version

# Container status
docker compose --env-file .env.docker ps

# Recent logs
docker compose --env-file .env.docker logs --tail=50 workspace php-fpm

# System info
docker info

When reporting issues, include:

Steps to reproduce
Error messages (full output)
Docker and compose versions
Operating system
Relevant configuration from .env.docker

📚 Additional Resources

Documentation

Project Guidelines: .junie/guidelines.md - Comprehensive development guidelines
Copilot Instructions: .github/copilot-instructions.md - AI coding assistant guidelines
Docker Compatibility: DOCKER_COMPATIBILITY.md - Version compatibility matrix

External Links

Laradock: Original upstream project - github.com/laradock/laradock
InvoicePlane: Main application - github.com/InvoicePlane/InvoicePlane
Docker Documentation: docs.docker.com
Docker Compose Documentation: docs.docker.com/compose

Community & Support

Issues: GitHub Issues - Report bugs and request features
Discussions: GitHub Discussions - Ask questions and share ideas
Pull Requests: Contributing Guidelines - Submit code improvements

🤝 Contributing

We welcome contributions! Please see our development guidelines for:

Code standards
Testing requirements
Pull request process
Docker best practices

Quick Contribution Guide

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Test thoroughly across PHP versions
Commit your changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📝 License

This project inherits its license from Laradock. See LICENSE for details.

🙏 Origins & Credits

This project was originally called Laradock and has been forked to target specifically the images needed to run InvoicePlane.

Laradock: github.com/laradock/laradock
License: Original license file included in this repository

Version: 2.0
Last Updated: 2025-01-05
Maintained by: InvoicePlane Team

Note: Helper scripts use docker-compose for backward compatibility, but docker compose (v2) is recommended for manual commands.

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
.docker		.docker
.github		.github
.junie		.junie
resources/databases/upload		resources/databases/upload
sites		sites
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
DOCKER_COMPATIBILITY.md		DOCKER_COMPATIBILITY.md
LICENSE		LICENSE
README.md		README.md
builddmeup.sh		builddmeup.sh
buildmeup.sh		buildmeup.sh
docker-compose.yml		docker-compose.yml
docker-exec.sh		docker-exec.sh
down.sh		down.sh
phpmeup.sh		phpmeup.sh
rootmeup.sh		rootmeup.sh
starmeup.sh		starmeup.sh
startmeup.sh		startmeup.sh
worker.sh		worker.sh
workmeup.sh		workmeup.sh

License

InvoicePlane/InvoicePlane-Docker

Folders and files

Latest commit

History

Repository files navigation

InvoicePlane Docker

🚀 Quick Start

📖 Setting Up Your First Project (InvoicePlane)

Step 1: Prepare Your Project Directory

Step 2: Configure Your Environment

Step 3: Create Your Nginx Configuration

Step 4: Add Domain to Your Hosts File

Step 5: Start Docker

Step 6: Verify Everything is Running

Step 7: Access Your Project

Step 8: Stop Docker When Done

Step 9: Restart Docker Later

🆘 Troubleshooting

📦 What's Included

Services

Features

🛠️ Helper Scripts

🔨 Building

▶️ Starting/Stopping

🖥️ Accessing Containers

🚀 Running Commands

🔄 Continuous Integration

📁 Directory Structure

⚙️ Configuration

Basic Setup

🐳 Docker Build Caching

🐛 Xdebug Configuration

Activation Methods

IDE Configuration

Configuration Files

Troubleshooting Xdebug

🔧 Troubleshooting

Common Issues

❌ Container Won't Start

🔌 Port Already in Use

🔐 Permission Denied Errors

🐌 Slow Performance (macOS/Windows)

🗄️ Database Connection Failed

🧹 Clean Up Issues

📦 Build Failures

Getting Help

📚 Additional Resources

Documentation

External Links

Community & Support

🤝 Contributing

Quick Contribution Guide

📝 License

🙏 Origins & Credits

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages