From ff0f491b77d3ba2cc4708d2e65e908c32ed2dd25 Mon Sep 17 00:00:00 2001 From: Rihards Simanovics Date: Sun, 23 Mar 2025 02:36:49 +0000 Subject: [PATCH 1/2] docs: re-write the docker setup --- docs/install/docker.md | 121 ++++++++++++++++++++++++++++++++++------- 1 file changed, 101 insertions(+), 20 deletions(-) diff --git a/docs/install/docker.md b/docs/install/docker.md index 263ed43..58d2d4e 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -9,7 +9,7 @@ We have pre-configured [Docker image](https://hub.docker.com/r/invoiceshelf/invo Follow the steps bellow to get started. -If you notice any issues report it to [InvoiceShelf/docker](https://github.com/invoiceshelf/docker). +If you notice any issues report it to [InvoiceShelf/docker](https://github.com/InvoiceShelf/docker/issues). ## Step 1 : Install Docker @@ -19,43 +19,124 @@ Install Docker on your host: [https://docs.docker.com/install/](https://docs.doc Open terminal and clone the repository by running: -``` +```sh git clone https://github.com/InvoiceShelf/docker ``` ## Step 3 : Prepare docker-compose -Navigate to the cloned repository folder (`docker`) and copy one of the example files (docker-compose.{db}.yml) to docker-compose.yml +Navigate to the cloned repository folder `cd docker/` and copy one of the example docker compose files with your desired database to `docker-compose.yml`, like shown below: + +### MySQL -If you want to use MySQL, take `docker-compose.mysql.yml` and copy it to `docker-compose.yml` in the same folder. +```sh +cp ./docker-compose.mysql.yml docker-compose.yml +``` -This will make it possible to run `docker compose up/down` commands without specifying `-f path/to/docker-compose.yml` in the `docker` folder. +### PostgreSQL -## Step 4 : Finalize & Run docker-compose +```sh +cp ./docker-compose.pgsql.yml docker-compose.yml +``` -Edit `docker-compose.yml` and adjust the configuration as per your needs. +### SQLite -And finally, open Terminal in the `docker` folder and spin up InvoiceShelf app: +```sh +cp ./docker-compose.sqlite.yml docker-compose.yml +``` +> 📝 NOTE +> +> This will make it possible to run `docker compose` `up` or `down` commands without specifying `-f` ( or `--file` - compose configuration files) flag. + +## Step 4 : Adjust the services environment variables + +Open the newly created `docker-compose.yml` in your editor of choice and adjust the configuration as per your needs. + +> ⚠️ IMPORTANT +> +> Make sure to pay close attention to the following environment variables when editing the file as after initial setup if you ever restart the container those will be used instead of what you entered during the setup. + +> 📝 NOTE +> +> You can simply run the `docker compose -f docker-compose.XXX.yml up -d` (where XXX is the Database type of your choice) if you only want to trial the invoiceShelf without committing to a more permanent setup. +> +> You can ever remove `-d` (detached mode) so it only runs while you have the terminal open, though you will still need to manually clean-up the containers and images once you are done. + +```yml +## truncated generic example `docker-compose.yml` + +services: + invoiceshelf_db: + ... + environment: + ## Set your database password + - XXX_PASSWORD=somepass # Where XXX is the Database Type of your choice. + ... + + invoiceshelf: + ... + environment: + ## Set to exactly the same password as in invoiceshelf_db service + - DB_PASSWORD=somepass + + ## Set to your actual time zone - this is needed for running daily tasks + ## such as recurring invoices + PHP timezone e.g. PHP_TZ=America/New_York + + ## Set to 'false' if running in production + - APP_DEBUG=true + + ## If you are running in production and have a domain make sure to set an + ## actual domain name otherwise you will get CSRF error on login. + ## Also make sure to update these values if you ever change the domain name. + - APP_URL=http://localhost:90 # Set to https if using SSL. + - SESSION_DOMAIN=localhost # Enter just the domain name. + - SANCTUM_STATEFUL_DOMAINS=localhost:90 # Enter the domain name and a custom port. + + ## Uncomment and set your smtp or other provider (ensure to use the same + ## as during the setup) + - MAIL_DRIVER=smtp + - MAIL_HOST=smtp.mailtrap.io + - MAIL_PORT=2525 + - MAIL_USERNAME=null + - MAIL_PASSWORD=null + - MAIL_PASSWORD_FILE= + - MAIL_ENCRYPTION=null + ... ``` -$ docker compose up -d + +## Step 5 : Deploy the docker containers + +Open the terminal in the `docker/` folder and spin up InvoiceShelf app: + +```sh +docker compose up -d ``` -## Step 5 : Complete installation wizard +> 📝 NOTE +> +> You can later run `docker compose down` to shutdown the application. -Open your web browser and go to your given domain and follow the installation wizard. +## Step 6 : Complete installation wizard -##### 5.1. MySQL/PostgresSQL +Open your web browser and go to your the url defined in your `APP_URL`, and follow the installation wizard. -For MySQL or PostgreSQL, you can use the following Database setup: +### 6.1. Database Setup inside the Wizard -- Database Host: `invoiceshelf` -- Database Name: `invoiceshelf` -- Database Username: `invoiceshelf` -- Database Password: `somepass` +> 📝 NOTE +> +> In the future this section will not be necessary as we will implement a docker install detection system. -**Important**: The database password `somepass` is example and should be changed in the docker-compose.yml file before you run the project, especially if you expose it in public. +> ⚠️ IMPORTANT +> +> If using SQLite DB **leave the `database.sqlite` path as is**, otherwise it will NOT work correctly. -##### 5.2. SQLite Database +For MySQL and PostgreSQL, you can use the following Database setup: -Leave the `database.sqlite` path as is, otherwise it will NOT work correctly. \ No newline at end of file +| Field | Value | +| ----------------- | ------------------------------------------------------------------------------------- | +| Database Host | `invoiceshelf_db` | +| Database Name | `invoiceshelf` | +| Database Username | `invoiceshelf` | +| Database Password | `somepass` (or the password you defined in `DB_PASSWORD` inside `docker-compose.yml`) | From b408aa21f8c31b9278e1580002c4949e97859a34 Mon Sep 17 00:00:00 2001 From: Rihards Simanovics Date: Sun, 23 Mar 2025 02:48:15 +0000 Subject: [PATCH 2/2] chore: typo correction --- docs/install/docker.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/install/docker.md b/docs/install/docker.md index 58d2d4e..67ecef0 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -59,9 +59,9 @@ Open the newly created `docker-compose.yml` in your editor of choice and adjust > 📝 NOTE > -> You can simply run the `docker compose -f docker-compose.XXX.yml up -d` (where XXX is the Database type of your choice) if you only want to trial the invoiceShelf without committing to a more permanent setup. +> You can simply run the `docker compose -f docker-compose.XXX.yml up -d` (where XXX is the Database type of your choice) if you only want to trial the invoiceShelf, without committing to a more permanent setup. > -> You can ever remove `-d` (detached mode) so it only runs while you have the terminal open, though you will still need to manually clean-up the containers and images once you are done. +> You can even remove `-d` (detached mode) so it only runs while you have the terminal open, though you will still need to manually clean-up the containers and images once you are done. ```yml ## truncated generic example `docker-compose.yml` @@ -88,13 +88,13 @@ services: - APP_DEBUG=true ## If you are running in production and have a domain make sure to set an - ## actual domain name otherwise you will get CSRF error on login. - ## Also make sure to update these values if you ever change the domain name. + ## actual domain name, otherwise you will get CSRF error on login. + ## Also, make sure to update these values if you ever change the domain name. - APP_URL=http://localhost:90 # Set to https if using SSL. - SESSION_DOMAIN=localhost # Enter just the domain name. - SANCTUM_STATEFUL_DOMAINS=localhost:90 # Enter the domain name and a custom port. - ## Uncomment and set your smtp or other provider (ensure to use the same + ## Uncomment and set your SMTP or other provider (ensure to use the same ## as during the setup) - MAIL_DRIVER=smtp - MAIL_HOST=smtp.mailtrap.io @@ -126,7 +126,7 @@ Open your web browser and go to your the url defined in your `APP_URL`, and foll > 📝 NOTE > -> In the future this section will not be necessary as we will implement a docker install detection system. +> In the future this section will not be necessary, as we will implement a docker install detection system. > ⚠️ IMPORTANT >