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

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