BookStack Code Mirror - website/blob - content/docs/admin/backup-restore.md

 1 +++
 2 title = "Backup and Restore"
 3 description = "How to back up and restore your BookStack data"
 4 date = "2017-01-01"
 5 type = "admin-doc"
 6 +++
 7
 8 BookStack does not currently have a built-in way to backup and restore but it
 9 can be done via the command line fairly simply. This process will be impoved in
 10 the future and will ideally be built-in at some point soon.
 11
 12 Please note the below commands are based on using Ubuntu. If you are using a
 13 different operating system you may have to alter these commands to suit.
 14
 15 ---
 16
 17 ## Backup
 18
 19 There are two types of content you need to backup: Files and database records.
 20
 21 #### Database
 22
 23 The easiest way to backup the database is via `mysqldump`:
 24
 25 ```bash
 26 # Syntax
 27 mysqldump -u {mysql_user} -p {database_name} > {output_file_name}
 28 ## Only specify the -p if the user provided has a password
 29
 30
 31 # Example
 32 mysqldump -u benny bookstack > bookstack.backup.sql
 33 ```
 34
 35 If you are using MySQL 5.7 on Ubuntu 16.04 and are using the `root` MySQL
 36 user you will likely have to run the command above with `sudo`:
 37
 38 ```bash
 39 sudo mysqldump -u root bookstack > bookstack.backup.sql
 40 ```
 41
 42 The resulting file (`bookstack.backup.sql` in the examples above) will contain
 43 all the data from the database you specified. Copy this file to somewhere safe,
 44 ideally on a different device.
 45
 46 #### Files
 47
 48 Below is a list of files and folders containing data you should back up. The paths
 49 are shown relative to the root BookStack folder.
 50
 51 * `.env` - File, Contains important configuration information.
 52 * `public/uploads` - Folder, Contains any uploaded images (If not using amazon s3).
 53 * `storage/uploads` - Folder, Contains uploaded page attachments (Only exists as of BookStack v0.13).
 54
 55 Alternatively you could backup up your whole BookStack folder but only the above
 56 are non-restorable.
 57
 58 The following command will create a compressed archive of the above folders and
 59 files:
 60
 61 ```bash
 62 # BookStack v0.13+:
 63 tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads
 64
 65 # BookStack v0.12.* and below:
 66 tar -czvf bookstack-files-backup.tar.gz .env public/uploads
 67 ```
 68
 69 The resulting file (`bookstack-files-backup.tar.gz`) will contain all your file
 70 data. Copy this to a safe place, ideally on a different device.
 71
 72 ---
 73
 74 ## Restore
 75
 76 If you are restoring from scratch follow the
 77 [installation](/docs/admin/installation)
 78 instructions first to get a new BookStack instance up and running. Once you are
 79 sure the new instance is working follow the instructions below.
 80
 81 #### Database
 82
 83 To restore the database you simply need to execute the sql in the output file from the `mysqldump`
 84 you performed above. To do this copy your database SQL backup file onto the
 85 BookStack or database host machine and run the following:
 86
 87 ```bash
 88 # Syntax
 89 mysql -u {mysql_user} -p {database_name} < {backup_file_name}
 90 ## Only specify the -p if the user provided has a password
 91
 92 # Example
 93 mysql -u benny -p bookstack < bookstack.backup.sql
 94
 95 # If using the root user on Ubuntu 16.04 and MySQL 5.7 you may
 96 # have to run the above with root permissions via sudo:
 97 sudo mysql -u root bookstack < bookstack.backup.sql
 98 ```
 99
 100 If you are restoring to a new verion of BookStack you will have to run
 101 `php artisan migrate` after restore to perform any required updates to the database.
 102
 103 #### Files
 104
 105 To restore the files you simple need to copy them from the backup archive
 106 back to their original locations.  If you created a compressed `bookstack-files-backup.tar.gz`
 107 archive as per the backup instructions above you can simply copy that file to
 108 your BookStack folder then run the following command:
 109
 110 ```bash
 111 tar -xvzf bookstack-files-backup.tar.gz
 112 ```
 113
 114 If you get errors during the above command it may be due to permissions.
 115 Change permissions so you can write to the restore locations.
 116
 117 After a backup of the files you should re-set the permissions to ensure any write-required
 118 locations are writable by the server. The locations required for this can be
 119 found in the [installation](/docs/admin/installation)
 120 instructions.