Add ordering to installation docs

pull/7908/head
Oliver Günther 5 years ago
parent 2ef8170c7f
commit 6fbcb42d62
No known key found for this signature in database
GPG Key ID: A3A8BDAD7C0C552C
  1. 6
      help/installation-and-operations/docker/README.md
  2. 6
      help/installation-and-operations/docker/backup.md
  3. 165
      help/installation-and-operations/docker/installation.md
  4. 6
      help/installation-and-operations/docker/upgrading.md
  5. 6
      help/installation-and-operations/manual/README.md
  6. 7
      help/installation-and-operations/packaged/README.md
  7. 15
      help/installation-and-operations/packaged/backup.md
  8. 6
      help/installation-and-operations/packaged/installation.md
  9. 14
      help/installation-and-operations/packaged/upgrading.md

@ -1,3 +1,9 @@
---
nav:
title: Docker installation
priority: 200
---
# Docker installation
TODO

@ -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.

@ -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
<http://localhost:8080>. 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

@ -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:

@ -1,3 +1,9 @@
---
nav:
title: Manual installation
priority: 100
---
# Manual installation
TODO

@ -1,3 +1,10 @@
---
nav:
title: Packaged installation
priority: 300
---
# Packaged installation
TODO

@ -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
<div class="alert alert-info" role="alert">
Note: this guide only applies if you've installed OpenProject using our DEB/RPM
packages. [Please see the index](../) for guides on other installation methods.
</div>
We advise to backup your OpenProject installation regularly — especially before upgrading to a newer version.

@ -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:

@ -1,7 +1,17 @@
# Upgrading your OpenProject installation
---
nav:
title: Upgrade Guide
priority: 100
---
# Upgrading your packaged installation
<div class="alert alert-info" role="alert">
Note: this guide only applies if you've installed OpenProject using our DEB/RPM
packages.
packages. [Please see the index](../) for guides on other installation methods.
</div>
Upgrading OpenProject is as easy as installing a newer OpenProject package and
running the `openproject configure` command.

Loading…
Cancel
Save