Fix installation and ops guides

docker-compose.yml

@@ -12,7 +12,7 @@ x-op-restart-policy: &restart_policy
   restart: unless-stopped
 x-op-image: &image
   build: .
-  image: openproject/community:${TAG:-10-test}
+  image: openproject/community:${TAG:-10}
 x-op-app: &app
   <<: *image
   <<: *restart_policy

docs/installation-and-operations/README.md

@@ -1,4 +1,4 @@
-# Installation and Operation Guides
+# Installation and Operations Guides
 
 This section concerns the installation and operation of OpenProject (Community and Enterprise editions).
 
@@ -8,7 +8,7 @@ This section concerns the installation and operation of OpenProject (Community a
 | ----------- | :---------- |
 | [System requirements](system-requirements) | Learn the minimum configuration required to run OpenProject |
 | [Installation](installation/) | How to install OpenProject |
-| [Operation & Maintenance](operation/) | Guides on how to configure, backup, upgrade, and monitor your OpenProject installation |
+| [Operations & Maintenance](operation/) | Guides on how to configure, backup, upgrade, and monitor your OpenProject installation |
 | [Advanced configuration](configuration/) | Guides on how to perform advanced configuration of your OpenProject installation |
 | [Other](misc/) | Guides on infrequent operations such as MySQL to PostgreSQL migration |
 

docs/installation-and-operations/configuration/ssl/README.md

@@ -14,16 +14,14 @@ SSL configuration can be applied on the first installation, or at any time by re
 sudo openproject reconfigure
 ```
 
-You will be prompted with the same dialogs than on the [initial configuration](#TODO) 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.
-
-[initial_configuration]: ../installation/packaged/#install-apache2-web-server-default
+You will be prompted with the same dialogs than on the [initial configuration](../../installation/packaged/#step-2-apache2-web-server) 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.
 
 ## 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.
+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

docs/installation-and-operations/installation/README.md

@@ -10,8 +10,7 @@ OpenProject can be setup in three different ways:
 
 | ----------- | :---------- |
 | [Installation with DEB/RPM packages](./packaged) | This is the recommended way to install OpenProject |
-| [Installation with docker](./docker) | This method of installation will undergo some changes soon and is currently not recommended |
+| [Installation with docker](./docker) | This allows to setup OpenProject in an isolated manner using Docker |
 | [Installation with Univention Corporate Server](./univention) | OpenProject is available in the App Center and comes integrated with the identity management |
 
 **We recommend downloading the DEB/RPM package installation.**
-

docs/installation-and-operations/installation/docker/README.md

@@ -35,10 +35,16 @@ Then, go into the OpenProject folder and you can launch all the services require
 docker-compose up -d
 ```
 
-After some time, you will be able to access OpenProject on http://localhost:8080.
+After some time, you will be able to access OpenProject on http://localhost:8080. The default username and password is login: `admin`, and password: `admin`.
 
 Note that the official `docker-compose.yml` file present in the repository can be adjusted to your convenience. 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 for more details.
 
+You can stop the Compose stack by running:
+
+```
+docker-compose down
+```
+
 ## All-in-one container
 
 ### Quick Start
@@ -127,5 +133,3 @@ docker run -d --env-file path/to/file ...
 ```
 
 For more advanced configuration, please have a look at the [Advanced configuration](../../configuration) section.
-
-

docs/installation-and-operations/installation/packaged/README.md

@@ -42,7 +42,11 @@ $ uname -i
 x86_64
 ```
 
-Also, please note that the packaged installation works best when running on a dedicated server or virtual machine, as we cannot ensure that the components installed and configured by the OpenProject installer will work on systems that have been already customized.
+<div class="alert alert-info" role="alert">
+
+**Important note:** Please note that the packaged installation works best when running on a dedicated server or virtual machine, as we cannot ensure that the components installed and configured by the OpenProject installer will work on systems that have been already customized. If you must install OpenProject on a server where other software is running, or with an already configured Apache or NginX server, then you should have a look at the Docker-based installation instead.
+
+</div>
 
 ## Ubuntu 18.04
 
@@ -206,7 +210,7 @@ sudo openproject configure
 
 The first dialog in the wizard allows you to choose an option for the PostgreSQL database connection: 
 
-![01-postgres](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/01-postgres.png?raw=true)
+![01-postgres](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/01-postgres.png)
 
 The dialog allows you to choose from three options:
 
@@ -236,7 +240,7 @@ OpenProject comes with an internal ruby application server, but this server only
 
 This wizard step allows you to auto-install an Apache2 web server to function as that proxy.
 
-![02a-apache](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02a-apache.png?raw=true)
+![02a-apache](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/02a-apache.png)
 
 The available options are:
 
@@ -250,13 +254,13 @@ In case you select to auto-install Apache2, multiple dialogs will request the pa
 
 Enter the fully qualified domain where your OpenProject installation will be reached at. This will become the `ServerName` of your apache VirtualHost and is also used to generate full links from OpenProject, such as in emails.
 
-![02b-hostname](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02b-hostname.png?raw=true)
+![02b-hostname](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/02b-hostname.png)
 
 **Server path prefix**
 
 If you wish to install OpenProject under a server path prefix, such as `yourdomain.example.com/openproject`, please specify that prefix here with a leading slash. For example: `/openproject`. If OpenProject should respond to `http(s)://yourdomain.example.com` as specified in the previous dialog, simply leave this dialog empty and confirm by pressing `ENTER`.
 
-![02c-prefix](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02c-prefix.png?raw=true)
+![02c-prefix](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/02c-prefix.png)
 
 **SSL/TLS configuration**
 
@@ -268,7 +272,7 @@ In that case, you will be shown three additional dialogs to enter the certificat
 2. The absolute SSL private key path
 3. The path to the Certificate Authority bundle for the certificate (optional, leave empty unless needed)
 
-![02d-ssl](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/02d-ssl.png?raw=true)
+![02d-ssl](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/02d-ssl.png)
 
 
 ### **Skip** (not recommended)
@@ -285,13 +289,13 @@ If you have selected to auto-install an Apache2 web server, you will be asked wh
 
 For more information, [see our help on repositories](https://www.openproject.org/help/repository/)
 
-![03-repos](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/03-repos.png?raw=true)
+![03-repos](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/03-repos.png)
 
 ## Step 4: Outgoing email configuration
 
 OpenProject requires a setup for sending outgoing emails for notifications, such as updates on work packages, password resets, or other notifications you and your users receive.
 
-![04-mail](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/04-mail.png?raw=true)
+![04-mail](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/04-mail.png)
 
 The wizard supports the following options:
 
@@ -313,13 +317,13 @@ Does not set up mail configuration. You can configure the mail setup in OpenProj
 
 The wizard will ask you for an administrative email address so that it can create the administrator account with that email for the initial login. Enter your email address to have it tied to the admin account.
 
-![05-admin](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/05-admin.png?raw=true)
+![05-admin](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/05-admin.png)
 
 ## Step 6: Memcached server
 
 OpenProject heavily relies on caching, which is why the wizard suggests you to install a local memcached server the OpenProject instances can connect to. You should always set this to `install` unless you have a reason to configure another caching mechanism - for example when configuring multiple shared instances of OpenProject.
 
-![06-cache](https://github.com/opf/openproject/blob/dev/docs/installation/packaged/screenshots/06-cache.png?raw=true)
+![06-cache](https://github.com/opf/openproject/raw/dev/docs/installation-and-operations/installation/packaged/06-cache.png)
 
 ## Result
 

docs/installation-and-operations/misc/docker-postgresql-migration/README.md

@@ -1,29 +1,21 @@
 # Migrating your Docker OpenProject database to PostgreSQL
 
-TODO: review
-
-This guide will migrate your docker-based MySQL installation to a PostgreSQL installation using [pgloader](https://github.com/dimitri/pgloader). 
+This guide will migrate your all-in-one docker-based MySQL installation to a PostgreSQL installation using [pgloader](https://github.com/dimitri/pgloader). 
 
 ## Backing up
 
-Before beginning the migration, please ensure you have created a backup of your current installation. Please follow our [backup and restore documentation](https://www.openproject.org/operations/backup/backup-guide-docker-installation/) for Docker-based installations.
-
-
+Before beginning the migration, please ensure you have created a backup of your current installation. Please follow our [backup and restore guides](../../operation) for Docker-based installations.
 
 ## Built-in migration script
 
 The Dockerfile comes with a built-in PostgreSQL migration script that will auto-run and inform you what to do.
 
-
-
 ### Set up a PostgreSQL database
 
 Depending on your usage, you may want to set up an external PostgreSQL database to provide the container with connection details just like you did for MySQL.
 
 In any case, you may also use the internally configured PostgreSQL instance of the docker container by using the DATABASE_URL ` postgres://openproject:openproject@127.0.0.1/openproject`
 
-
-
 **Installing a PostgreSQL database outside docker**
 
 If you want to set up a PostgreSQL installation database outside the container and not use the built-in database, please set up a PostgreSQL database now. These are generic apt-based installation steps, please adapt them appropriately for your distribution.
@@ -112,5 +104,4 @@ docker run -it \
 ```
 
 
-
 This will perform all necessary steps to perform the migration. Afterwards, simply remove the `MYSQL_DATABASE_URL`environment variable again and start your container as usual.

docs/installation-and-operations/misc/migration/README.md

@@ -1,14 +1,12 @@
 # Migrating your packaged OpenProject installation to another environment
 
-TODO: review
-
 **Note:** this guide only applies if you've installed OpenProject using our DEB/RPM packages.
 
 Migrating your OpenProject packaged installation to another host or environment is trivial and may be combined with, e.g., minor or major package upgrades due to our migration system.
 
 ## Backing up
 
-To create a dump of all your data in the old installation, please follow our [backup and restore documentation](https://www.openproject.org/operations/backup/backup-guide-packaged-installation/) for our packaged installation.
+To create a dump of all your data in the old installation, please follow our [backup and restore guides](../../operation) for our packaged installation.
 
 This guide should leave you with a set of archives that you should manually move to your new environment:
 
@@ -17,8 +15,6 @@ This guide should leave you with a set of archives that you should manually move
 - **Custom env configuration**: conf-\<timestamp>.tar.gz
 - **Repositories**: svn- and git-\<timestamp>.tar.gz
 
-
-
 ## Migration
 
 The following steps outline the migration process to the OpenProject package (possibly, a newer version).

docs/installation-and-operations/misc/packaged-postgresql-migration/README.md

@@ -1,14 +1,12 @@
 # Migrating your packaged OpenProject database to PostgreSQL
 
-TODO: review
-
 **Note:** this guide only applies if you've installed OpenProject using our DEB/RPM packages.
 
 This guide will migrate your packaged MySQL installation to a PostgreSQL installation using [pgloader](https://github.com/dimitri/pgloader). 
 
 ## Backing up
 
-Before beginning the migration, please ensure you have created a backup of your current installation. Please follow our [backup and restore documentation](https://www.openproject.org/operations/backup/backup-guide-packaged-installation/) for our packaged installation.
+Before beginning the migration, please ensure you have created a backup of your current installation. Please follow our [backup and restore guides](../../operation).
 
 This guide should leave you with a set of archives that you can use to restore, should the migration end up in an unstable state:
 

docs/installation-and-operations/misc/upgrading-older-openproject-versions/README.md

@@ -1,6 +1,6 @@
-### Migrating from an old MySQL database
+# Migrating from an old MySQL database
 
-The script described above reuqires at least OpenProject 8 to work properly. If you are still on an older OpenProject version you have to migrate to OpenProject 8 first.
+The script described above requires at least OpenProject 8 to work properly. If you are still on an older OpenProject version you have to migrate to OpenProject 8 first.
 
 To make this easier there is a script which automates that too. It's included in the docker image itself but will want to run it directly on the docker host. To do that you can either copy it onto your system from `/app/script/migration/migrate-from-pre-8.sh` or simply download it [here](https://github.com/opf/openproject/tree/release/10.3/script/migration/migrate-from-pre-8.sh).
 
@@ -13,4 +13,3 @@ With docker installed, use the following command to start the upgrade process on
 ```bash
 bash migrate-from-pre-8.sh <docker host IP> <MySQL dump>"
 ```
-

docs/installation-and-operations/operation/backing-up/README.md

@@ -52,7 +52,7 @@ You should then copy those dump files to a secure location, for instance an S3 b
 
 ## Docker-based installation
 
-If you are using docker-compose, then the data volumes are managed by Docker and you should have a look at https://docs.docker.com/storage/volumes/ for instructions on how to backup.
+If you are using docker-compose, then the data volumes are managed by Docker and you should have a look at the [official Docker documentation](https://docs.docker.com/storage/volumes/) for instructions on how to backup.
 
 If you are using the all-in-one container, then you can simply backup any local volumes that you chose to bind-mount with the `-v` option when launching the container. For instance if you launched the container with:
 

docs/installation-and-operations/operation/control/README.md

@@ -44,8 +44,6 @@ sudo openproject run ruby -v
 
 ## Scaling the number of web workers
 
-TODO: review
-
 Note: Depending on your free RAM on your system, we recommend you raise the default number of web processes. The default from 9.0.3 onwards is 4 web processes. Each worker will take roughly 300-400MB RAM.
 
 We recommend at least 4 web processes. Please check your current web processes count with:
@@ -62,4 +60,8 @@ sudo openproject config:set OPENPROJECT_WEB_WORKERS=number
 
 Where `number` is a positive number between 1 and `round(AVAILABLE_RAM * 1.5)`.
 
-After changing these values, call `sudo openproject configure` to apply it to the web server.
+After changing these values, simply restart the web process:
+
+```bash
+sudo openproject restart web
+```