Environment variables

After installing Shlink, you will have to set it up, and customize different aspects of its behavior. One way to do this is via environment variables.

This is the complete list of supported env vars. Right next to their name you will find the version in which they were introduced.

Strikethrough env vars are deprecated.

General

  • DEFAULT_DOMAIN (v2.9.0) : The default short domain used for this Shlink instance. For example s.test.
  • IS_HTTPS_ENABLED (v2.10.0) : Tells if Shlink is served with https or not (true or false). It’s still up to you to actually serve it with HTTPS.
  • GEOLITE_LICENSE_KEY: The license key used to download new GeoLite2 database files. Go to GeoLite2 license key to know how to generate it. Not providing a license key will completely disable visits geolocation.
  • AUTO_RESOLVE_TITLES: Used to automatically resolve the short URL’s title based on the <title /> tag in the long URL. Defaults to false.
  • DEFAULT_SHORT_CODES_LENGTH: The length you want generated short codes to have. It defaults to 5 and has to be at least 4, so any value smaller than that will fall back to 4.
  • DELETE_SHORT_URL_THRESHOLD: The amount of visits on short URLs which will not allow them to be deleted. If not provided, this restriction will be disabled.
  • BASE_PATH: The base path from which you plan to serve Shlink, in case you don’t want to serve it from the root of the domain. It has to start with a bar, like /shlink. Defaults to ''.
  • TIMEZONE (v3.1.0) : A timezone code as defined in this list. All dates stored by Shlink (visits, short URL creation, etc) will be considered to be on this timezone. By default, the default timezone set in PHP config will be used, which is UTC in the case of the docker image.
  • MULTI_SEGMENT_SLUGS_ENABLED (v3.2.0) : Allows to create and handle multi-segment custom slugs when true is provided. Default value is false. See multi-segment custom slugs for more information.
  • SHORT_URL_TRAILING_SLASH (v3.3.0) : Allows to enable support for trailing slashes in short URLs when true is provided. Default value is false. See short URLs trailing slash for more information.
  • SHORT_URL_MODE (v3.5.0) : strict or loose. Determines how to match short URLs. Defaults to strict. See short URLs mode for more information.
  • CACHE_NAMESPACE (v3.7.0) : A prefix used for all cache keys generated by Shlink. It’s important to set a unique value here if you have multiple Shlink instances sharing the same cache store (same server when not using redis, or same redis cluster), otherwise there could be collisions. Defaults to Shlink.

Server

These env vars are only relevant when serving Shlink with openswoole or RoadRunner.

  • PORT: Can be used to set the port in which Shlink listens. Defaults to 8080 (Some cloud providers, like Google cloud or Heroku, expect to be able to customize exposed port by providing this env var).
  • WEB_WORKER_NUM: The amount of concurrent http requests this Shlink instance will be able to serve. Defaults to 16 for openswoole and the amount of available CPUs for roadrunner.
  • TASK_WORKER_NUM: The amount of concurrent background tasks this Shlink instance will be able to execute. Defaults to 16 for openswoole and the amount of available CPUs for roadrunner. Cannot be lower than 4 for openswoole.

Database

  • DB_DRIVER: mysql, maria, postgres, mssql or sqlite.
  • DB_NAME: The database name to be used when using an external database driver. Defaults to shlink.
  • DB_USER: The username credential to be used when using an external database driver.
  • DB_PASSWORD: The password credential to be used when using an external database driver.
  • DB_HOST: The host name of the database server when using an external database driver.
  • DB_PORT: The port in which the database service is running when using an external database driver. Default value is based on the value provided for DB_DRIVER:
    • mysql or maria -> 3306
    • postgres -> 5432
    • mssql -> 1433
  • DB_UNIX_SOCKET: Alternatively to the DB_HOST, you can provide this to connect through unix sockets when using mysql, maria or postgres drivers.

Warning

SQLite is intended for testing/automation purposes only. Using it in production is not supported, even less if mounted via docker volumes.

There’s a potential risk of breakage when updating Shlink, so make sure you move to any of the other alternatives if you plan to use Shlink long term.

