From 6fbcb42d62650be83eb35d8a9f9c9942e0642e23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20G=C3=BCnther?= Date: Mon, 21 Oct 2019 16:03:35 +0200 Subject: [PATCH] Add ordering to installation docs --- .../docker/README.md | 6 + .../docker/backup.md | 6 + .../docker/installation.md | 165 ++++++++++++++++++ .../docker/upgrading.md | 6 + .../manual/README.md | 6 + .../packaged/README.md | 7 + .../packaged/backup.md | 15 +- .../packaged/installation.md | 6 + .../packaged/upgrading.md | 14 +- 9 files changed, 227 insertions(+), 4 deletions(-) create mode 100644 help/installation-and-operations/docker/installation.md diff --git a/help/installation-and-operations/docker/README.md b/help/installation-and-operations/docker/README.md index ba459d8218..efe83308e2 100644 --- a/help/installation-and-operations/docker/README.md +++ b/help/installation-and-operations/docker/README.md @@ -1,3 +1,9 @@ +--- +nav: + title: Docker installation + priority: 200 +--- + # Docker installation TODO diff --git a/help/installation-and-operations/docker/backup.md b/help/installation-and-operations/docker/backup.md index a47bb0518c..49174d531d 100644 --- a/help/installation-and-operations/docker/backup.md +++ b/help/installation-and-operations/docker/backup.md @@ -1,3 +1,9 @@ +--- +nav: + title: Backup guide + priority: 100 +--- + # Backup your OpenProject installation (Docker) Note: this guide only applies if you've installed OpenProject with our Docker image. diff --git a/help/installation-and-operations/docker/installation.md b/help/installation-and-operations/docker/installation.md new file mode 100644 index 0000000000..c4062039bb --- /dev/null +++ b/help/installation-and-operations/docker/installation.md @@ -0,0 +1,165 @@ +--- +nav: + title: Installation guide + priority: 300 +--- + +# Install OpenProject with Docker + +[Docker][docker] 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][docker-install] if you don't have Docker +installed. + +Also, please note that the Docker image is quite new and might not support all +the options that the package-based or manual installation provides. + +[docker]: https://www.docker.com/ +[docker-install]: https://docs.docker.com/engine/installation/ + +### Quick Start + +The fastest way to get an OpenProject instance up and running is to run the +following command: + + docker run -it -p 8080:80 -e SECRET_KEY_BASE=secret openproject/community:8 + +This will take a bit of time the first time you launch it, but after a few +minutes you should see a success message indicating the default administration +password (login: `admin`, password: `admin`). + +You can then launch a browser and access your new OpenProject installation at +. Easy! + +To stop the container, simply hit CTRL-C. + +Note that the above command will not daemonize the container and will display +the logs to your terminal, which helps with debugging if anything goes wrong. +For normal usage you probably want to start it in the background, which can be +achieved with the `-d` flag: + + docker run -d -p 8080:80 -e SECRET_KEY_BASE=secret openproject/community:8 + +# Recommended usage + +The one-liner above is great to get started quickly, but if you want to run +OpenProject in production you will likely want to ensure that your data is not +lost if you restart the container. + +To achieve this, we recommend that you create a directory on your host system +where the Docker Engine is installed (for instance: `/var/lib/openproject`) +where all this data will be stored. + +You can use the following commands to create the local directories where the +data will be stored across container restarts, and start the container with +those directories mounted: + + sudo mkdir -p /var/lib/openproject/{pgdata,static} + + docker run -d -p 8080:80 --name openproject -e SECRET_KEY_BASE=secret \ + -v /var/lib/openproject/pgdata:/var/openproject/pgdata \ + -v /var/lib/openproject/static:/var/openproject/assets \ + openproject/community:8 + +Since we named the container, you can now stop it by running: + + docker stop openproject + +And start it again: + + docker start openproject + +If you want to destroy the container, run the following commands + + docker stop openproject && docker rm openproject + +# 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 as explained in the [CONFIGURATION][configuration-doc] +documentation. + +Environment variables can be either passed directly on the command-line to the +Docker Engine, or via an environment file: + + docker run -d -e KEY1=VALUE1 -e KEY2=VALUE2 ... + docker run -d --env-file path/to/file ... + +[configuration-doc]: https://github.com/opf/openproject/blob/dev/docs/configuration/configuration.md + +# SMTP configuration + +By default, the docker container will try to send emails via the local +`postfix` daemon. However emails sent this way are more than likely to fail or +end up in the spam inbox of your users. We recommend using an external SMTP +server to send your emails. + +A good choice is [SendGrid](https://www.sendgrid.com/), which offers a free plan +with up to 12000 emails per month. Just sign up on the website, and once your +account is provisioned, generate a new API key and copy it somewhere (it looks +like `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`). +You can also just use your SendGrid username and password, but this is less +secure. + +You can then configure OpenProject with the following additonal environment +variables (with SendGrid, the `SMTP_USER_NAME` is always `apikey`. Just replace +`SMTP_PASSWORD` with the API key you've generated and you should be good to +go): + + docker run -d \ + -e EMAIL_DELIVERY_METHOD=smtp \ + -e SMTP_ADDRESS=smtp.sendgrid.net \ + -e SMTP_PORT=587 \ + -e SMTP_DOMAIN=my.domain.com \ + -e SMTP_AUTHENTICATION=login \ + -e SMTP_ENABLE_STARTTLS_AUTO=true \ + -e SMTP_USER_NAME="apikey" \ + -e SMTP_PASSWORD="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" \ + ... + +You can adjust those settings for other SMTP providers, such as GMail, +Mandrill, etc. Please refer to the documentation of the corresponding provider +to see what values should be used. + +# FAQ + +* Can I use SSL? + +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. + +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. + + +* Can I use an external (MySQL or PostgreSQL) database? + +Yes. You can simply pass a custom `DATABASE_URL` environment variable on the +command-line, which could point to an external database. You can even choose to +use MySQL instead of PostgreSQL if you wish. Here is how you would do it: + + docker run -d ... -e DATABASE_URL=mysql2://user:pass@host:port/dbname openproject/community:8 + +The container will make sure that the database gets the migrations and demo +data as well. + +* I don't want the all-in-one installation. Can I still use the image to launch a specific process? + +Yes, you can do so by passing a command when you launch the container. By default the container will run `./docker/supervisord`, but you can override this with `./docker/web`, `./docker/worker`, `./docker/cron` to launch the individual services separately (e.g. in a docker-compose file). Please note that in this configuration you will have to setup the external services (postgres, memcached, email sending) by yourself. + +Example: + + docker run -d -e DATABASE_URL=xxx ... openproject/community:8 ./docker/web + docker run -d -e DATABASE_URL=xxx ... openproject/community:8 ./docker/worker + + + diff --git a/help/installation-and-operations/docker/upgrading.md b/help/installation-and-operations/docker/upgrading.md index cf6bde939b..5915664edc 100644 --- a/help/installation-and-operations/docker/upgrading.md +++ b/help/installation-and-operations/docker/upgrading.md @@ -1,3 +1,9 @@ +--- +nav: + title: Upgrade guide + priority: 200 +--- + # Upgrade your OpenProject installation (Docker) Upgrading a Docker container is easy. First, pull the latest version of the image: diff --git a/help/installation-and-operations/manual/README.md b/help/installation-and-operations/manual/README.md index a0b600ea59..6ce2bc1d98 100644 --- a/help/installation-and-operations/manual/README.md +++ b/help/installation-and-operations/manual/README.md @@ -1,3 +1,9 @@ +--- +nav: + title: Manual installation + priority: 100 +--- + # Manual installation TODO diff --git a/help/installation-and-operations/packaged/README.md b/help/installation-and-operations/packaged/README.md index 2566bf9fc8..dccc9f91d8 100644 --- a/help/installation-and-operations/packaged/README.md +++ b/help/installation-and-operations/packaged/README.md @@ -1,3 +1,10 @@ +--- +nav: + title: Packaged installation + priority: 300 +--- + + # Packaged installation TODO diff --git a/help/installation-and-operations/packaged/backup.md b/help/installation-and-operations/packaged/backup.md index b1e0261b3a..ab5a6677fa 100644 --- a/help/installation-and-operations/packaged/backup.md +++ b/help/installation-and-operations/packaged/backup.md @@ -1,6 +1,17 @@ -# Backup your OpenProject installation +--- +nav: + title: Backup Guide + priority: 50 +--- -**Note:** this guide only applies if you've installed OpenProject using our DEB/RPM packages. +# Packaged installation backup guide + + We advise to backup your OpenProject installation regularly — especially before upgrading to a newer version. diff --git a/help/installation-and-operations/packaged/installation.md b/help/installation-and-operations/packaged/installation.md index 39b76bb426..feb43b15f5 100644 --- a/help/installation-and-operations/packaged/installation.md +++ b/help/installation-and-operations/packaged/installation.md @@ -1,3 +1,9 @@ +--- +nav: + title: Installation Guide + priority: 200 +--- + # Packaged Installation Guide The packaged installation of OpenProject is the easiest way to install and maintain OpenProject, provided a supported distribution exists and you can allocate an isolated server for OpenProject. The package will: diff --git a/help/installation-and-operations/packaged/upgrading.md b/help/installation-and-operations/packaged/upgrading.md index e534f04d27..13f1a170ef 100644 --- a/help/installation-and-operations/packaged/upgrading.md +++ b/help/installation-and-operations/packaged/upgrading.md @@ -1,7 +1,17 @@ -# Upgrading your OpenProject installation +--- +nav: + title: Upgrade Guide + priority: 100 +--- + +# Upgrading your packaged installation + + Upgrading OpenProject is as easy as installing a newer OpenProject package and running the `openproject configure` command.