Invoicerr

Invoicerr is a simple, open-source invoicing application designed to help freelancers manage their quotes and invoices efficiently. It provides a clean interface for creating, sending, and tracking quotes and invoices — so you get paid faster, with less hassle.

📢 Maintainer availability

I no longer have enough personal time to work on Invoicerr full-time (studies + job).

The project is still open, and I can continue to review and manage community pull requests, but development speed from my side will be slower.

✨ Features

• Create and manage invoices
• Create and manage quotes (convertible to invoices)
• Manage clients and their contact details
• Track status of quotes and invoices (signed, paid, unread, etc.)
• Built-in quote signing system with secure tokens
• Generate and send quote/invoice emails directly from the app
• Generate clean PDF documents (quotes, invoices, payments, and more)
• Custom brand identity: logo, company name, VAT, and more
• Authentication via JWT or OIDC (stored in cookies)
• International-friendly: Default English UI, customizable currencies
• SQLite database for quick local setup
• Docker & docker-compose ready for self-hosting
• Built with modern stack: React, NestJS, Prisma, SQLite/PostgreSQL
• REST API backend, ready for future integrations (mobile & desktop apps)
• Plugin system for community-made features

🌍 Translation

Invoicerr uses weblate to easily manage the translations

🐳 Docker Installation (Recommended)

Supported Architectures

The images are built for the following architectures:

• linux/amd64 (x86_64)
• linux/arm64/v8 (ARMv8)

Why not linux/arm/v7?

The linux/arm/v7 architecture is not supported due to the use of prisma, which does not provide prebuilt binaries for this architecture. This means that the application will not run on 32-bit ARM devices.

The fastest way to run Invoicerr is using Docker Compose. A prebuilt image is available at ghcr.io/invoicerr-app/invoicerr.

🚀 Quick Start

1. Create a docker-compose.yml file with the following content, then adjust the environment variables to your setup:

   services:
     invoicerr:
       image: ghcr.io/invoicerr-app/invoicerr:latest
       ports:
         - "80:80"
       environment:
         - DATABASE_URL=postgresql://invoicerr:invoicerr@invoicerr_db:5432/invoicerr_db
         - APP_URL=https://invoicerr.example.com # Required for email templates, as it redirects to the app
         - CORS_ORIGINS=http://localhost:5173,https://invoicerr.example.com # Comma-separated list of allowed origins for CORS
   
         # Required for email features - choose ONE provider below
         # Option 1: SMTP (default, MAIL_PROVIDER can be omitted)
         - MAIL_PROVIDER=smtp
         - SMTP_HOST=smtp-relay.example.com
         - SMTP_USER="[email protected]"
         - SMTP_FROM="[email protected]" # Not required if SMTP_USER is the same as SMTP_FROM
         - SMTP_PASSWORD="your_smtp_password"
         - SMTP_PORT=587
         - SMTP_SECURE=false
   
         # Option 2: Brevo (set MAIL_PROVIDER=brevo and comment out the SMTP_* variables above)
         # - MAIL_PROVIDER=brevo
         # - BREVO_API_KEY="your_brevo_api_key"
   
         # Optional, but recommended for docker deployments
         - JWT_SECRET="your_jwt_secret"
       depends_on:
         - invoicerr_db
   
     invoicerr_db:
       image: postgres:15
       environment:
         POSTGRES_USER: invoicerr
         POSTGRES_PASSWORD: invoicerr
         POSTGRES_DB: invoicerr_db
       volumes:
         - db_data:/var/lib/postgresql/data
   
   volumes:
     db_data:
       driver: local
   

   The full reference file with OIDC options is available at docker-compose.yml.

2. Run the app:

   docker compose up -d
   

3. Open your browser at:

   http://localhost
   

🔧 Environment Variables

These environment variables are defined in docker-compose.yml under the invoicerr service:

• DATABASE_URL
  PostgreSQL connection string. Example:
  postgresql://invoicerr:invoicerr@invoicerr_db:5432/invoicerr_db

• APP_URL
  Full public URL of the frontend (e.g., https://invoicerr.example.com).
  This is required for email templates and links.

• MAIL_PROVIDER
  Which email transport to use: smtp (default) or brevo.

• SMTP_HOST, SMTP_USER, SMTP_PASSWORD
  Used when MAIL_PROVIDER=smtp (or unset). Credentials and server used for sending emails (quotes, invoices, etc.)

• SMTP_FROM
  Optional — address used as the sender for emails. If omitted, defaults to SMTP_USER.

• BREVO_API_KEY
  Used when MAIL_PROVIDER=brevo. API key for sending emails via Brevo instead of SMTP. The sender address falls back to MAIL_FROM, then SMTP_FROM/SMTP_USER.

• JWT_SECRET
  Optional but recommended for JWT authentication. Can be any random string.
  If not set, a default secret will be used. But it can have issues with docker deployments.

Make sure port 80 is available on your host machine, or change the mapping.

💻 Manual Installation (Local Development)

Prerequisites

• Node.js v20+
• SQLite (or configure another DATABASE_URL)
• PNPM or NPM

Steps

1. Clone the project:

   git clone https://github.com/invoicerr-app/invoicerr.git
   cd invoicerr
   

2. Backend setup:

   cd backend
   npm install
   npx prisma generate
   npm run start
   

3. Frontend setup (in a new terminal):

   cd frontend
   npm install
   npm run start
   

4. Open in your browser:

   • Frontend: http://localhost:5173
   • API: http://localhost:3000

🧪 Lancer les tests end-to-end (Cypress)

Pour lancer les tests e2e localement ou en CI :

1. Démarrer le backend et le frontend avec les variables de test :

   cd backend && npm run start:test &
   cd frontend && npm run start:test &
   

   (Assurez-vous d'avoir un .env.test dans chaque dossier)

2. Dans un autre terminal, lancer Cypress :

   cd e2e
   npm install
   npm run e2e:open # ou npm run e2e:run
   

En CI, le workflow GitHub Actions fait ces étapes automatiquement.

📸 Screenshots

🧰 Technologies

⚖️ License

This project is dual-licensed:

• Open Source: AGPL-3.0
• Commercial: COMMERCIAL-LICENSE

Contact me for commercial use.