Redirects

  • REDIRECT_STATUS_CODE: 301, 302, 308 or 307 (last two since v3.5.0). Determines the status code that should be used on redirects from short to long URLs. Setting 308 or 307 implicitly makes requests to short URLs work regardless the HTTP method. Defaults to 302.
  • REDIRECT_CACHE_LIFETIME: Allows to set the amount of seconds that redirects should be cached when redirect status is 301 or 308. Default values is 30.
  • DEFAULT_INVALID_SHORT_URL_REDIRECT (v2.10.0) : If a URL is provided here, when a user tries to access an invalid short URL, and the visited domain does not have a redirect URL of its own, he/she will be redirected to this value. If this env var is not provided, the user will see a generic 404 - not found page.
  • DEFAULT_REGULAR_404_REDIRECT (v2.10.0) : If a URL is provided here, when a user tries to access a URL not matching any supported by the router, and the visited domain does not have a redirect URL of its own, he/she will be redirected to this value. If this env var is not provided, the user will see a generic 404 - not found page.
  • DEFAULT_BASE_URL_REDIRECT (v2.10.0) : If a URL is provided here, when a user tries to access Shlink’s base URL, and the visited domain does not have a redirect URL of its own, he/she will be redirected to this value. If this env var is not provided, the user will see a generic 404 - not found page.
  • REDIRECT_APPEND_EXTRA_PATH (v2.8.0) : Makes Shlink match short URLs as soon as they start with a known short code, appending the rest of the path to the long URL before redirection. Default values is false. (See Extra path forwarding for more info).

Visits tracking

  • DISABLE_TRACKING (v2.7.0) : Tells if visits tracking should be completely disabled. Defaults to false (see Tracking visits for more info).
  • TRACK_ORPHAN_VISITS: Tells if orphan visits should be tracked or not. Defaults to true (see Tracking visits for more info).
  • DISABLE_TRACK_PARAM: The name of a query param that can be used to visit short URLs avoiding the visit to be tracked. This feature won’t be available if no value is provided (see Tracking visits for more info).
  • DISABLE_TRACKING_FROM: A comma-separated list of IP address patterns from which all tracking should be disabled. It allows providing fixed IP addresses (100.200.80.40), CIDR blocks (192.168.10.0/24) or wildcard patterns (11.22.*.*)
  • DISABLE_IP_TRACKING (v2.7.0) : Tells if tracking of the IP address (and therefore visitors location) should be disabled. Defaults to false (see Tracking visits for more info).
  • DISABLE_REFERRER_TRACKING (v2.7.0) : Tells if tracking of the referrer should be disabled. Defaults to false (see Tracking visits for more info).
  • DISABLE_UA_TRACKING (v2.7.0) : Tells if tracking of the user agent should be disabled. Defaults to false (see Tracking visits for more info).
  • ANONYMIZE_REMOTE_ADDR: Tells if IP addresses from visitors should be obfuscated before storing them in the database. Default value is true (see Tracking visits for more info).

Warning

Setting this to false will make your Shlink instance no longer be in compliance with the GDPR and other similar data protection regulations.

QR codes

  • DEFAULT_QR_CODE_SIZE (v2.9.0) : A value between 50 and 1000 to determine the default size of generated QR codes when the size query param is not provided. Defaults to 300.
  • DEFAULT_QR_CODE_MARGIN (v2.9.0) : A value greater than 0 to determine the default margin of generated QR codes when the margin query param is not provided. Defaults to 0.
  • DEFAULT_QR_CODE_FORMAT (v2.9.0) : One of png or svg, to determine the default format of generated QR codes when the format query param is not provided. Defaults to png.
  • DEFAULT_QR_CODE_ERROR_CORRECTION (v2.9.0) : One of L (Low), M (Medium), Q (Quartile) or H (High), to determine the default error correction of generated QR codes when the errorCorrection query param is not provided. Defaults to l.
  • DEFAULT_QR_CODE_ROUND_BLOCK_SIZE (v2.10.0) : Tells if the block size should be round on QR codes, making it more readable, but potentially adding some extra margin as a side effect. Defaults to true.

Redis integration

  • REDIS_SERVERS: A comma-separated list of redis servers which Shlink uses for shared locks, cache, and optionally real-time updates through pub/sub (make sure to include the port number and credentials for every server).
  • REDIS_DECODE_CREDENTIALS (v3.7.0) : Tells if credentials provided for server URIs in REDIS_SERVERS should be URL-decoded. Defaults to false.
  • REDIS_SENTINEL_SERVICE (v2.9.0) : The name of the sentinel service if you want to use redis sentinel. If this value is provided, the servers provided in REDIS_SERVERS will be considered sentinel instances.
  • REDIS_PUB_SUB_ENABLED (v3.2.0) : Tells if the configured redis instance/cluster should also be used to publish real-time updates via redis pub/sub. Defaults to false.

Mercure hub integration

  • MERCURE_PUBLIC_HUB_URL: The public URL of a mercure hub server to which Shlink will sent updates. This URL will also be served to consumers that want to subscribe to those updates.
  • MERCURE_INTERNAL_HUB_URL: An internal URL for a mercure hub. Will be used only when publishing updates to mercure, and does not need to be public. If this is not provided but MERCURE_PUBLIC_HUB_URL was, the former one will be used to publish updates.
  • MERCURE_JWT_SECRET: The secret key that was provided to the mercure hub server, in order to be able to generate valid JWTs for publishing/subscribing to that server.

