diff --git a/compose/.env.example b/.env.example similarity index 100% rename from compose/.env.example rename to .env.example diff --git a/.gitignore b/.gitignore index a499c1a..08eb01f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,3 @@ -# Jetbrains IDE -.idea/ +.env -*.swp -*.tar.gz +docker-compose.override.yml diff --git a/README.md b/README.md index c76eb75..8afe58a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,182 @@ -# OpenProject Deploy +# OpenProject installation with Docker Compose -Recipes and examples for deploying OpenProject. +This repository contains the installation method for OpenProject using Docker Compose. -* [Docker Compose](./compose/) -* [Kubernetes](./kubernetes/) + +> [!NOTE] +> Looking for the Kubernetes installation method? +> Please use the [OpenProject helm chart](https://charts.openproject.org) to install OpenProject on kubernetes. + +## Install + +Clone this repository: + +```shell +git clone https://github.com/opf/openproject-deploy --depth=1 --branch=stable/14 openproject +``` + +Copy the example `.env` file and edit any values you want to change: + +```shell +cp .env.example .env +vim .env +``` + +Next you start up the containers in the background while making sure to pull the latest versions of all used images. + +```shell +docker compose up -d --build --pull always +``` + +After a while, OpenProject should be up and running on . + +### Troubleshooting + +**pull access denied for openproject/proxy, repository does not exist or may require 'docker login': denied: requested access to the resource is denied** + +If you encounter this after `docker compose up` this is merely a warning which can be ignored. + +If this happens during `docker compose pull` this is simply a warning as well. +But it will result in the command's exit code to be a failure even though all images are pulled. +To prevent this you can add the `--ignore-buildable` option, running `docker compose pull --ignore-buildable`. + +### HTTPS/SSL + +By default OpenProject starts with the HTTPS option **enabled**, but it **does not** handle SSL termination itself. This +is usually done separately via a [reverse proxy +setup](https://www.openproject.org/docs/installation-and-operations/installation/docker/#apache-reverse-proxy-setup). +Without this you will run into an `ERR_SSL_PROTOCOL_ERROR` when accessing OpenProject. + +See below how to disable HTTPS. + +Be aware that if you want to use the integrated Caddy proxy as a proxy with outbound connections, you need to rewrite the +`Caddyfile`. In the default state, it is configured to forward the `X-Forwarded-*` headers from the reverse proxy in +front of it and not setting them itself. This is considered a security flaw and should instead be solved by configuring +`trusted_proxies` inside the `Caddyfile`. For more information read +the [Caddy documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy). + +### PORT + +By default the port is bound to `0.0.0.0` means access to OpenProject will be public. +See below how to change that. + +## Configuration + +Environment variables can be added to `docker-compose.yml` under `x-op-app -> environment` to change +OpenProject's configuration. Some are already defined and can be changed via the environment. + +You can pass those variables directly when starting the stack as follows. + +``` +VARIABLE=value docker-compose up -d +``` + +You can also put those variables into an `.env` file in your current working +directory, and Docker Compose will pick it up automatically. See `.env.example` +for details. + +## HTTPS + +You can disable OpenProject's HTTPS option via: + +``` +OPENPROJECT_HTTPS=false +``` + +## PORT + +If you want to specify a different port, you can do so with: + +``` +PORT=4000 +``` + +If you don't want OpenProject to bind to `0.0.0.0` you can bind it to localhost only like this: + +``` +PORT=127.0.0.1:8080 +``` + +## TAG + +If you want to specify a custom tag for the OpenProject docker image, you can do so with: + +``` +TAG=my-docker-tag +``` + +## Upgrade + +Retrieve any changes from the `openproject-deploy` repository: + + git pull origin stable/14 + +Build the control plane: + + docker-compose -f docker-compose.yml -f docker-compose.control.yml build + +Take a backup of your existing postgresql data and openproject assets: + + docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup + +Run the upgrade: + + docker-compose -f docker-compose.yml -f docker-compose.control.yml run upgrade + +Relaunch the containers, ensure you are pulling to use the latest version of the Docker images: + + docker compose up -d --build --pull always + + + +## Backup + +Switch off your current installation: + + docker-compose down + +Build the control scripts: + + docker-compose -f docker-compose.yml -f docker-compose.control.yml build + +Take a backup of your existing PostgreSQL data and OpenProject assets: + + docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup + +Restart your OpenProject installation + + docker-compose up -d + + + +## Uninstall + +You can remove the stack with: + + docker-compose down + +## Troubleshooting + +You can look at the logs with: + + docker-compose logs -n 1000 + +For the complete documentation, please refer to https://docs.openproject.org/installation-and-operations/. + +### Network issues + +If you're running into weird network issues and timeouts such as the one described in +[OP#42802](https://community.openproject.org/work_packages/42802), you might have success in remove the two separate +frontend and backend networks. This might be connected to using podman for orchestration, although we haven't been able +to confirm this. + +### SMTP setup fails: Network is unreachable. + +Make sure your container has DNS resolution to access external SMTP server when set up as described in +[OP#44515](https://community.openproject.org/work_packages/44515). + +```yml +worker: + dns: + - "Your DNS IP" # OR add a public DNS resolver like 8.8.8.8 +``` diff --git a/compose/.gitignore b/compose/.gitignore deleted file mode 100644 index 08eb01f..0000000 --- a/compose/.gitignore +++ /dev/null @@ -1,3 +0,0 @@ -.env - -docker-compose.override.yml diff --git a/compose/README.md b/compose/README.md deleted file mode 100644 index f9f44d7..0000000 --- a/compose/README.md +++ /dev/null @@ -1,155 +0,0 @@ -# OpenProject installation with Docker Compose - -## Install - -Clone this repository: - -```shell -git clone https://github.com/opf/openproject-deploy --depth=1 --branch=stable/14 openproject -``` - -Go to the compose folder: - -```shell -cd openproject/compose -``` - -Copy the example `.env` file and edit any values you want to change: - -```shell -cp .env.example .env -vim .env -``` - -Next you start up the containers in the background while making sure to pull the latest versions of all used images. - -```shell -docker compose up -d --build --pull always -``` - -After a while, OpenProject should be up and running on . - -### Troubleshooting - -**pull access denied for openproject/proxy, repository does not exist or may require 'docker login': denied: requested access to the resource is denied** - -If you encounter this after `docker compose up` this is merely a warning which can be ignored. - -If this happens during `docker compose pull` this is simply a warning as well. -But it will result in the command's exit code to be a failure even though all images are pulled. -To prevent this you can add the `--ignore-buildable` option, running `docker compose pull --ignore-buildable`. - -### HTTPS/SSL - -By default OpenProject starts with the HTTPS option **enabled**, but it **does not** handle SSL termination itself. This -is usually done separately via a [reverse proxy -setup](https://www.openproject.org/docs/installation-and-operations/installation/docker/#apache-reverse-proxy-setup). -Without this you will run into an `ERR_SSL_PROTOCOL_ERROR` when accessing OpenProject. - -See below how to disable HTTPS. - -Be aware that if you want to use the integrated Caddy proxy as a proxy with outbound connections, you need to rewrite the -`Caddyfile`. In the default state, it is configured to forward the `X-Forwarded-*` headers from the reverse proxy in -front of it and not setting them itself. This is considered a security flaw and should instead be solved by configuring -`trusted_proxies` inside the `Caddyfile`. For more information read -the [Caddy documentation](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy). - -### PORT - -By default the port is bound to `0.0.0.0` means access to OpenProject will be public. -See below how to change that. - -## Configuration - -Environment variables can be added to `docker-compose.yml` under `x-op-app -> environment` to change -OpenProject's configuration. Some are already defined and can be changed via the environment. - -You can pass those variables directly when starting the stack as follows. - -``` -VARIABLE=value docker-compose up -d -``` - -You can also put those variables into an `.env` file in your current working -directory, and Docker Compose will pick it up automatically. See `.env.example` -for details. - -## HTTPS - -You can disable OpenProject's HTTPS option via: - -``` -OPENPROJECT_HTTPS=false -``` - -## PORT - -If you want to specify a different port, you can do so with: - -``` -PORT=4000 -``` - -If you don't want OpenProject to bind to `0.0.0.0` you can bind it to localhost only like this: - -``` -PORT=127.0.0.1:8080 -``` - -## TAG - -If you want to specify a custom tag for the OpenProject docker image, you can do so with: - -``` -TAG=my-docker-tag -``` - -## Upgrade - -Go to the compose folder: - - cd openproject/compose - -Retrieve any changes from the `openproject-deploy` repository: - - git pull origin stable/12 - -Make sure you are using the latest version of the Docker images: - - docker-compose pull - -Relaunch the containers: - - docker-compose up -d - -## Uninstall - -You can remove the stack with: - - docker-compose down - -## Troubleshooting - -You can look at the logs with: - - docker-compose logs -n 1000 - -For the complete documentation, please refer to https://docs.openproject.org/installation-and-operations/. - -### Network issues - -If you're running into weird network issues and timeouts such as the one described in -[OP#42802](https://community.openproject.org/work_packages/42802), you might have success in remove the two separate -frontend and backend networks. This might be connected to using podman for orchestration, although we haven't been able -to confirm this. - -### SMTP setup fails: Network is unreachable. - -Make sure your container has DNS resolution to access external SMTP server when set up as described in -[OP#44515](https://community.openproject.org/work_packages/44515). - -```yml -worker: - dns: - - "Your DNS IP" # OR add a public DNS resolver like 8.8.8.8 - ``` diff --git a/compose/control/README.md b/compose/control/README.md deleted file mode 100644 index b46cf0a..0000000 --- a/compose/control/README.md +++ /dev/null @@ -1,47 +0,0 @@ -# Control your OpenProject installation - -## Backup - -Switch off your current installation: - - docker-compose down - -Build the control scripts: - - docker-compose -f docker-compose.yml -f docker-compose.control.yml build - -Take a backup of your existing PostgreSQL data and OpenProject assets: - - docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup - -Restart your OpenProject installation - - docker-compose up -d - -## Upgrade - -Switch off your current installation (using the outdated postgres engine): - - docker-compose down - -Fetch the latest changes from this repository: - - git pull origin stable/12 # adjust if needed - -Build the control plane: - - docker-compose -f docker-compose.yml -f docker-compose.control.yml build - -Take a backup of your existing postgresql data and openproject assets: - - docker-compose -f docker-compose.yml -f docker-compose.control.yml run backup - -Run the upgrade: - - docker-compose -f docker-compose.yml -f docker-compose.control.yml run upgrade - -Relaunch your OpenProject installation, using the normal Compose command: - - docker-compose up -d - -Test that everything works again, the database container should now be running postgres 13. diff --git a/compose/control/Dockerfile b/control/Dockerfile similarity index 100% rename from compose/control/Dockerfile rename to control/Dockerfile diff --git a/compose/control/backup/entrypoint.sh b/control/backup/entrypoint.sh similarity index 100% rename from compose/control/backup/entrypoint.sh rename to control/backup/entrypoint.sh diff --git a/compose/control/upgrade/entrypoint.sh b/control/upgrade/entrypoint.sh similarity index 74% rename from compose/control/upgrade/entrypoint.sh rename to control/upgrade/entrypoint.sh index 71a8f78..9cbc947 100755 --- a/compose/control/upgrade/entrypoint.sh +++ b/control/upgrade/entrypoint.sh @@ -5,4 +5,4 @@ set -o pipefail /control/upgrade/scripts/00-db-upgrade.sh echo "Please restart your installation by issuing the following command:" -echo " docker-compose up -d" +echo " docker compose up -d --build --pull always" diff --git a/compose/control/upgrade/scripts/00-db-upgrade.sh b/control/upgrade/scripts/00-db-upgrade.sh similarity index 100% rename from compose/control/upgrade/scripts/00-db-upgrade.sh rename to control/upgrade/scripts/00-db-upgrade.sh diff --git a/compose/docker-compose.control.yml b/docker-compose.control.yml similarity index 100% rename from compose/docker-compose.control.yml rename to docker-compose.control.yml diff --git a/compose/docker-compose.yml b/docker-compose.yml similarity index 100% rename from compose/docker-compose.yml rename to docker-compose.yml diff --git a/kubernetes/MINIKUBE.md b/kubernetes/MINIKUBE.md deleted file mode 100644 index 2bd2f2d..0000000 --- a/kubernetes/MINIKUBE.md +++ /dev/null @@ -1,17 +0,0 @@ -# Accessing OpenProject - -If the minikube tunnel doesn't work, find out the used OpenProject port via - -``` -kubectl --context minikube get services -``` - -and then open the tunnel yourself via - -``` -ssh -i $(minikube ssh-key) docker@localhost -p 60390 -L 8080:localhost:30265 -``` - -to be able to access OpenProject under http://localhost:8080. - -60390 would be the minikube container's mapped ssh port which you can see via `docker ps`. diff --git a/kubernetes/README.md b/kubernetes/README.md deleted file mode 100644 index bef8ad5..0000000 --- a/kubernetes/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# OpenProject installation using Kubernetes - -Please use the [OpenProject helm chart](https://charts.openproject.org) to install OpenProject on kubernetes. diff --git a/compose/proxy/Caddyfile.template b/proxy/Caddyfile.template similarity index 100% rename from compose/proxy/Caddyfile.template rename to proxy/Caddyfile.template diff --git a/compose/proxy/Dockerfile b/proxy/Dockerfile similarity index 100% rename from compose/proxy/Dockerfile rename to proxy/Dockerfile