In the previous guides we had the chance to go through the basic commands of dputils which allow us to handle Deskpro instances in a very simple way. This advanced guide aims to deliver a more comprehensive and detailed help to work with dputils.

::: info Although the following instructions are based on the Linux version, the syntax is the same for both Windows and Linux. :::

Running dputils with the command --help will retrieve the main commands available.

$ cd /path/to/deskpro
$ bin/console dputils -h
 copy

backup: This command will give access to all the backup options available. Has a sub-set of commands just for backup.
dump_config: Generates a general print of the main environment configs for Deskpro
help: Displays this menu
restore: With this command you'll have access to all the restore options. Has a sub-set of commands just for restore.
version: displays the current version

1- Backup

The backup command has a sub-set of flags that give the user added flexibility when running backups of Deskpro instances. To see all the options available, you need to issue the --help flag in conjunction with the backup command

$ bin/console dputils backup --help
 copy

1.1 Full backup to custom folder

To generate a full backup (database dump and attachments) to a custom folder, the sintax to be used should be like the one noted below

$ bin/console dputils backup -t /path/to/custombackupfolder
 copy

1.2 Full backup to a public folder

In the event you need to make the backup publicly available for download, you can issue the backup command with the flag -t public. It will generate a long random URL that you can use to download the backup. Just remember to delete the file after it's been downloaded.

$ bin/console dputils backup -t public
 copy

1.3 Partial backup

In case you need to generate a partial backup (just the database dump or the attachments folder) you can use the -b flag to force this behavior.

$ bin/console dputils backup -b database -t /path/to/custombackupfolder
 copy

$ bin/console dputils backup -b attachments -t /path/to/custombackupfolder
 copy

2- Dump Config

The dump_config command generates a small dump of the main Deskpro configuration. It is used mainly for diagnosis purposes.

$ bin/console dputils dump_config
 copy

3- Restore

The restore command is the most comprehensive of the entire tool, and it is very flexible, allowing a multitude of combinations of flags to better adjust to the user needs. To obtain a full list of flags available just issue with the --help flag:

$ bin/console dputils restore --help
Usage:
  dputils restore [flags]
Flags:
      --as-test-instance
      --attachments string
      --attachments-archive
  -k, --full-backup string
  -h, --help                         
  -i, --interactive
      --move-attachments
      --mysql-direct string
      --mysql-direct-audit string
      --mysql-direct-system string
      --mysql-direct-voice string
      --mysql-dump string
      --reindex-elastic
      --skip-upgrade
      --tmpdir string
Global Flags:
      --deskpro string   Path to Deskpro on the current server
      --php string       Path to PHP
 copy

In the following lines we will detail every single flag. In most cases, several flags can be used together to build a powerful command that suits the user needs

3.1 --as-test-instance

This flag will disable email processing in the restored instance. Example of a restore from a local full backup to a test instance:

$ bin/console dputils restore --as-test-instance -k /path/to/fullbackup
 copy

::: info Note This command disables email processing by applying this config in $SETTINGS['disable_outgoing_email'] = true; in config/advanced/config.settings.php - when you want to re-enable main processing, you will need to manually revert this setting to false;. :::

3.2 --attachments

The flag --attachments can be used when the original folder is accessible. This flag cannot be used when you want to extract the attachments from an archive. There are several options to retrieve the attachments

• Local Filesystem: Either locally or a network folder mounted locally. Note: the files are copied and not moved. If you want to move attachments, you'll need to use the --move-attachments flag

• URL: A URL from where attachments can be downloaded. Use this if your attachments are uploaded somewhere where they can be downloaded directly. For example, if they are available over HTTP or if you have uploaded them to an S3 bucket. Examples:

https://example.com/deskpro/MRjUXQsZe6h6ESP4hCQReahM56xphf/attachments
s3::https://s3-eu-west-1.amazonaws.com/bucket/attachments/?aws_access_key_id=xxx&aws_access_key_secret=xxx&aws_access_token=xxx
 copy

