The main way you will configure Deskpro is via env vars. There are a large number of variables, some are required (such as database connection credentials), and some are optional (such as enabling or disabling features).

When using docker run, we suggest using the --env-file option where you can write all values to a env file. This option is also available with docker-compose.

For example, if you had a config.env file with all of your values in it, you could run Deskpro like so:

docker run \
  --env-file config.env \
  --name deskpro \
  deskpro/deskpro-product:$DPVERSION-onprem
 copy

Example env file

Here's an example config.env file with common options:

# 32 random bits, base64 encoded
# (see "Application secret key" below for instructions on generating this value)
DESKPRO_APP_KEY="Dtax194IaUus2shE2+7NE4/GRAAwriT2Er9SSwL6vDc="

# Database credentials
DESKPRO_DB_HOST="mysql"
DESKPRO_DB_PORT="3306"
DESKPRO_DB_USER="deskpro"
DESKPRO_DB_PASS="my_db_password"
DESKPRO_DB_NAME="deskpro"

# Elastic search
DESKPRO_ES_URL="https://elastic:9200"
DESKPRO_ES_INDEX_NAME="deskpro"

# (Optional) Read-only database
DESKPRO_DB_READ_HOST="mysql-replica"
DESKPRO_DB_READ_PORT="3306"
DESKPRO_DB_READ_USER="deskpro"
DESKPRO_DB_READ_PASS="my_db_password"
DESKPRO_DB_READ_NAME="deskpro"
 copy

Encoding values

In some environments, it may be difficult to declare variables that contain special characters like quotes or newlines. In such cases, you can encode your values by appending an encoding suffix to your variable name. The following options are available:

• *_B64: Values with this suffix are expected to be base64 encoded and they will be decoded before use.

• *_ESC: Values with this suffix will have escape sequences (e.g. \n) decoded into their appropriate real characters before use.

Examples:

# DESKPRO_DB_PASS but with the value base64 encoded
DESKPRO_DB_PASS_B64='bXkgJ3Bhc3N3b3JkJw=='

# PHP_FPM_OVERRIDES but with \n replaced with actual newlines
PHP_FPM_OVERRIDES_ESC='emergency_restart_threshold=10\nemergency_restart_interval=10\n'
 copy

Mount values in files (e.g. secrets)

For a variable VARNAME you may declare a variable VARNAME_FILE=/path/to/file that is a file that contains the value. This is handy for sensitive values that you may not want to make available in the environment.

For example, Docker swarm can manage secrets and docker-compose has a secrets attribute) both use mounted values at /run/secrets/XXX to pass values to the container. For exampe, if you had a secret named my_db_pass with your database password, then you would define an env var DESKPRO_DB_PASS_FILE=/run/secrets/my_db_pass.

Common variables

Application secret key

Every instance of Deskpro needs an app key (DESKPRO_APP_KEY) that acts as a secret used in cryptographic functions like hashing. The app key must be be 32 random bits and it must be base64 encoded.

An easy way to generate an application key is to execute some simple PHP code:

docker run -it --rm php:latest php -r 'echo "DESKPRO_APP_KEY=".var_export(base64_encode(random_bytes(32)),true).PHP_EOL;'
 copy

... then copy and paste the outputted line into your env file. It will look something like this:

# example output - do not copy this key - use your own
DESKPRO_APP_KEY='WPxTbezEYhxIqFYZEF4VIhWVrOqE7u3q2lvM/h/+8Wk='
 copy

Database

• [Required] DESKPRO_DB_HOST: Database host name or IP address

• [Required] DESKPRO_DB_PORT: Port number to be used with the host

• [Required] DESKPRO_DB_NAME: Deskpro database name

• [Required] DESKPRO_DB_USER and DESKPRO_DB_PASS: User to connect to the db with. User must have permission to use the DESKPRO_DB_NAME user including create/drop.

• DESKPRO_DB_READ_HOST (and DESKPRO_DB_READ_*): Database server to be used for read queries. You only need to set the host. All other values can also be set but will default to the primary database values: DESKPRO_DB_READ_PORT, DESKPRO_DB_READ_NAME, DESKPRO_DB_READ_USER, DESKPRO_DB_READ_PASS.

Elastic search

• [Required] DESKPRO_ES_URL: Full URL to elastic. E.g. https://username:password!#$?*abc@foo.com:9200. No trailing slash.

• [Required] DESKPRO_ES_INDEX_NAME: Index name to use. Defaults to deskpro.

Storage

• DESKPRO_STORAGE_TYPE: Storage type: db, fs, or s3. Defaults to db.

• DESKPRO_STORAGE_SETTINGS: A JSON-encoded string of storage adapter settings according to the type

Filesystem storage (fs)

Storing files on the filesystem requires no special configuration other than setting DESKPRO_STORAGE_TYPE=fs. Files will be written to /srv/deskpro/INSTANCE_DATA/attachments in the container which is where you should mount a persisted volume.

AWS S3 storage (s3) settings

You need to specify S3 bucket credentals. For example, in an env file:

DESKPRO_STORAGE_SETTINGS="
{
  \"bucket_name\": \"your-bucket-name\",
  \"bucket_region\": \"us-east-1\",
  \"access_key\": \"access key\",
  \"secret_key\": \"secret key\"
}
"
 copy