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