• none: If you wish to skip downloading attachments, the use the special string "none". You might do this if attachments are not stored in the filesystem (e.g. if they're in the DB or S3).

::: info Note: If you opt for local attachments, you will need to ensure your attachments folder has correct writeable permissions. This may not be set automatically by the utility, so you can run sudo chmod -R 777 /usr/share/nginx/html/deskpro/attachments/ to set the correct permissions. :::

3.3 --attachments-archive

If you have your attachments folder in a zip file, you need to use this flag to restore it. This option can be used in conjunction with the mysql* options available while copying the database.

3.4 --full-backup

After generating a full backup in the original server, you can restore it using the --full-backup flag. It will search for a file containing a database dump and attachments, so please be sure that your backup is a full backup. The path can either be a local filesystem, a HTTP URL or a S3 URL.

$ bin/console dputils restore --full-backup /path/to/fullbackup
 copy

3.5 --interactive

The flag --interactive will force the input of values during runtime

3.6 --move-attachments

If you have specified a local filesystem path with --attachments, this flag can be enabled to make this tool MOVE files into place rather than copy them. You might choose to do this if the files are on the local disk already and you don't want to consume more disk space.

$ bin/console dputils restore --mysql-direct deskpro:mypass@10.1.1.3/deskpro --attachments /path/to/attachments --move-attachments
 copy

3.7 --mysql-direct

With this flag the tool will connect to an existing MySQL server to copy it. This is the recommended method because it doesn't require local disk space, the dump and import can be streamed over the network. If the password is not specified, you will be prompted for it.

$ bin/console dputils restore --mysql-direct deskpro:mypass@10.1.1.3/deskpro --attachments-archive /path/to/attachments 
 copy

::: info With all the -mysql options, you either have the attachments in your database/S3 bucket, or you'll need to use --attachments flag for the attachments folder, or --attachments-archive for the attachments archive you want to copy. :::

3.8 --mysql-direct-audit

An additional information for audit database (it may be stored on a different mysql server). If in your new config audit connection config exists we will restore audit db there otherwise we're going to restore audit database into default database.

3.9 --mysql-direct-system

An additional information for system database (it may be stored on a different mysql server). If in your new config system connection config exists we will restore system db there otherwise we're going to restore system database into default database.

3.10 --mysql-direct-voice

An additional information for voice database (it may be stored on a different mysql server). If in your new config voice connection config exists we will restore voice db there otherwise we're going to restore voice database into default database.

3.11 --mysql-dump

The --mysql-dump flag allows the user to restore a MySQL dump file. If the file is compressed, it will be automatically decompressed.
Examples:

• https://example.com/deskpro/MRjUXQsZe6h6ESP4hCQReahM56xphf/db.sql.gz

• sftp://user:pass@example.com/tmp/db.sql

• /mnt/db.sql.gz

• D:\db.sql

If you have a checksum, you may append a query parameter to the URI in the form of type:value to verify the download before it's used. This also the a benefit where the download will only happen even upon multiple invokations of this command because the file will exist in the tmpdir. Examples:

• /mnt/db.sql.gz?checksum=md5:b7d96c89d09d9e204f5fedc4d5d55b21

• /mnt/db.sql.gz?checksum=file:./db.sql.gz.sha256sum

You can use files from S3 buckets by adding query parameters for credentials:

• s3::https://s3-eu-west-1.amazonaws.com/bucket/foo/db.sql.gz?aws_access_key_id=xxx&aws_access_key_secret=xxx&aws_access_token=xxx

3.12 --reindex-elastic

This flag will force a Elastic Search indexation as soon as the restore is finished

3.13 --skip-upgrade

When you restore a database dump or full backup, the script will attempt to upgrade Deskpro to the latest version. Using this flag will skip the upgrade step, but you can always run it later if you want to.

3.14 --tmpdir

When you have to specify a custom temporary folder for all the downloaded files, you just need to issue the --tmpdir flag with the custom tmp folder.

4- Version

The command version returns the current dputils version

$ bin/console dputils version
 copy