| [List of supported environment variables](#TODO) | TODO: The full list of environment variables you can use to override the default configuration |
| [Configuring SSL](#TODO) | How to configure SSL so that your OpenProject installation is available over HTTPS |
| [Configuring outbound emails](#TODO) | How to configure outbound emails for notifications, etc. |
| [List of supported environment variables](./environment) | The full list of environment variables you can use to override the default configuration |
| [Configuring SSL](./ssl) | How to configure SSL so that your OpenProject installation is available over HTTPS |
| [Configuring outbound emails](./outbound-emails) | How to configure outbound emails for notifications, etc. |
| [Configuring inbound emails](#TODO) | TODO: How to configure inbound emails for work package updates directly from an email |
| [Configuring a custom database](#TODO) | How to use an external database |
| [Configuring a custom web server](#TODO) | TODO: How to use a custom web server (e.g. NginX) with your OpenProject installation |
| [Configuring a custom web server](#TODO) | TODO: How to use a custom caching server with your OpenProject installation |
| [Adding plugins](#TODO) | TODO: How to add plugins to your OpenProject installation |
| [Configuring a custom database](./database) | How to use an external database |
| [Configuring a custom web server](./server) | How to use a custom web server (e.g. NginX) with your OpenProject installation |
| [Configuring a custom caching server](#TODO) | TODO: How to use a custom caching server with your OpenProject installation |
| [Adding plugins](./plugins) | How to add plugins to your OpenProject installation |
Note: this guide only applies if you've installed OpenProject using our DEB/RPM packages.
A [number of plugins](https://www.openproject.org/plugins/) exist for use with OpenProject. Most plugins that are maintained by us are shipping with OpenProject, however there are several plugins contributed by the community.
Previously, using them in a packaged installation was not possible without losing your changes on every upgrade. With the following steps, you can now use third party plugins.
Note: We cannot guarantee upgrade compatibility for third party plugins nor do we provide support for them. Please carefully check whether the plugins you use are available in newer versions before upgrading your installation.
## Add a custom Gemfile
If you have a plugin you wish to add to your packaged OpenProject installation, create a separate Gemfile with the Gem dependencies, such as the following:
The group `:opf_plugins` is generally recommended, but only required for plugins with custom frontend code that is picked up by webpack and output into their respective bundles.
We suggest to store the Gemfile under `/etc/openproject/Gemfile.custom`, but the choice is up to you, just make sure the openproject user is able to read it.
## Propagate the Gemfile to the package
You have to tell your installation to use the custom gemfile via a config setting:
If your plugin links into the Angular frontend, you will need to set the following environment variable to ensure it gets recompiled. Please note that NPM dependencies will be installed during the installation, and the angular CLI compilation will take place which will delay the configuration process by a few minutes.
To re-bundle the application including the new plugins, as well as running migrations and precompiling their assets, simply re-run the installer while using the same configuration as before.
```
openproject configure
```
Using configure will take your previous decisions in the installer and simply re-apply them, which is an idempotent operation. It will detect the Gemfile config option being set and re-bundle the application with the additional plugins.
Both the packaged and docker-based installations ship with Apache as the default web server, because the Git and SVN repository integrations (when OpenProject manages the repositories) only work with that web server.
For a packaged-based installation, if for instance you wish to use NginX, you will need to skip the web server installation when asked in the initial configuration, and then configure NginX yourself so that it forwards traffic to the OpenProject web process (listening by default on 127.0.0.1:6000).If using SSL/TLS, please ensure you set the header value `X-Forwarded-Proto https` so OpenProject can correctly produce responses.
For a docker-based installation, you will need to switch to the single-process launch mode, where you would launch one or more containers for the `web` process, one container for the `worker` process, and then setup a web server of your choice in another container that forwards traffic to the `web` container(s). A simplified Compose file would look like:
This requires your OpenProject server to be available from the Internet on port 443 or 80.
If this works the certificate (`cert.pem`) and private key (`privkey.pem`) will be created under `/etc/letsencrypt/live/openproject.mydomain.com/`. Configure these for OpenProject to use by running `openproject reconfigure` and choosing yes when the wizard asks for SSL.
Now this Let's Encryt certificate is only valid for 90 days. To renew it automatically all you have to do is to add the following entry to your crontab (run `crontab -e`):
This will execute `certbot renew` every day at 1am. The command checks if the certificate is expired and renews it if that is the case. The web server is restarted in a post hook in order for it to pick up the new certificate.
Yes, but you will lose the ability to enable Git/SVN repository integration. Note that the OpenProject installer does not support NginX, so you will have to ask to disable the Apache2 integration when running the installer, and then configure NginX yourself so that it forwards traffic to the OpenProject web process (listening by default on 127.0.0.1:6000). If using SSL/TLS, please ensure you set the header value `X-Forwarded-Proto https` so OpenProject can correctly produce responses. [For more information, please visit our forums](https://community.openproject.com/projects/openproject/boards).
## Can I use MySQL instead of PostgreSQL?
OpenProject has traditionally supported both MySQL and PostgreSQL, but in order to optimize for performance and SQL functionality, it is unfeasible to support both DBMS that are becoming more and more disjunct when trying to use more modern SQL features. This shift has started some years ago when full-text search was added for PostgreSQL, but at the time MySQL did not yet support it - and as of yet many distributions still do not support MySQL 8 natively.
This led us to the path of removing support in the upcoming stable releases of OpenProject in order to focus on these goals. [Please see our blog post on the matter for additional notes](https://www.openproject.org/deprecating-mysql-support/).
## How can I migrate my existing MySQL database to PostgreSQL ?
Older installations of OpenProject are likely installed with a MySQL installation because the installer shipped with an option to auto-install it. With [pgloader](https://pgloader.io), it is trivially easy to convert a dump between MySQL and PostgreSQL installation. [We have prepared a guide](https://www.openproject.org/operations/upgrading/migrating-packaged-openproject-database-postgresql/) on how to migrate to a PostgreSQL database if you previously used MySQL.
## My favorite linux distribution is not listed. What can I do?
You can either try the manual installation, or ask in the forum whether this could be added to the list of supported distributions. We try to support recent major distributions, but due to maintenance and operations cost cannot freely add to that list.
## What is the better option to run OpenProject in production environments: docker or linux packages?
We recommend the Linux packages [if you have a compatible distribution](https://www.openproject.org/system-requirements/) and a separate machine for OpenProject, since it will allow for the easiest and most flexible setup. Use a docker-based image either for quickly spinning up an environment or if you have knowledge in setting up and maintaing docker-based installations.
@ -67,62 +48,31 @@ We recommend the Linux packages [if you have a compatible distribution](https://
Please note we currently do not yet provide a docker-compose based image, [please see this ticket for a timeline](https://community.openproject.com/wp/30551) and help us contribute one!
## Do you provide different release channels?
Yes! We release OpenProject in separate release channels that you can try out. For production environments, **always** use the `stable/MAJOR` (e.g., stable/9) package source that will receive stable and release updates. Every major upgrade will result in a source switch (from `stable/7` to `stable/8` for example).
A closer look at the available branches:
* [stable/9](https://packager.io/gh/opf/openproject/refs/stable/9): Latest stable releases, starting with 9.0.0 until the last minor and patch releases of 9.X.Y are released, this will receive updates.
* [release/9.0](https://packager.io/gh/opf/openproject/refs/release/9.0): Regular (usually daily) release builds for the current next patch release (or for the first release in this version, such as 9.0.0). This will contain early bugfixes before they are being release into stable. **Do not use in production**. But, for upgrading to the next major version, this can be regarded as a _release candidate channel_ that you can use to test your upgrade on a copy of your production environment.
* [stable/10](https://packager.io/gh/opf/openproject/refs/stable/10): Latest stable releases, starting with 10.0.0 until the last minor and patch releases of 10.X.Y are released, this will receive updates.
* [release/10.0](https://packager.io/gh/opf/openproject/refs/release/10.0): Regular (usually daily) release builds for the current next patch release (or for the first release in this version, such as 10.0.0). This will contain early bugfixes before they are being release into stable. **Do not use in production**. But, for upgrading to the next major version, this can be regarded as a _release candidate channel_ that you can use to test your upgrade on a copy of your production environment.
* [dev](https://packager.io/gh/opf/openproject/refs/dev): Daily builds of the current development build of OpenProject. While we try to keep this operable, this may result in broken code and/or migrations from time to time. Use when you're interested what the next release of OpenProject will look like. **Do not use in production!**
For more information, please visit our dedicated [page regarding release candidates and channels](https://www.openproject.org/download-and-installation/release-candidate/).
## How to upgrade my OpenProject installation?
Please refer to the documentation at https://www.openproject.org/operations/upgrading/
## What skills should I have for the installation?
If you use the packaged installation, you should have a basic knowledge of Linux and the command-line terminal.
If you use the docker images, you need to be familiar with Docker and Docker volumes.
## Why don't you support Windows?
Ruby support on Windows is notoriously difficult, however you might be able to run the Docker image, or use the unofficial Windows stack provided by [Bitnami](https://bitnami.com/stack/openproject/installer). We would welcome feedback and reported experiences on running OpenProject on Windows, please reach out to us if you can contribute some information.
## How to backup and restore my OpenProject installation?
Please refer to the [backup documentation](../backing-up) for the packaged installation.
## How can I install a free SSL certificate using let's encrypt?
You can get an SSL certificate for free via Let's Encrypt.
Here is how you do it using [certbot](https://github.com/certbot/certbot):
This requires your OpenProject server to be available from the Internet on port 443 or 80.
If this works the certificate (`cert.pem`) and private key (`privkey.pem`) will be created under `/etc/letsencrypt/live/openproject.mydomain.com/`. Configure these for OpenProject to use by running `openproject reconfigure` and choosing yes when the wizard asks for SSL.
Now this Let's Encryt certificate is only valid for 90 days. To renew it automatically all you have to do is to add the following entry to your crontab (run `crontab -e`):
This will execute `certbot renew` every day at 1am. The command checks if the certificate is expired and renews it if that is the case. The web server is restarted in a post hook in order for it to pick up the new certificate.
Cyril Rohr
5 years ago