OpenProject can be configured either via the `config/configuration.yml` file, [environment variables](environment/) or a mix of both.
While the latter is probably a bad idea, the environment variable option is often helpful for automatically deploying production systems.
Using the configuration file is probably the simplest way of configuration.
OpenProject can be configured either via environment variables. These are often helpful for automatically deploying production systems.
You can find a list of options below and an example file in [config/configuration.yml.example](https://github.com/opf/openproject/blob/dev/config/configuration.yml.example)
> **NOTE:** This documentation is for OpenProject on-premises Installations only, if you would like to setup similar in your OpenProject cloud instance, please contact us at support@openproject.com
> **NOTE:** Using the configuration file `config/configuration.yml` is depracted and is **NOT** recommended anymore
## Environment variables
Configuring OpenProject through environment variables is detailed [in this separate guide](environment/).
# Packaged installation
## List of options
The file `/opt/openproject/.env.example` contains some information to learn more. The file `/opt/openproject/conf.d/env` is used for parsing the variables and your custom values to your configuration.
To configure the environment variables such as the number of web server threads OPENPROJECT_HTTPS, copy the `.env.example` to `/etc/openproject/conf.d/env` and add the environment variables you want to configure. The variables will be automatically loaded to the application’s environment.
After changing the file `/etc/openproject/conf.d/env` the command `sudo openproject configure` must be issued
If you would like to change only one variable you are able to configure the environment variable by using the following command:
This will write the value of the variable to the file `/etc/openproject/conf.d/other`.
After the file `/etc/openproject/conf.d/other` is changed the command `sudo openproject configure` must be issued
Configuring OpenProject through environment variables is described in detail [in the environment variables guide](environment/).
# Docker
## one container per process installation
Add your custom configuration to `docker-compose.override.yml`.
In the compose folder you will also find the file `docker-compose.yml` which shall **NOT** be edited.
After changing the file `docker-compose.override.yml` the command `docker-compose down && docker-compose up -d` must be issued
To add an environment variable manually to the docker-compose file, add it to the `environment:` section of the `op-x-app` definition like in the following example:
# set to true to enable the email receiving feature. See ./docker/cron for more options
IMAP_ENABLED: "${IMAP_ENABLED:-false}"
volumes:
- "${OPDATA:-opdata}:/var/openproject/assets"
# configuration cut off at this point.
# Please use the file at https://github.com/opf/openproject-deploy/blob/stable/12/compose/docker-compose.yml
```
Alternatively, you can also use an env file for docker-compose like so:
First, add a `.env` file with some variable:
```bash
OPENPROJECT_HTTPS="true"
```
And then you'll need to pass the environment variable to the respective containers you want to set it on. For most OpenProject environment variables, this will be for `x-op-app`:
```yaml
version: "3.7"
networks:
frontend:
backend:
volumes:
pgdata:
opdata:
x-op-restart-policy: &restart_policy
restart: unless-stopped
x-op-image: &image
image: openproject/community:${TAG:-12}
x-op-app: &app
<<:[*image,*restart_policy]
environment:
OPENPROJECT_HTTPS: ${OPENPROJECT_HTTPS}
# ... more environment variables
# configuration cut off at this point.
# Please use the file at https://github.com/opf/openproject-deploy/blob/stable/12/compose/docker-compose.yml
```
Let's say you have a `.env.prod` file with some production-specific configuration. Then, start the services with that special env file specified.
```bash
docker-compose --env-file .env.prod up
```
### Disabling services in the docker-compose file
If you have a `docker-compose.override.yml` file created, it is also easy to disable certain services, such as the database container if you have an external one running anyway.
To do that, add this section to the file:
```yaml
services:
db:
deploy:
replicas: 0
```
Configuring OpenProject through environment variables is described in detail [in the environment variables guide](environment/).
## Docker all-in-one container installation
Environment variables can be either passed directly on the command-line to the
Docker Engine, or via an environment file:
```bash
docker run -d -e KEY1=VALUE1 -e KEY2=VALUE2 ...
# or
docker run -d --env-file path/to/file ...
```
Configuring OpenProject through environment variables is described in detail [in the environment variables guide](environment/).
## Examples for common use cases
* `attachments_storage_path`
* `autologin_cookie_name` (default: 'autologin'),
@ -55,18 +195,28 @@ Configuring OpenProject through environment variables is detailed [in this separ
Use `session_store` to define where session information is stored. In order to store sessions in the database and use the following options, set that configuration to `:active_record_store`.
**Delete old sessions for the same user when logging in** (Disabled by default)
**Delete old sessions for the same user when logging in**
To enable, set the configuration option`drop_old_sessions_on_login` to true.
To enable, set the configuration option:
**Delete old sessions for the same user when logging out** (Enabled by default)
*default: false*
To disable, set the configuration option `drop_old_sessions_on_logout` to false.
If you enable this option you have to configure at least one omniauth authentication
provider to take care of authentication instead of the password login.
@ -74,42 +224,49 @@ provider to take care of authentication instead of the password login.
All username/password forms will be removed and only a list of omniauth providers
presented to the users.
*default: false*
```yaml
OPENPROJECT_DISABLE__PASSWORD__LOGIN="true"
```
### auth source sso
Can be used to automatically login a user defined through a custom header sent by a load balancer or reverse proxy in front of OpenProject, for instance in a Kerberos Single Sign-On (SSO) setup via apache.
The header with the given name has to be passed to OpenProject containing the logged in user and the defined global secret as in `$login:$secret`.
# Optional secret to be passed by the header in form
# of a colon-separted userinfo string
# e.g., X-Remote-User "username:s3cret"
secret: s3cr3t
# Uncomment to make the header optional.
# optional: true
This example in the old `configuration.yml` looked like this:
Can be used to automatically login a user defined through a custom header
sent by a load balancer or reverse proxy in front of OpenProject,
for instance in a Kerberos Single Sign-On (SSO) setup via apache.
The header with the given name has to be passed to OpenProject containing the logged in
user and the defined global secret as in `$login:$secret`.
```yaml
auth_source_sso:
header: X-Remote-User
# Optional secret to be passed by the header in form
# of a colon-separted userinfo string
# e.g., X-Remote-User "username:s3cret"
secret: s3cr3t
# Uncomment to make the header optional.
# optional: true
```
### omniauth direct login provider
*default: nil*
Example:
Per default the user may choose the usual password login as well as <u>several</u> omniauth providers on the login page and in the login drop down menu. With this configuration option you can set a specific omniauth provider to be used for direct login. Meaning that the login provider selection is skipped and the configured provider is used directly (non-interactive) instead.
omniauth_direct_login_provider: google
If this option is active, a login will lead directly to the configured omniauth provider and so will a click on 'Sign in' (the drop down menu will not open).
Per default the user may choose the usual password login as well as several omniauth providers on the login page and in the login drop down menu. With his configuration option you can set a specific omniauth provider to be used for direct login. Meaning that the login provider selection is skipped and the configured provider is used directly instead.
> **NOTE:** This does not stop a user from manually navigating to any other omniauth provider if additional ones are configured.
If this option is active /login will lead directly to the configured omniauth provider and so will a click on 'Sign in' (as opposed to opening the drop down menu).
*default: nil*
Note that this does not stop a user from manually navigating to any other
omniauth provider if additional ones are configured.
@ -119,342 +276,292 @@ You can override this behavior by setting `gravatar_fallback_image` to a differe
For supported values, please see [en.gravatar.com/site/implement/images/](https://en.gravatar.com/site/implement/images/)
*default: 404*
### Attachments storage
```yaml
OPENPROJECT_GRAVATAR__FALLBACK__IMAGE="identicon"
```
You can modify the folder that attachments are stored locally. Use the `attachments_storage_path` configuration variable for that. But ensure that you move the existing paths. To find out the current path on a packaged installation, use `openproject config:get ATTACHMENTS_STORAGE_PATH`.
To update the path, use `openproject config:set ATTACHMENTS_STORAGE_PATH="/path/to/new/folder"`. Ensure that this is writable by the `openproject` user.
### Attachments storage
### attachment storage type
You can modify the folder that attachments are stored locally. Use the `attachments_storage_path` configuration variable for that. But ensure that you move the existing paths. To find out the current path on a packaged installation, use `openproject config:get ATTACHMENTS_STORAGE_PATH`.
*default: file*
To update the path, use `openproject config:set ATTACHMENTS_STORAGE_PATH="/path/to/new/folder"`. Ensure that this is writable by the `openproject` user. Afterwards issue a restart by `sudo openproject configure`
Attachments can be stored using fog as well. You will have to add further configuration through `fog`, e.g. for Amazon S3:
You can migrate attachments between the available backends. One example would be that you change the configuration from
the file storage to the fog storage. If you want to put all the present file-based attachments into the cloud,
you will have to use the following rake task:
You can migrate attachments between the available backends. One example would be that you change the configuration from the file storage to the fog storage. If you want to put all the present file-based attachments into the cloud, you will have to use the following rake task:
```
```bash
rake attachments:copy_to[fog]
```
It works the other way around too:
```
```bash
rake attachments:copy_to[file]
```
Note that you have to configure the respective storage (i.e. fog) beforehand as described in the previous section.
In the case of fog you only have to configure everything under `fog`, however. Don't change `attachments_storage`
to `fog` just yet. Instead leave it as `file`. This is because the current attachments storage is used as the source
for the migration.
> **NOTE:** that you have to configure the respective storage (i.e. fog) beforehand as described in the previous section. In the case of fog you only have to configure everything under `fog`, however. Don't change `attachments_storage` to `fog` just yet. Instead leave it as `file`. This is because the current attachments storage is used as the source for the migration.
### direct uploads
*default: true*
> **NOTE**: This only works for S3 right now. When using fog with another provider this configuration will be `false`. The same goes for when no fog storage is configured, or when the `use_iam_profile` option is used in the fog credentials when using S3.
When using fog attachments uploaded in the frontend will be posted directly
to the cloud rather than going through the OpenProject servers. This allows large attachments to be uploaded
without the need to increase the `client_max_body_size` for the proxy in front of OpenProject.
Also it prevents web processes from being blocked through long uploads.
When using fog attachments uploaded in the frontend will be posted directly to the cloud rather than going through the OpenProject servers. This allows large attachments to be uploaded without the need to increase the `client_max_body_size` for the proxy in front of OpenProject. Also it prevents web processes from being blocked through long uploads.
If, for what ever reason, this is undesirable, you can disable this option.
In that case attachments will be posted as usual to the OpenProject server which then uploads the file
to the remote storage in an extra step.
If, for what ever reason, this is undesirable, you can disable this option. In that case attachments will be posted as usual to the OpenProject server which then uploads the file to the remote storage in an extra step.
**Note**: This only works for S3 right now. When using fog with another provider this configuration will be `false`. The same goes for when no fog storage is configured, or when the `use_iam_profile` option is used in the fog credentials when using S3.
*default: true*
### fog download url expires in
```yaml
OPENPROJECT_DIRECT__UPLOADS="false"
```
*default: 21600*
### fog download url expires in
Example:
When using remote storage for attachments via fog - usually S3 (see [`attachments_storage`](#attachments-storage) option) - each attachment download will generate a temporary URL. This option determines how long these links will be valid.
fog_download_url_expires_in: 60
The default is 21600 seconds, that is 6 hours, which is the maximum expiry time allowed by S3 when using IAM roles for authentication.
When using remote storage for attachments via fog - usually S3 (see [`attachments_storage`](#attachments-storage) option) -
each attachment download will generate a temporary URL.
This option determines how long these links will be valid.
*default: 21600*
The default is 21600 seconds, that is 6 hours, which is the maximum expiry time
allowed by S3 when using IAM roles for authentication.
```yaml
OPENPROJECT_FOG__DOWNLOAD__URL__EXPIRES__IN="60"
```
### Overriding the help link
### force help link
You can override the default help menu of OpenProject by specifying a `force_help_link` option to
the configuration. This value is used for the href of the help link, and the default dropdown is removed.
### Setting an impressum (legal notice) link
*deafult: nil*
You can set a impressum link for your OpenProject instance by setting `impressum_link` to an absolute URL.
You can disable specific menu items in the menu sidebar for each main menu (such as Administration and Projects). The configuration can be done through environment variables. You have to define one variable for each menu that shall be hidden.
*default: []*
*default: {}*
You can blacklist specific routes
The following example forbid all routes for above disabled menu:
For instance 'Roles' and 'Types' under 'Administration' can be disabled by defining the following variable:
This example in the old `configuration.yml` looked like this:
```yaml
default:
authentication:
global_basic_auth:
user: admin
password: admin
password: adminpw
```
## Security badge
### security badge displayed
OpenProject now provides a release indicator (security badge) that will inform administrators of an OpenProject
installation on whether new releases or security updates are available for your platform.
OpenProject provides a release indicator (security badge) that will inform administrators of an OpenProject installation on whether new releases or security updates are available for your platform. If enabled, this option will display a badge with your installation status at Administration > Information right next to the release version, and on the home screen. It is only displayed to administrators.
If enabled, this option will display a badge with your installation status at Administration > Information right next to the release version,
and on the home screen. It is only displayed to administrators.
The badge will match your current OpenProject version against the official OpenProject release database to alert you of any updates or known vulnerabilities. To ensure the newest available update can be returned, the check will include your installation type, current version, database type, enterprise status and an anonymous unique ID of the instance. To localize the badge, the user's locale is sent. No personal information of your installation or any user within is transmitted, processed, or stored.
The badge will match your current OpenProject version against the official OpenProject release database to alert you of any updates or known vulnerabilities.
To ensure the newest available update can be returned, the check will include your installation type, current version, database type, enterprise status and an anonymous unique ID of the instance.
To localize the badge, the user's locale is sent. No personal information of your installation or any user within is transmitted, processed, or stored.
To disable rendering the badge, uncheck the setting at Administration > System settings > General or pass the configuration flag `security_badge_displayed: false` .
To disable rendering the badge, uncheck the setting at Administration > System settings > General or pass
the configuration flag `security_badge_displayed: false` .
*default=true*
## Cache options:
```yaml
OPENPROJECT_SECURITY__BADGE__DISPLAYED="false"
```
* `rails_cache_store`: `memcache` for [memcached](https://www.memcached.org/) or `memory_store` (default: `file_store`)
* `cache_memcache_server`: The memcache server host and IP (default: `127.0.0.1:11211`)
* `cache_expires_in`: Expiration time for memcache entries (default: `0`, no expiry)
* `cache_namespace`: Namespace for cache keys, useful when multiple applications use a single memcache server (default: none)
### Cache configuration options
## Asset options:
* `rails_cache_store`: `memcache` for [memcached](https://www.memcached.org/) or `memory_store` (default: `file_store`)
* `cache_memcache_server`: The memcache server host and IP (default: `nil`)
* `cache_expires_in`: Expiration time for memcache entries (default: `nil`, no expiry)
* `cache_namespace`: Namespace for cache keys, useful when multiple applications use a single memcache server (default: `nil`)
* `rails_asset_host`: A custom host to use to serve static assets such as javascript, CSS, images, etc. (default: `nil`)
### rails asset host
## Onboarding variables:
`rails_asset_host`: A custom host to use to serve static assets such as javascript, CSS, images, etc. (default: `nil`)
* `onboarding_video_url`: An URL for the video displayed on the onboarding modal. This is only shown when the user logs in for the first time.
### onboarding video url
### Enterprise Limits
`onboarding_video_url`: An URL for the video displayed on the onboarding modal. This is only shown when the user logs in for the first time.
If using an Enterprise token there are certain limits that apply.
backup_daily_limit: 3 # number of times backups can be requested per day across all users
backup_initial_waiting_period: 24.hours # time after which new backup token is usable
backup_include_attachments: true # include/exclude attachments besides db dump
backup_attachment_size_max_sum_mb: 1024 # if all attachments together are larger than this, they will not be included
```yaml
OPENPROJECT_BACKUP__ENABLED="false"
```
Per default the maximum overall size of all attachments must not exceed 1GB for them to be included
in the backup. If they are larger only the database dump will be included.
#### backup attachment size max sum mb
As usual this can be override via the environment, for example like this:
Per default the maximum overall size of all attachments must not exceed 1GB for them to be included in the backup. If they are larger only the database dump will be included.
OpenProject can push metrics to [statsd](https://github.com/statsd/statsd).
Currently these are simply the metrics for the puma server
but this may include more in the future.
OpenProject can push metrics to [statsd](https://github.com/statsd/statsd). Currently these are simply the metrics for the puma server, but this may include more in the future.
This is disabled by default unless a host configured.
This is disabled by default unless a host is configured.
| [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](./incoming-emails) | How to configure inbound emails for work package updates directly from an email |
| [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 | How to use a custom caching server with your OpenProject installation |
| [Configuring Git and Subversion repositories](./repositories) | How to integrate Git and Subversion repositories into OpenProject |
| [Adding plugins](./plugins) | How to add plugins to your OpenProject installation |
| [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](./incoming-emails) | How to configure inbound emails for work package updates directly from an email |
| [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 | How to use a custom caching server with your OpenProject installation |
| [Configuring Git and Subversion repositories](./repositories) | How to integrate Git and Subversion repositories into OpenProject |
| [Adding plugins](./plugins) | How to add plugins to your OpenProject installation |
@ -12,8 +12,7 @@ Simply run `sudo openproject reconfigure`, and when the database wizard is displ
## Docker-based installation
If you run the all-in-one container, you can simply pass a custom
`DATABASE_URL` environment variable on the docker command-line, which could
If you run the all-in-one container, you can simply pass a custom `DATABASE_URL` environment variable on the docker command-line, which could
point to an external database.
Example:
@ -22,9 +21,9 @@ Example:
docker run -d ... -e DATABASE_URL=postgres://user:pass@host:port/dbname openproject/community:12
```
If you run the Compose based docker stack, you can simply override the `DATABASE_URL` environment variable, and remove the `db` service from the `docker-compose.yml` file. Be careful, because by pulling a new version `docker-compose.yml` might get replaced. Best practice is using the file `docker-compose.override.yml` instead. Then you can restart the stack with:
Best practice is using the file `docker-compose.override.yml`. If you run the Compose based docker stack, you can simply override the `DATABASE_URL` environment variable, and remove the `db` service from the `docker-compose.yml` file, but because by pulling a new version `docker-compose.yml` might get replaced. Then you can restart the stack with:
> **NOTE:** This documentation is for OpenProject on-premises Installations only, if you would like to setup similar in your OpenProject cloud instance, please contact us at support@openproject.com
When using environment variables, you can set the options by setting environment variables with the name of the options below in uppercase. So for example, to configure email delivery via an SMTP server, you can set the following environment variables:
```bash
@ -23,7 +25,7 @@ SMTP_ENABLE_STARTTLS_AUTO="true"
In case you want to use environment variables, but you have no easy way to set them on a specific system, you can use the [dotenv](https://github.com/bkeepers/dotenv) gem. It automatically sets environment variables written to a .env file for a Rails application.
Please be aware that **only those variables shall be edited which are documented** as not everything is meant to be configured or bend.
### Nested values
@ -49,7 +51,7 @@ storage config above like this:
OPENPROJECT_STORAGE_TYPE=nfs
```
## Passing data structures
## Passing data structures to the app
The configuration uses YAML to parse overrides from ENV. Using YAML inline syntax, you can:
@ -64,6 +66,22 @@ Example: `{!ruby/symbol key: !ruby/symbol value}` will be parsed as `{ key: :val
Please note: The Configuration is a HashWithIndifferentAccess and thus it should be irrelevant for hashes to use symbol keys.
Here an Example:
Configured in the `/etc/openproject/conf.d/env` like this:
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
```bash
sudo 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.
Both the packaged and docker-based installations ship with Apache2 as the default web server, because the Git and SVN repository integrations (when OpenProject manages the repositories) only work with Apache2.
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 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 use the (recommended) Compose stack, which will allow you to swap the `proxy` container with whatever server you want to use.
For a docker-based installation, you will need to use the (recommended) docker-compose stack, which will allow you to swap the `proxy` container with whatever server you want to use.
For instance you could define a new proxy server like this:
The following example is for NginX as a custom web server:
For instance you could define a new proxy server like this in the `docker-compose.override.yml`:
SSL configuration can be applied on the first installation, or at any time by reconfiguring the application with:
SSL configuration can be applied any time by reconfiguring the application with:
```bash
sudo openproject reconfigure
```
You will be prompted with the same dialogs than on the [initial configuration](../../installation/packaged/#step-3-apache2-web-server-and-ssl-termination) guide. This assumes that you select the **install** option when the **server/autoinstall** dialog appears, and that you have certificate and key files available on your server at a path you know.
You will be prompted with the same dialogs than on the [initial configuration](../../installation/packaged/#step-3-apache2-web-server-and-ssl-termination) guide. This assumes that you select the **install** option when the **server/autoinstall** dialog appears, and that you have certificate and key files available on your server at a known path.
## Docker-based installation
The current Docker image does not support SSL by default. Usually you would
already have an existing Apache or NginX server on your host, with SSL
configured, which you could use to set up a simple ProxyPass rule to direct
traffic to the container. Or one of the myriad of other tools (e.g. Traefik) offered by the Docker community to handle this aspect.
The current Docker image does not use SSL by default. Usually you would already have an existing Apache or NginX server (container) on your host, with SSL configured, which you could use to set up a simple ProxyPass rule to direct traffic to the container. Or one of the myriad of other tools (e.g. Traefik) offered by the Docker community to handle this aspect.
If you really want to enable SSL from within the container, you could try
mounting a custom apache2 directory when you launch the container with `-v
my/apache2/conf:/etc/apache2`. This would entirely replace the configuration
we're using.
If you really want to enable SSL from within the container, you could try mounting a custom apache2 directory when you launch the container with `-v
my/apache2/conf:/etc/apache2`. This would entirely replace the configuration we're using.
## Create a free SSL certificate using let's encrypt
@ -38,7 +33,9 @@ This requires your OpenProject server to be reachable using a domain name (e.g.
2. Follow the installation instructions to get the `certbot` CLI installed.
3. Run the `certbot` CLI to generate the certificate (and only the certificate):
sudo certbot certonly --apache
```bash
sudo certbot certonly --apache
```
The CLI will ask for a few details and to agree to the Let's Encrypt terms of usage. Then it will perform the Let's Encrypt challenge and finally issue a certificate file and a private key file if the challenge succeeded.
@ -54,7 +51,9 @@ This requires your OpenProject server to be reachable using a domain name (e.g.
4. Let's Encrypt certificates are only valid for 90 days. An entry in your OS crontab should have automatically been added when `certbot` was installed. You can optionally confirm that the renewal will work by issuing the following command in dry-run mode:
sudo certbot renew --dry-run
```bash
sudo certbot renew --dry-run
```
## External SSL termination
@ -78,7 +77,7 @@ If you're terminating SSL on the outer server, you need to set the `X-Forwarded-
Finally, to let OpenProject know that it should create links with 'https' when no request is available (for example, when sending emails), you need to set the Protocol setting of OpenProject to `https`. You can set this configuration by setting the ENV `OPENPROJECT_HTTPS=true`.
Finally, to let OpenProject know that it should create links with 'https' when no request is available (for example, when sending emails), you need to set the Protocol setting of OpenProject to `https`. You can set this configuration by setting the ENV `OPENPROJECT_HTTPS="true"`.
_<sup>1</sup> In the packaged installation this means you selected "no" when asked for SSL in the configuration wizard but at the same time take care of SSL termination elsewhere. This can be a manual Apache setup on the same server (not recommended) or an external server, for instance._
[Docker](https://www.docker.com/) is a way to distribute self-contained applications easily. We
provide a Docker image for the Community Edition that you can very easily
install and upgrade on your servers. However, contrary to the manual or
package-based installation, your machine needs to have the Docker Engine
installed first, which usually requires a recent operating system. Please see
the [Docker Engine installation page](https://docs.docker.com/install) if you don't have Docker
installed.
[Docker](https://www.docker.com/) is a way to distribute self-contained applications easily. We provide a Docker image for the Community Edition that you can very easily
install and upgrade on your servers. However, contrary to the manual or package-based installation, your machine needs to have the Docker Engine
installed first, which usually requires a recent operating system. Please see the [Docker Engine installation page](https://docs.docker.com/install) if you don't have Docker installed.
OpenProject with Docker can be launched in two ways:
@ -50,7 +46,7 @@ OPENPROJECT_HTTPS=false docker-compose up -d
After a while, OpenProject should be up and running on `http://localhost:8080`. The default username and password is login: `admin`, and password: `admin`. You need to explicitly disable HTTPS mode on startup as OpenProject assumes it's running behind HTTPS in production by default.
Note that the `docker-compose.yml` file present in the repository can be adjusted to your convenience. With each pull it will be overwritten. Best practice is to use the file `docker-compose.override.yml` for that case. For instance you could mount specific configuration files, override environment variables, or switch off services you don't need. Please refer to the official [Docker Compose documentation](https://docs.docker.com/compose/extends/) for more details.
> **Note:** The `docker-compose.yml` file present in the repository can be adjusted to your convenience. With each pull it will be overwritten. Best practice is to use the file `docker-compose.override.yml` for that case. For instance you could mount specific configuration files, override environment variables, or switch off services you don't need. Please refer to the official [Docker Compose documentation](https://docs.docker.com/compose/extends/) for more details.
You can stop the Compose stack by running:
@ -71,27 +67,12 @@ If you want to start from scratch and remove the existing data you will have to
### Configuration
In the compose folder you will find the file `docker-compose.yml` which can be edited.
Although we recommend using `docker-compose.override.yml`.
Please be aware that only those variables shall be edited which are documented as not everything is meant to be configured or bend.
Please see the [advanced configuration guide's docker paragraphs](../configuration#docker)
#### BIM Edition
In order to install or change to BIM inside a Docker environment, please navigate to the [Docker Installation for OpenProject BIM](../../bim-edition/#docker-installation-openproject-bim) paragraph at the BIM edition documentation.
### Disabling services in the docker-compose file
If you have an override file created, it is also easy to disable certain services, such as the database container if you have an external one running anyway.
To do that, add this section to the file:
```yaml
services:
db:
deploy:
replicas: 0
```
## All-in-one container
### Quick Start
@ -194,121 +175,16 @@ docker stop openproject
docker rm openproject
```
### Initial configuration
OpenProject is usually configured through a YAML file, but with the Docker
image you need to pass all configuration through environment variables. You can
overwrite any of the values usually found in the standard YAML file by using
Environment variables can be either passed directly on the command-line to the
Docker Engine, or via an environment file:
```bash
docker run -d -e KEY1=VALUE1 -e KEY2=VALUE2 ...
# or
docker run -d --env-file path/to/file ...
```
#### Docker-compose setup
For the docker-compose setup, we recommend you copy the upstream docker-compose.yml and adjust it to your needs. Please observe any changes when updating to the latest versions.
To add an environment variable manually to the docker-compose file, add it to the `environment:` section of the `op-x-app` definition like in the following example:
# set to true to enable the email receiving feature. See ./docker/cron for more options
IMAP_ENABLED: "${IMAP_ENABLED:-false}"
volumes:
- "${OPDATA:-opdata}:/var/openproject/assets"
# configuration cut off at this point.
# Please use the file at https://github.com/opf/openproject-deploy/blob/stable/12/compose/docker-compose.yml
```
Alternatively, you can also use an env file for docker-compose like so:
First, add a `.env` file with some variable:
```
OPENPROJECT_HTTPS=true
```
And then you'll need to pass the environment variable to the respective containers you want to set it on. For most OpenProject environment variables, this will be for `x-op-app`:
```yaml
version: "3.7"
networks:
frontend:
backend:
volumes:
pgdata:
opdata:
x-op-restart-policy: &restart_policy
restart: unless-stopped
x-op-image: &image
image: openproject/community:${TAG:-12}
x-op-app: &app
<<:[*image,*restart_policy]
environment:
OPENPROJECT_HTTPS: ${OPENPROJECT_HTTPS}
# ... more environment variables
# configuration cut off at this point.
# Please use the file at https://github.com/opf/openproject-deploy/blob/stable/12/compose/docker-compose.yml
```
Let's say you have a `.env.prod` file with some production-specific configuration. Then, start the services with that special env file specified.
```
docker-compose --env-file .env.prod up
```
### Configuration
Please see the [advanced configuration guide's docker paragraphs](../configuration#docker)
#### Disabling HTTPS mode
By default, OpenProject will expect a HTTPS request in production systems.
In most cases, you will have an external web server or load balancer terminating the SSL/TLS connection and proxy/reverse-proxy to the docker container. You will then have to set up the web server to forward the protocol information (usually, this is `X-Forwarded-Proto` but depends on your web server).
**Note**: This does not imply the docker container itself is running on SSL.
> **NOTE**: This does not imply the docker container itself is running on SSL.
If you _really_ want to disable HTTPS responses by OpenProject, you will need to add the environment variable `OPENPROJECT_HTTPS=false`. Note that this will disable secure cookies for session cookies, and is strongly discouraged for any production system.
@ -356,7 +232,7 @@ described above.
Assuming the desired *server name* is `openproject.example.com` the configuration
will look like this:
> **Note:** There is [another example](../packaged/#external-ssltls-termination) for external SSL/TLS termination for **packaged** installations
> **NOTE:** There is [another example](../packaged/#external-ssltls-termination) for external SSL/TLS termination for **packaged** installations
```
<VirtualHost*:80>
@ -677,7 +553,7 @@ x-op-app: &app
Any additional configuration of OpenProject happens in the environment section (like for S3 above) of the app inside of the `openproject-stack.yml`.
For instance should you want to disable an OpenProject module globally, you would add the following:
```
```yaml
x-op-app: &app
<<:*image
<<:*restart_policy
@ -694,13 +570,13 @@ on what you can configure and how.
Once you made any necessary adjustments to the `openproject-stack.yml` you are ready to launch the stack.
Then finish the installation by reading the [*Initial configuration*](#initial-configuration) section.
**Note:** On this distribution full-text extraction for attachments [*is not supported*](#full-text-extraction-not-supported) by default.
> **Note:** On this distribution full-text extraction for attachments [*is not supported*](#full-text-extraction-not-supported) by default.
>
### CentOS 7 / RHEL 7
@ -370,11 +371,12 @@ sudo openproject reconfigure #interactive - manual choices are stored in /etc/op
sudo openproject configure #non-interactive - using values stored in /etc/openproject/installer.dat
```
**Notes:**
* Every time you will run the OpenProject wizard, by using `sudo openproject reconfigure` your choices will be persisted in a configuration file at `/etc/openproject/installer.dat` and subsequent executions of `sudo openproject configure` will re-use these values, only showing you the wizard steps for options you have not yet been asked for.
* In the interactive way you can skip dialogs you do not want to change simply by confirming them with `ENTER`.
> **Notes:**
>
> * Every time you will run the OpenProject wizard, by using `sudo openproject reconfigure` your choices will be persisted in a configuration file at `/etc/openproject/installer.dat` and subsequent executions of `sudo openproject configure` will re-use these values, only showing you the wizard steps for options you have not yet been asked for.
>
> * In the interactive way you can skip dialogs you do not want to change simply by confirming them with `ENTER`.
This guide covers all of OpenProject's functionalities.
This guide covers all of OpenProject's functionalities from a user's perspective.
## Overview of projects in OpenProject
@ -24,7 +22,7 @@ Both the community edition and enterprise edition allow you to create an unlimit
<divclass="glossary">
**Module** is defined as an independent unit of functionality that can be used to extend and improve the existing core functions.</div>
Within a project Modules can be activated and deactivated under "Modules" in the project settings menu by project members who have sufficient permissions to adjust project settings. Which modules will be available within projects is controlled in the global Administration settings (please see [System admin guide](.../system-admin-guide/system-settings/project-system-settings/) to see how this is done.)
Within a project Modules can be activated and deactivated under "Modules" in the project settings menu by project members who have sufficient permissions to adjust project settings. Which modules will be available within projects is controlled in the global Administration settings (please see [System admin guide](.../system-admin-guide/system-settings/project-system-settings/) to see how this is done).
Please choose the module or topic you want to learn more about.
@ -38,7 +36,7 @@ Please choose the module or topic you want to learn more about.
| [Calendar](calendar) | How to display your work in a calendar in OpenProject. |
| [Documents](documents) | How to upload and share documents in OpenProject. |
| [Forums](forums) | How to manage forums to discuss and comment on topics. |
| [GitHub](../system-admin-guide/integrations/github-integration/) | How to manage GitHub integration. |
| [GitHub](../system-admin-guide/integrations/github-integration/) | How to manage the GitHub integration. |
| [Meetings](meetings) | How to manage meetings to create and share meeting agenda and meeting minutes. |
| [News](news) | How to create and manage News for your projects. |
| [Using the Nextcloud integration](nextcloud-integration) | How to link and use Nextcloud files and folders in OpenProject |
Oliver Günther
2 years ago