Skip to content

docs: re-write the docker setup #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: re-write the docker setup #10

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff0f491
docs: re-write the docker setup
rihards-simanovics Mar 23, 2025
b408aa2
chore: typo correction
rihards-simanovics Mar 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 101 additions & 20 deletions docs/install/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 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`

services:
invoiceshelf_db:
...
environment:
## Set your database password
- XXX_PASSWORD=somepass # Where XXX is the Database Type of your choice.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

May be give examples SQLITE_PASSWORDetc. Idk well the docker part but why not DB_PASSWORD too ?

Copy link
Member Author

@rihards-simanovics rihards-simanovics Apr 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Different Docker images use different environment variables, just like our own IS image. The MySQL image specifically requires the password environment variable to be set to MYSQL_PASSWORD, while the PostgreSQL image requires POSTGRES_PASSWORD.

Does our SQLite database have a password? Since the DB is stored locally in the project root and not encrypted by a password, I thought we only provided a path; I can update the doc if that's not the case.

...

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=<filename>
- 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.
| 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`) |