openproject/doc/operation_guides/manual/backup-guide.md

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