1. Getting started
  2. Environment variables

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.

Supported env vars

General

  • DEFAULT_DOMAIN: The default short domain used for this Shlink instance. For example s.test.

  • IS_HTTPS_ENABLED: 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.

  • 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.

  • 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.

  • MEMORY_LIMIT (v4.1.0) : The maximum amount of memory that every Shlink process can use. You can provide a number, which will be the amount of memory in bytes, or a number followed by K for kilobytes, M for megabytes or G for gigabytes. You can also provide -1 to set no memory limit. Defaults to 512M.

    Note

    When using RoadRunner, Shlink will spin-up one persistent process per web/job worker, which will run and consume memory until Shlink is restarted.

    With php-fpm, there will be one process per request that’s killed once finished. The max amount of concurrent active processes can be configured using process.max.

URL shortening

  • 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.
  • AUTO_RESOLVE_TITLES: Used to automatically resolve the short URL’s title based on the <title /> tag in the long URL. Defaults to true.
  • 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.

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.
  • DB_USE_ENCRYPTION: Whether it is desired to use an encrypted connection with the database or not. Defaults to false.

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: 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: 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: 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_EXTRA_PATH_MODE (v4.4.0) : Determines how Shlink should match short URLs when they start with a known short code. (See Extra path forwarding for more info).
    • default -> Only exact short URLs will match. Extra paths will result in a not-found short URL.
    • append -> The rest of the path will be appended to the long URL before redirection.
    • ignore -> The rest of the path will be ignored.
  • REDIRECT_APPEND_EXTRA_PATH: This is deprecated since Shlink 4.4.0. Use REDIRECT_EXTRA_PATH_MODE=append instead.

Visits tracking

  • DISABLE_TRACKING: 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: 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: Tells if tracking of the referrer should be disabled. Defaults to false (see Tracking visits for more info).
  • DISABLE_UA_TRACKING: 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

Warning

Starting with Shlink 4.5.0, generating QR codes through Shlink is considered deprecated. See this issue for details.

  • DEFAULT_QR_CODE_SIZE: 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: 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: 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: 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: 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.
  • QR_CODE_FOR_DISABLED_SHORT_URLS (v3.7.2) : Whether generating QR codes should work for disabled short URLs. Disabled short URLs are those which reached the maximum amount of visits, have a validSince date in the future, or a validUntil date in the past. Defaults to true.
  • DEFAULT_QR_CODE_COLOR (v4.0.0) : The QR code foreground color. Defaults to #000000 (black).
  • DEFAULT_QR_CODE_BG_COLOR (v4.0.0) : The QR code background color. Defaults to #FFFFFF (white).
  • DEFAULT_QR_CODE_LOGO_URL (v4.0.0) : A URL pointing to a logo that will be placed in the middle of the QR code. This one is experimental, as some images might break the QR code.

Robots.txt

  • ROBOTS_ALLOW_ALL_SHORT_URLS (v4.2.0) : Whether all short URLs should be allowed via robots.txt or not. If set to true, the crawlable option set in individual short URLs will be ignored. Defaults to false.
  • ROBOTS_USER_AGENTS (v4.2.0) : A comma-separated list of allowed user agents via robots.txt. Defaults to *.

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_SENTINEL_SERVICE: 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: Tells if the integration with a RabbitMQ server for real-time updates should be enabled. Defaults to false.
  • RABBITMQ_HOST: The RabbitMQ server host name. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_USE_SSL: Whether connection is encrypted with SSL/TLS or not. Defaults to false. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_PORT: The RabbitMQ server port. Defaults to 5672. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_USER: The RabbitMQ server username credential. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_PASSWORD: The RabbitMQ server password credential. This will be ignored if RABBITMQ_ENABLED is false.
  • RABBITMQ_VHOST: The RabbitMQ server VHost. Defaults to /. This will be ignored if RABBITMQ_ENABLED 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:

  • 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 the amount of available CPUs.
  • TASK_WORKER_NUM: The amount of concurrent background tasks this Shlink instance will be able to execute. Defaults to the amount of available CPUs.
  • 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.

Secret env vars

Starting with Shlink 4.0.0, you can pass any environment variable with the _FILE suffix. When you do that, Shlink treats its value as a file path, reads that file, and uses its value as the corresponding non-suffixed env var.

For example, if DB_PASSWORD is not set, but DB_PASSWORD_FILE is, Shlink will read it, and return its contents as the DB_PASSWORD value.

This is useful when used in combination with docker compose secrets, as it prevents env vars containing secrets to leak their values to any intermediary system.

Considerations with secret env vars

  • The logic to parse secret env vars is generic, so you can use this approach with any existing or future environment variable.
  • The use of a _FILE suffix is a convention used by popular docker images.
  • If both the suffixed and non-suffixed env vars are provided (for example, DB_PASSWORD and DB_PASSWORD_FILE), the latter will be ignored.

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.