Merge pull request #2801 from kgalli/feature/update-operation-guildes
Feature/update operation guildespull/2771/merge
jonasheinrich
10 years ago
commit
a7b7df4329
@ -0,0 +1,158 @@ |
|||||||
|
# Backup Guide |
||||||
|
|
||||||
|
We advice to backup your OpenProject installation regularly — especially |
||||||
|
before upgrading to a newer version. |
||||||
|
|
||||||
|
## Backup the Database |
||||||
|
|
||||||
|
###OpenProject Version 3.0.15 and newer |
||||||
|
|
||||||
|
Execute the following command in a shell in the directory where |
||||||
|
OpenProject is installed: |
||||||
|
|
||||||
|
````bash |
||||||
|
RAILS_ENV=production bundle exec rake backup:database:create |
||||||
|
``` |
||||||
|
|
||||||
|
The command will create dump of your database which can be found at |
||||||
|
|
||||||
|
`OPENPROJECT_DIRECTORY/backup/openproject-production-db-<DATE>.sql` (for |
||||||
|
MySQL) or |
||||||
|
`OPENPROJECT_DIRECTORY/backup/openproject-production-db-<DATE>.backup` |
||||||
|
(for PostgreSQL). |
||||||
|
|
||||||
|
Optionally, you can specify the path of the backup file. Therefore |
||||||
|
you have to replace the `/path/to/file.backup` with the path of your |
||||||
|
choice |
||||||
|
|
||||||
|
```bash |
||||||
|
RAILS_ENV=production bundle exec rake backup:database:create[/path/to/backup/file.backup] |
||||||
|
``` |
||||||
|
*Note:* You can restore any database backup with the following |
||||||
|
command. Be aware that you have to replace the |
||||||
|
`/path/to/backup/file.backup` path with your actual backup path. |
||||||
|
|
||||||
|
```bash |
||||||
|
RAILS_ENV=production bundle exec rake backup:database:restore[/path/to/backup/file.backup] |
||||||
|
``` |
||||||
|
|
||||||
|
If your database dump is from an old version of OpenProject, also run |
||||||
|
the following command after the restore: |
||||||
|
|
||||||
|
```bash |
||||||
|
RAILS_ENV=production bundle exec rake db:migrate |
||||||
|
``` |
||||||
|
|
||||||
|
to migrate your data to the database structure of your installed |
||||||
|
OpenProject version. |
||||||
|
|
||||||
|
### OpenProject prior Version 3.0.15 |
||||||
|
|
||||||
|
Determine which Database you are using. You can find the relevant |
||||||
|
information in the `OPENPROJECT_DIRECTORY/config/database.yml` file. It |
||||||
|
looks similar to this: |
||||||
|
|
||||||
|
```yaml |
||||||
|
production: |
||||||
|
adapter: postgresql |
||||||
|
database: openproject-production |
||||||
|
host: localhost |
||||||
|
username: my_postgres_user |
||||||
|
password: my_secret_password |
||||||
|
encoding: utf8 |
||||||
|
min_messages: warning |
||||||
|
``` |
||||||
|
|
||||||
|
Locate the database entry for your production database. If your adapter |
||||||
|
is postgresql, then you have a PostgreSQL database. If it is mysql2, you |
||||||
|
use a MySQL database. Now follow the steps for your database adapter. |
||||||
|
|
||||||
|
#### PostgreSQL |
||||||
|
You can backup your PostgreSQL database with the `pg_dump` command and |
||||||
|
restore backups with the `pg_restore` command. (There might be other (and |
||||||
|
more convenient) tools, like pgAdmin, depending on your specific setup.) |
||||||
|
|
||||||
|
An example backup command with `pg_dump` looks like this: |
||||||
|
|
||||||
|
```bash |
||||||
|
pg_dump --clean --format=custom --no-owner --file=/path/to/your/backup/file.backup --username=POSTGRESQL_USER --host=HOST DATABASE_NAME |
||||||
|
``` |
||||||
|
|
||||||
|
Please, replace the path to your backup file, the username, host, and |
||||||
|
database name with your actual data. You can find all relevant |
||||||
|
information in the database.yml file. |
||||||
|
Consult the man page of `pg_dump` for more advanced parameters, if |
||||||
|
necessary. |
||||||
|
|
||||||
|
The database dump can be restored similarly with `pg_restore`: |
||||||
|
|
||||||
|
```bash |
||||||
|
pg_restore --clean --no-owner --single-transaction |
||||||
|
--dbname=DATABASE_NAME --host=HOST --username=POSTGRESQL_USER |
||||||
|
/path/to/your/backup/file.backup |
||||||
|
``` |
||||||
|
|
||||||
|
Consult the man page of `pg_restore` for more advanced parameters, if |
||||||
|
necessary. |
||||||
|
|
||||||
|
#### MySQL |
||||||
|
You can backup your MySQL database for example with the mysqldump |
||||||
|
command and restore backups with the mysql command line client. (There |
||||||
|
might be other (and more convenient) tools, like phpMyAdmin, adminer, or |
||||||
|
other tools, depending on your specific setup.) |
||||||
|
|
||||||
|
An example backup command with `mysqldump` looks like this: |
||||||
|
|
||||||
|
```bash |
||||||
|
mysqldump --single-transaction --add-drop-table --add-locks --result-file=/path/to/your/backup/file.sql --host=HOST --user=MYSQL_USER --password DATABASE_NAME |
||||||
|
``` |
||||||
|
|
||||||
|
Please, replace the path to your backup file, the MySQL username, host |
||||||
|
and database name with your actual data. You can find all relevant |
||||||
|
information in the `database.yml` file. |
||||||
|
Consult the man page of `mysqldump` for more advanced parameters, if |
||||||
|
necessary. |
||||||
|
|
||||||
|
The database dump can be restored similarly with `mysql` (on a \*nix |
||||||
|
compatible shell): |
||||||
|
|
||||||
|
```bash |
||||||
|
mysql --host=HOST --user=MYSQL_USER --password DATABASE_NAME < /path/to/your/backup/file.sql |
||||||
|
``` |
||||||
|
Consult the man page of mysql for more advanced parameters, if |
||||||
|
necessary. |
||||||
|
|
||||||
|
## Backup your Configuration Files |
||||||
|
Please make sure to create a backup copy of at least the following |
||||||
|
configuration files (all listed as a relative path from the OpenProject |
||||||
|
installation directory): |
||||||
|
|
||||||
|
`Gemfile.local` (if present) |
||||||
|
`Gemfile.plugins` (if present) |
||||||
|
`config/database.yml` (if present) |
||||||
|
`config/configuration.yml` (if present) |
||||||
|
`config/settings.yml` (if present) |
||||||
|
|
||||||
|
Some OpenProject options can be given as environment variables. If you |
||||||
|
have configured environment variables for OpenProject, consider to |
||||||
|
backup them too. |
||||||
|
|
||||||
|
## Backup Files Uploaded by Users (attachments) |
||||||
|
Files uploaded by users (e.g. when adding an attachment to a |
||||||
|
WorkPackage) are stored on the hard disk. |
||||||
|
The directory where those files are stored can be configured in the |
||||||
|
`config/configuration.yml` via the `attachments_storage_path` setting (or an |
||||||
|
appropriate environment variable). |
||||||
|
|
||||||
|
If you have not changed the `attachment_storage_path` setting, all files |
||||||
|
will be uploaded to the files directory (relative to your OpenProject |
||||||
|
installation). |
||||||
|
|
||||||
|
Make sure to backup this directory. |
||||||
|
|
||||||
|
## Backup Repositories |
||||||
|
You can manage Repositories with OpenProject — so one or more of your |
||||||
|
projects may have a repository. Please make sure to backup these too. |
||||||
|
The path to a project’s repository can be found in the repository |
||||||
|
settings of the respective project (it can be individually defined for |
||||||
|
every project). Each of the defined locations has to be backed up. |
||||||
@ -0,0 +1,152 @@ |
|||||||
|
# OpenProject 4.0 to OpenProject 4.1 Debian/Ubuntu Upgrade Guide |
||||||
|
|
||||||
|
This guide describes the upgrade process from OpenProject 4.0 to 4.1 on Debian 7.7 and |
||||||
|
Ubuntu 14.04 LTS step by step. |
||||||
|
|
||||||
|
Note: We strongly recommend to update your OpenProject installation to the latest |
||||||
|
available 4.0 version (currently 4.0.9), before attempting an update to 4.1. |
||||||
|
|
||||||
|
|
||||||
|
## Preparation |
||||||
|
|
||||||
|
* Backup your current Openproject installation. Typically you should backup the attachment |
||||||
|
folder of your installation, the subversion repositories (if applicable) and your database. |
||||||
|
For more information please have a look at our [backup guide](backup-guide.md) |
||||||
|
|
||||||
|
* Before Upgrading, check that all the installed OpenProject plugins support the new |
||||||
|
OpenProject version. Remove incompatible plugins before attempting an upgrade. Stop |
||||||
|
the OpenProject Server. You may even add a maintenance page, if you feel comfortable |
||||||
|
with that. |
||||||
|
|
||||||
|
* If you run the worker process with a cronjob, disable the cronjob temporarily. |
||||||
|
* Stop the (delayed\_job) worker process. In case you run the woker process through |
||||||
|
`RAILS_ENV=production bundle exec script/delayed_job start`, execute the following: |
||||||
|
`RAILS_ENV=production bundle exec script/delayed_job stop`. |
||||||
|
|
||||||
|
## Update your system |
||||||
|
|
||||||
|
```bash |
||||||
|
[root@debian]# apt-get update |
||||||
|
[root@debian]# apt-get upgrade |
||||||
|
``` |
||||||
|
|
||||||
|
## Get the new OpenProject Source Code |
||||||
|
Change into the directory where OpenProject is installed and switch to the |
||||||
|
operating-system-user the OpenProject operates as. We assume that OpenProject is |
||||||
|
installed in `/home/openproject/openproject` by the `openproject` user. |
||||||
|
|
||||||
|
```bash |
||||||
|
[root@debian]# su - openproject -c "bash -l" |
||||||
|
[openproject@debian]# cd ~/openproject/openproject |
||||||
|
``` |
||||||
|
|
||||||
|
Remove manual changes and modifications (If you have modified OpenProject source |
||||||
|
files and want to preserve those changes, back up your changes, and re-apply |
||||||
|
them later): |
||||||
|
|
||||||
|
```bash |
||||||
|
[openproject@debian]# git reset --hard |
||||||
|
[openproject@debian]# git fetch |
||||||
|
[openproject@debian]# git checkout v4.1.0 |
||||||
|
``` |
||||||
|
|
||||||
|
## Upgrade Ruby |
||||||
|
OpenProject 4.1 requires Ruby to be installed in version 2.1.x. Assuming you have |
||||||
|
installed Ruby via RVM, do the following to upgrade your Ruby installation: |
||||||
|
|
||||||
|
```bash |
||||||
|
[openproject@debian]# rvm get stable |
||||||
|
[openproject@debian]# export -f rvm_debug |
||||||
|
[openproject@debian]# rvm install 2.1.5 |
||||||
|
[openproject@debian]# rvm use --default 2.1.5 |
||||||
|
[openproject@debian]# gem install bundler |
||||||
|
[openproject@debian]# bundle install |
||||||
|
``` |
||||||
|
|
||||||
|
### Update application server configuration |
||||||
|
This sections only applies to you, if you serve OpenProject via Apache and Passenger. |
||||||
|
If you serve OpenProject in a different way, be sure to check that it still works. |
||||||
|
|
||||||
|
During the upgrade of the Ruby version, we have potentially installed a new Ruby |
||||||
|
and Passenger version. The versions of Ruby and Passenger appear in the Apache |
||||||
|
configuration like this: |
||||||
|
|
||||||
|
```apache |
||||||
|
LoadModule passenger_module /home/openproject/.rvm/gems/ruby-2.1.4/gems/passenger-4.0.53/buildout/apache2/mod_passenger.so |
||||||
|
<IfModule mod_passenger.c> |
||||||
|
PassengerRoot /home/openproject/.rvm/gems/ruby-2.1.4/gems/passenger-4.0.53 |
||||||
|
PassengerDefaultRuby /home/openproject/.rvm/gems/ruby-2.1.4/wrappers/ruby |
||||||
|
</IfModule> |
||||||
|
``` |
||||||
|
Please run the following commands to upgrade passenger and re-install the Apache module: |
||||||
|
|
||||||
|
```bash |
||||||
|
[openproject@debian]# gem update passenger |
||||||
|
[openproject@debian]# gem cleanup passenger |
||||||
|
[openproject@debian]# passenger-install-apache2-module |
||||||
|
``` |
||||||
|
|
||||||
|
The output of passenger-install-apache2-module2 tells you how to configure Apache. |
||||||
|
It is basically the same as what is already installed, except for the updated version numbers. |
||||||
|
|
||||||
|
Don’t forget to restart apache after the configuration change: |
||||||
|
|
||||||
|
```bash |
||||||
|
[root@debian]# service apache2 reload |
||||||
|
``` |
||||||
|
|
||||||
|
## Node.js installation |
||||||
|
Node.js is necessary to precompile the assets (JavaScript and CSS). We will |
||||||
|
install the latest 0.12.x version of Node.js via nodeenv: |
||||||
|
|
||||||
|
```bash |
||||||
|
[openproject@debian]# exit |
||||||
|
[root@debian]# apt-get install python python-pip |
||||||
|
[root@debian]# pip install nodeenv |
||||||
|
[root@debian]# su - openproject -c "bash -l" |
||||||
|
[openproject@debian]# cd /home/openproject |
||||||
|
[openproject@debian]# nodeenv nodeenv |
||||||
|
[openproject@debian]# source ./nodeenv/bin/activate |
||||||
|
[openproject@debian]# npm -g install bower |
||||||
|
``` |
||||||
|
|
||||||
|
As a reference, the following Node.js and NPM versions have been installed on our system: |
||||||
|
|
||||||
|
```bash |
||||||
|
[openproject@debian]# node --version |
||||||
|
v0.12.2 |
||||||
|
[openproject@debian]# npm --version |
||||||
|
1.4.28 |
||||||
|
[openproject@debian]# bower --version |
||||||
|
1.3.12 |
||||||
|
``` |
||||||
|
|
||||||
|
## The Upgrade |
||||||
|
|
||||||
|
Now that the sources and dependencies are in place, you can migrate the Database and do the upgrade: |
||||||
|
|
||||||
|
```bash |
||||||
|
[openproject@debian]# cd /home/openproject/openproject |
||||||
|
[openproject@debian]# npm install |
||||||
|
[openproject@debian]# RAILS_ENV="production" bundle exec rake db:migrate |
||||||
|
[openproject@debian]# RAILS_ENV="production" bundle exec rake db:seed |
||||||
|
[openproject@debian]# RAILS_ENV="production" bundle exec rake assets:precompile |
||||||
|
[openproject@debian]# touch tmp/restart.txt |
||||||
|
``` |
||||||
|
|
||||||
|
*Side note:* If you are using `RAILS_ENV="development"` the task `bundle exec rake |
||||||
|
assets:webpack` needs to be run. This step is not necessary for `production` |
||||||
|
because it is part of the `asset:precompile` tasks. |
||||||
|
|
||||||
|
## The Aftermath |
||||||
|
* Re-enable the `delayed_job` cron job that was disabled in the first step. |
||||||
|
* If you have put up a maintenance page, remove it. |
||||||
|
* Start the OpenProject server again |
||||||
|
* Watch for further OpenProject updates in our news, or on twitter. |
||||||
|
|
||||||
|
## Questions, Comments, and Feedback |
||||||
|
If you have any further questions, comments, feedback, or an idea to enhance this guide, |
||||||
|
please tell us at the appropriate forum. |
||||||
|
|
||||||
|
Also, please take a look at the Frequently [Asked Questions](https://www.openproject.org/help/faq/). |
||||||
|
|
||||||
@ -0,0 +1,73 @@ |
|||||||
|
# Backup Guide |
||||||
|
|
||||||
|
We advice to backup your OpenProject installation regularly — especially |
||||||
|
before upgrading to a newer version. |
||||||
|
|
||||||
|
## What should be backed up |
||||||
|
|
||||||
|
In general the following parts of your OpenProject installation should be |
||||||
|
backed up: |
||||||
|
|
||||||
|
* Data stored in the database |
||||||
|
* Configuration files |
||||||
|
* Uploaded files (attachments) |
||||||
|
* Repositories (typically subversion) if applicable |
||||||
|
|
||||||
|
## Backup via packager command line client |
||||||
|
|
||||||
|
The packager installation provides a backup tool which can be used to take |
||||||
|
a snaphsot of the current OpenProject installation. It will create a |
||||||
|
backup of all parts mentioned above. The backup tool is used by |
||||||
|
executing the following command: |
||||||
|
|
||||||
|
`openproject run backup` |
||||||
|
|
||||||
|
for the _OpenProject Core Editon_ or a slighly different command if the |
||||||
|
_OpenProject Community Edition_ is used (a `-ce` is prepended): |
||||||
|
|
||||||
|
`openproject-ce run backup` |
||||||
|
|
||||||
|
The command will create backup files in the following location: |
||||||
|
|
||||||
|
`/var/db/openproject/backup` or `/var/db/openproject-ce/backup` |
||||||
|
depending on the Edition used (as above `-ce` is used for Community |
||||||
|
Edition). |
||||||
|
|
||||||
|
In detail the content of the directory should look very similar to the |
||||||
|
following: |
||||||
|
|
||||||
|
```bash |
||||||
|
root@test-packager-backup:/opt/openproject# ls -l /var/db/openproject/backup/ |
||||||
|
total 24 |
||||||
|
-rw-r----- 1 openproject openproject 117 Apr 8 09:55 attachments-20150408095521.tar.gz |
||||||
|
-rw-r----- 1 openproject openproject 667 Apr 8 09:55 conf-20150408095521.tar.gz |
||||||
|
-rw-r----- 1 openproject openproject 8298 Apr 8 09:55 mysql-dump-20150408095521.sql.gz |
||||||
|
-rw-r----- 1 openproject openproject 116 Apr 8 09:55 svn-repositories-20150408095521.tar.gz |
||||||
|
``` |
||||||
|
|
||||||
|
## Restore notice |
||||||
|
|
||||||
|
The backup created via the packager command line client consists of four |
||||||
|
parts which are all zipped using `gzip`. Except the MySQL database dump |
||||||
|
these parts can be restored by untar/unzip the `*.tar.gzip` and copy the |
||||||
|
content to the proper location. The command to untar and unzip the |
||||||
|
`*.tar.gz` files looks like this (using sample file names from above): |
||||||
|
|
||||||
|
```bash |
||||||
|
tar vxfz attachments-20150408095521.tar.gz |
||||||
|
``` |
||||||
|
|
||||||
|
To restore the MySQL dump it is recommended to use the `mysql` comand |
||||||
|
line client. |
||||||
|
|
||||||
|
First the dump has to be extracted (unzipped) and then restored. The |
||||||
|
command used should look very similar to this: |
||||||
|
|
||||||
|
```bash |
||||||
|
gzip -d mysql-dump-20150408095521.sql.gz |
||||||
|
mysql -u <user> -h <host> -p <database> < mysql-dump-20150408095521.sql |
||||||
|
``` |
||||||
|
|
||||||
|
The `<user>`, `<host>` and `<database>` variables have to be replaced with |
||||||
|
actual values. |
||||||
|
|
||||||
Loading…
Reference in new issue