diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 896753c9..45e9a128 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Thank you for your interest in contributing to InvoiceShelf! We welcome contribu ## How to Contribute -1. **Fork the repository** and create a new branch from `master` +1. **Fork the repository** and create a new branch from `3.x` 2. **Make your changes** — follow the existing code style and conventions 3. **Write tests** if applicable 4. **Run the test suite** to ensure nothing is broken diff --git a/Makefile b/Makefile index fa8ad1dd..9b90142c 100644 --- a/Makefile +++ b/Makefile @@ -37,7 +37,7 @@ dist-gen: clean composer npm-build @cp -r composer.json InvoiceShelf @cp -r composer.lock InvoiceShelf @cp -r LICENSE InvoiceShelf - @cp -r readme.md InvoiceShelf + @cp -r README.md InvoiceShelf @cp -r SECURITY.md InvoiceShelf @touch InvoiceShelf/storage/logs/laravel.log diff --git a/README.md b/README.md new file mode 100644 index 00000000..caa98a65 --- /dev/null +++ b/README.md @@ -0,0 +1,99 @@ +

+ InvoiceShelf +

+ +

+ Open-source invoicing for people who want to own their business data. +

+ +

+ Download InvoiceShelf + · + Documentation + · + Community +

+ +> [!WARNING] +> The default `3.x` branch is an alpha preview. It is ready for testing and +> feedback, but not for production data. Use the supported +> [`2.x` release](https://github.com/InvoiceShelf/InvoiceShelf/tree/2.x) for a +> production installation. + +![InvoiceShelf dashboard](resources/static/img/invoiceshelf-dashboard.png) + +## Run your invoicing from one place + +InvoiceShelf is a self-hosted web application for creating invoices, tracking +payments and expenses, and keeping customer accounts organised. It is built for +freelancers and small businesses that want a focused workflow without giving up +control of their data. + +- Create invoices and estimates, then export polished PDFs. +- Record payments and see what each customer still owes. +- Track expenses, taxes, and business reports. +- Schedule recurring invoices for repeat work. +- Give customers a portal for invoices, estimates, and payment history. +- Manage multiple companies and invite team members with scoped roles. + +Optional official modules can add specialised features without making the core +application heavier. + +## Install InvoiceShelf + +### Production: InvoiceShelf 2.x + +Install the current stable release from the +[self-hosted download page](https://invoiceshelf.com/download), or run the +official Docker image with the `:latest` tag. Follow the +[installation guide](https://docs.invoiceshelf.com/installation.html) for the +complete setup and upgrade instructions. + +### Preview: InvoiceShelf 3.x + +Use the preview only with disposable or backed-up data: + +- Download the latest 3.x preview from the + [self-hosted download page](https://invoiceshelf.com/download). +- For Docker, use `invoiceshelf/invoiceshelf:next` instead of `:latest` in the + [official Compose setup](https://github.com/InvoiceShelf/docker). + +A minimal SQLite Docker setup looks like this: + +```bash +git clone https://github.com/InvoiceShelf/docker.git invoiceshelf +cd invoiceshelf +cp docker-compose.sqlite.yml docker-compose.yml +# For the 3.x preview, change the image tag in docker-compose.yml to :next. +docker compose up -d +``` + +Open and finish the setup wizard. Read the +[Docker guide](https://docs.invoiceshelf.com/install/docker.html) before using +InvoiceShelf on a public server. + +For a traditional web-server installation, see the +[manual installation guide](https://docs.invoiceshelf.com/install/manual.html). +InvoiceShelf 3.x requires PHP 8.4 and supports MySQL/MariaDB, PostgreSQL, and +SQLite. Docker includes the required application runtime. + +## Learn and get help + +- [User and installation documentation](https://docs.invoiceshelf.com/) +- [API reference](https://api-docs.invoiceshelf.com/) +- [Discord community](https://discord.gg/eHXf4zWhsR) +- [Bug reports and feature requests](https://github.com/InvoiceShelf/InvoiceShelf/issues) + +## Contribute + +Code contributions are welcome. Start with the +[contribution guide](CONTRIBUTING.md) and use the development environment in +[`docker/development`](docker/development/README.md). + +You can also help translate InvoiceShelf on +[Crowdin](https://crowdin.com/project/invoiceshelf). + +## License + +InvoiceShelf is released under the +[GNU Affero General Public License v3.0](LICENSE). diff --git a/config/installer.php b/config/installer.php index cf584139..14ba7fe7 100755 --- a/config/installer.php +++ b/config/installer.php @@ -13,7 +13,7 @@ return [ | */ 'core' => [ - 'minPhpVersion' => '8.2.0', + 'minPhpVersion' => '8.4.0', ], 'final' => [ 'key' => true, diff --git a/docker/development/README.md b/docker/development/README.md index 9c9cde64..e634d90a 100644 --- a/docker/development/README.md +++ b/docker/development/README.md @@ -1,166 +1,86 @@ -# InvoiceShelf Development Environment +# InvoiceShelf development environment -This is dockerized development environment that allows developers to easily get started to develop InvoiceShelf. +The repository includes a Docker Compose development stack for Linux and macOS. +It provides PHP 8.4, nginx, your chosen database, Adminer, and Mailpit. An +optional Gotenberg service is available for PDF development. -This development environment is **NOT MEANT TO BE USED IN PRODUCTION** and is preconfigured with all the needed tools that InvoiceShelf requires for development purposes. It works on Windows, Linux and MacOS. +> This stack is for development only. For a production installation, use the +> [official Docker repository](https://github.com/InvoiceShelf/docker). -For production grade docker image, please refer to [InvoiceShelf/docker](https://github.com/InvoiceShelf/docker) and [InvoiceShelf on DockerHub](https://hub.docker.com/r/invoiceshelf/invoiceshelf). +## Start the stack -## How to set up +You need Git, Docker, and Docker Compose. Clone your fork, prepare the local +environment file, and run the interactive helper from the repository root: -### 1. Hosts configuration - -We use `invoiceshelf.test` domain for local development within this environment and you need to adhere to it. - -For that purpose you need to edit your OS hosts file or DNS server and add the following line to make the local domain name available on your system. - -``` -127.0.0.1 invoiceshelf.test +```bash +git clone git@github.com:YOUR-USERNAME/InvoiceShelf.git +cd InvoiceShelf +cp .env.example .env +./devenv ``` -#### 1.1. Windows +The helper: -The hosts file on Windows is located at `C:\Windows\system32\drivers\etc\hosts`. +1. checks Docker and Docker Compose; +2. adds `invoiceshelf.test` to `/etc/hosts` when needed; +3. asks you to choose MySQL/MariaDB, PostgreSQL, or SQLite; +4. optionally enables the Gotenberg PDF service; and +5. saves that choice in `.devenvconfig` for later commands. -You need to launch Notepad as administrator, open the file through **File > Open**, add the line from above and save the file. +On the first run, install the PHP dependencies inside the running container: -#### 1.2. Linux/MacOS - -The hosts file on Linux and Mac is located at `/etc/hosts`. - -You need to open the file using your favorite editor as sudo/root, add the line from above and save the file. - -### 2. FileSystem configuration (Linux) - -If you are using **Linux**, you need to make sure that **USRID** and **GRPID** environment variables are set and matching your current session user ids. Those two variables are required to set up the filesystem permissions correctly on Linux. - -You can run it one time, every time before starting as follows: - -``` -export USRID=$(id -u) && export GRPID=$(id -g) +```bash +./devenv run composer install +./devenv run php artisan key:generate ``` -or you can append this to your .zshrc/.bashrc by running this command in your terminal: +The frontend runs on the host with Node.js 24 and the pnpm version pinned in +`package.json`: -``` -grep -qxF 'export USRID=$(id -u) GRPID=$(id -g)' ~/.${SHELL##*/}rc || echo 'export USRID=$(id -u) GRPID=$(id -g)' >> ~/.${SHELL##*/}rc -``` -this will append the `export` line to your rc file and run it on each terminal session. - -### 3. Clone the project - -Clone the InvoiceShelf project directly from InvoiceShelf git or your forked repository: - -```bash -git clone git@github.com:InvoiceShelf/InvoiceShelf.git +```bash +corepack enable +pnpm install --frozen-lockfile +pnpm dev ``` -## Development Workflow +Keep `pnpm dev` running while you work. Open and +complete the installation wizard. For +MySQL or PostgreSQL, use `db` as the database host and `invoiceshelf` as the +database name, username, and password. For SQLite, keep the wizard's default +`storage/app/database.sqlite` path. -We bundled separate docker-compose.yml file for each database: MySQL, PostgresSQL and SQLite, you can use any of those to spin up your development environment. +## Everyday commands -| Database | Compose File | -|---------|---------------------------| -| SQLite3 | docker-compose.sqlite.yml | -| MariaDB | docker-compose.mysql.yml | -| PostgresSQL | dpcler-compose.pgsql.yml | - -### 1. Spinning Up - -To **spin up** the environment, run docker compose as follows: - -**Important**: If you are on **Linux** and didn't add the `export` line to your .zshrc/.bashrc file, you need to repeat `step 2` before spinning up, otherwise you will face permissions issues. - -``` -docker compose -f docker/development/docker-compose.mysql.yml up --build +```bash +./devenv start # Start the saved stack +./devenv stop # Stop it +./devenv logs # Follow service logs +./devenv shell # Open a shell in the PHP container +./devenv run php artisan about +./devenv test # Run Pest +./devenv format # Run Pint +./devenv rebuild # Rebuild images from scratch ``` -### 2. Spinning Down +`./devenv destroy` removes the stack, its images, and its database volumes. The +command asks for confirmation before deleting anything. -To **spin down** the environment, run docker compose as follows: +## Services -``` -docker compose -f docker/development/docker-compose.mysql.yml down -``` +| Service | Address | +| --- | --- | +| InvoiceShelf | | +| Adminer | | +| Mailpit | | -### 3. Working with binaries +Mailpit receives development email over SMTP at `mail:1025`. Adminer connects +to MySQL or PostgreSQL at host `db`; its database, username, and password are +all `invoiceshelf`. -To correctly run `composer`, `npm`, `artisan`, `pint`, `pest` or other binaries within this project, you must ssh into the container as follows: +## Advanced Compose usage -``` -docker exec -it invoiceshelf-dev-php /bin/sh -``` - -In the `/var/www/html` directory you can find the application root and run the commands from there. - -## What is included - -### 1. Web Server - -This dockerized environment uses PHP-FPM and NGINX together to serve the website `invoiceshelf.test` - -Both NGINX and PHP-FPM are configured with optimal settings for development. Please don't use this in production. - -**URL**: http://invoiceshelf.test/ - -### 2. Databases - -This dockerized environment comes with support for all three databases that InvoiceShelf suppots: MySQL, PostgreSQL and SQLite. - -The setup parameters/credentials for each of the supported databases are as follows. - -| | MySQL | PostgreSQL | SQLite | -|---|---|---|-------------------------------------------| -| **DB_USER** | invoiceshelf | invoiceshelf | Not applicable | -| **DB_PASS** | invoiceshelf | invoiceshelf | Not applicable | -| **DB_NAME** | invoiceshelf | invoiceshelf | /var/www/html/storage/app/database.sqlite | -| **DB_HOST** | 172.18.0.1 | 172.18.0.1 | Not applicable | -| **DB_PORT** | 3306 | 5432 | Not applicable | - -**Note:** The only required field for SQLite is **DB_NAME**. - -### 3. Adminer - -Adminer is UI tool for viewing the database contents and executing queries. - -It supports MySQL, PostgreSQL, SQLite. - -**URL**: http://invoiceshelf.test:8080 - -#### MySQL/PostgresSQL - -To log into the MySQL or PostgresSQL, use the database information specified in the above section (2. Databases) - -#### SQLite - -To log into the SQLite, use the following credentials: - -| KEY | VALUE | -|--------------|------------------------------| -| **USERNAME** | admin | -| **PASSWORD** | admin | -| **DATABASE** | /storage/app/database.sqlite | - - -### 4. Mailpit (fake mail) - -To utilize Mailpit, use the following credentials: - -| KEY | VALUE | -|---------------------|-------------| -| **MAIL DRIVER** | smtp | -| **MAIL HOST** | mail | -| **MAIL PORT** | 1025 | -| **MAIL ENCRYPTION** | none | -| **MAIL USER** | leave empty | -| **MAIL PASS** | leave empty | -| **FROM MAIL ADDR** | your choice | -| **FROM MAIL NAME** | your choice | - - -**URL**: http://invoiceshelf.test:8025 - ---- - -If you have any questions, feel free to open issue. +The six Compose definitions in this directory cover all three databases, with +and without Gotenberg. The `./devenv` helper is the supported entry point, but +you can inspect or run those files directly when debugging the stack. +Run `./devenv --help` for the complete command list. diff --git a/readme.md b/readme.md deleted file mode 100644 index c221a281..00000000 --- a/readme.md +++ /dev/null @@ -1,88 +0,0 @@ - - -## Introduction - -InvoiceShelf is an open-source web app that helps you track expenses, record payments, and create professional invoices and estimates. It is self-hosted, multi-tenant, and built for individuals and small businesses that want to keep their books on their own infrastructure. - -The web application is built with Laravel and Vue 3. - -To get started using Docker Compose, follow the [Installation guide](https://docs.invoiceshelf.com/installation.html). - -# Table of Contents - -1. [Documentation](#documentation) -2. [System Requirements](#system-requirements) -3. [Download](#download) -4. [Discord](#discord) -5. [Roadmap](#roadmap) -6. [Translate](#translate) -7. [License](#license) - -## Documentation - -- [Installation Steps](https://docs.invoiceshelf.com/installation.html) -- [User Guide](https://docs.invoiceshelf.com/) -- [Developer Guide](https://docs.invoiceshelf.com/developer-guide.html) -- [API Documentation](https://api-docs.invoiceshelf.com) - -## System Requirements - -- **PHP 8.4+** is required (since v2.2.0, when InvoiceShelf moved to Laravel 13). -- Database: MySQL, MariaDB, PostgreSQL, or SQLite. -- Before updating from inside the app, verify your server meets the target version's PHP and extension requirements. -- The in-app updater verifies requirements and refuses to proceed if they are not met. - -## Download - -- [Download Link](https://invoiceshelf.com) - -## Discord - -Join the discussion on the InvoiceShelf Discord: [Invite Link](https://discord.gg/eHXf4zWhsR) - -## Roadmap - -Rough roadmap of things to come, not in any specific order: - -- [x] Automatic Update -- [x] Email Configuration -- [x] Installation Wizard -- [x] Address Customisation & Default Notes -- [x] Edit Email before Sending Invoice -- [x] Available as a Docker image -- [x] Performance Improvements -- [x] Customer View Page -- [x] Custom Fields on Invoices & Estimates -- [x] Multiple Companies -- [x] Recurring Invoices -- [x] Customer Portal -- [x] Decoupled system settings from company settings _(v3.0)_ -- [x] Proper multi-tenancy system _(v3.0)_ -- [x] Company member invitations with custom roles _(v3.0)_ -- [x] Dark mode _(v3.0)_ -- [x] Full TypeScript refactor of the frontend _(v3.0)_ -- [x] Improved backend architecture _(v3.0)_ -- [x] Security hardening _(v3.0)_ -- [ ] **Reworked installation wizard** _(v3.0)_ -- [ ] **Module Directory** _(v3.0)_ -- [ ] **Rewritten Payments module** _(v3.0)_ -- [ ] Accept Payments (Stripe integration) -- [ ] Improved template system for invoices and estimates - -## Translate - -Help us translate InvoiceShelf into your language: https://crowdin.com/project/invoiceshelf - -## Star History - - - - - - Star History Chart - - - -## License - -InvoiceShelf is released under the [GNU Affero General Public License v3.0](LICENSE). See [LICENSE](LICENSE) for the full text. diff --git a/resources/static/img/invoiceshelf-dashboard.png b/resources/static/img/invoiceshelf-dashboard.png new file mode 100644 index 00000000..56c3ed7a Binary files /dev/null and b/resources/static/img/invoiceshelf-dashboard.png differ diff --git a/tests/Unit/InstallationRequirementsTest.php b/tests/Unit/InstallationRequirementsTest.php new file mode 100644 index 00000000..38d60b09 --- /dev/null +++ b/tests/Unit/InstallationRequirementsTest.php @@ -0,0 +1,7 @@ +toBe(config('invoiceshelf.min_php_version')) + ->toBe('8.4.0'); +});