RabbitMQ integration

  • RABBITMQ_ENABLED (v2.10.0) : Tells if the integration with a RabbitMQ server for real-time updates should be enabled. Defaults to false.
  • RABBITMQ_HOST (v2.10.0) : The RabbitMQ server host name. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_USE_SSL (v3.7.0) : Whether connection is encrypted with SSL/TLS or not. Defaults to false. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_PORT (v2.10.0) : The RabbitMQ server port. Defaults to 5672. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_USER (v2.10.0) : The RabbitMQ server username credential. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_PASSWORD (v2.10.0) : The RabbitMQ server password credential. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_VHOST (v2.10.0) : The RabbitMQ server VHost. Defaults to /. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_LEGACY_VISITS_PUBLISHING (v3.2.0) : When RabbitMQ integration was implemented, the publishing was not done according to the async API spec. Shlink v3.2.0 fixes that, but since it is a breaking change, you can retain the previous format by providing this as true. Default values is false.

Matomo integration

  • MATOMO_ENABLED (v3.7.0) : Tells if visits should be sent to a Matomo instance. Defaults to false.
  • MATOMO_BASE_URL (v3.7.0) : The external Matomo server URL. This will be ignored if MATOMO_ENABLED is false.
  • MATOMO_SITE_ID (v3.7.0) : The site ID to be used for Shlink visits. This will be ignored if MATOMO_ENABLED is false.
  • MATOMO_API_TOKEN (v3.7.0) : The API token so that Shlink can call Matomo’s API. This will be ignored if MATOMO_ENABLED is false.

Specific for the docker image

These are the env vars that only the docker image take into consideration:

  • SKIP_INITIAL_GEOLITE_DOWNLOAD (v3.3.0) : If provided with value true, it will skip the initial GeoLite2 db file download, speeding-up the container start-up. As a side effect, first visits on this container will remain un-located until the file finishes downloading in background.
  • INITIAL_API_KEY (v3.6.4) : An API key that will be created once during container start-up, with admin permissions.

    Considerations with the initial API key

    • It will be ignored if other API keys already exist.
    • If the env var is removed at some point, that won’t make the API key to be deleted.
    • If the value is changed at some point, that won’t make the API key to be edited.
    • Between v3.3.0 and v3.6.3 it was possible to pass this env var to any non-docker Shlink instance, but that caused problems. Now only the docker image takes it into consideration. Use the installation tool for non-docker installations.
  • ENABLE_PERIODIC_VISIT_LOCATE (v2.8.0) : If provided with value true, it schedules the visit:locate command to be run every hour inside the container using crontab. Defaults to false. It will be ignored when using a non-root docker image.

Webhooks integration

Webhooks are deprecated since Shlink 3.1.0. See other integrations for real-time updates above.

  • VISITS_WEBHOOKS: A comma-separated list of URLs that will receive a POST request when a short URL receives a visit.
  • NOTIFY_ORPHAN_VISITS_TO_WEBHOOKS (v2.9.0) : Used to enable sending orphan visits to the webhooks configured in VISITS_WEBHOOKS. Default value is false.

Specific for Openswoole

Starting with Shlink 3.5.0, you can provide any openswoole config option via env vars prefixed with OPENSWOOLE_.

For example, OPENSWOOLE_PACKAGE_MAX_LENGTH=60000 will result in 'package_max_length' => 60000 or OPENSWOOLE_OPEN_CPU_AFFINITY=false will result in 'open_cpu_affinity' => false.

Warning

This feature is experimental, and has some considerations:

  • Certain config options might result in Shlink not working as expected. Proceed at your own risk.
  • If an env var starting with OPENSWOOLE_ is provided but it does not match any openswoole config option, a warning will be printed.
  • Nested configs are not currently supported, so you cannot provide ssl_sni_certs.
  • These env vars will have no effect if you are not serving Shlink with openswoole.

Considerations

There are a few things to have in mind.

  • Shlink has always supported configuration via environment variables when using the official docker image. However, it only supports env vars for other approaches since v2.9.0
  • Shlink also supports providing configuration options via the so-called installation tool. This is an interactive CLI tool that generates some “hardcoded” configuration after being executed. Before Shlink 3.0.0, this configuration will always take precedence over env vars, so you cannot combine the two of them. This limitation is not present starting with Shlink 3.0.0, where environment variables always have precedence.