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
orfalse
). 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 tofalse
.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 isUTC
in the case of the docker image.MULTI_SEGMENT_SLUGS_ENABLED
(v3.2.0) : Allows to create and handle multi-segment custom slugs whentrue
is provided. Default value isfalse
. 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 whentrue
is provided. Default value isfalse
. See short URLs trailing slash for more information.SHORT_URL_MODE
(v3.5.0) :strict
orloose
. Determines how to match short URLs. Defaults tostrict
. 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 toShlink
.
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 forDB_DRIVER
:- mysql or maria ->
3306
- postgres ->
5432
- mssql ->
1433
- mysql or maria ->
DB_UNIX_SOCKET
: Alternatively to theDB_HOST
, you can provide this to connect through unix sockets when usingmysql
,maria
orpostgres
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 generic404 - 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 generic404 - 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 generic404 - 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 isfalse
. (See Extra path forwarding for more info).
Visits tracking
DISABLE_TRACKING
(v2.7.0) : Tells if visits tracking should be completely disabled. Defaults tofalse
(see Tracking visits for more info).TRACK_ORPHAN_VISITS
: Tells if orphan visits should be tracked or not. Defaults totrue
(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 tofalse
(see Tracking visits for more info).DISABLE_REFERRER_TRACKING
(v2.7.0) : Tells if tracking of the referrer should be disabled. Defaults tofalse
(see Tracking visits for more info).DISABLE_UA_TRACKING
(v2.7.0) : Tells if tracking of the user agent should be disabled. Defaults tofalse
(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 istrue
(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 thesize
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 themargin
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 theformat
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 theerrorCorrection
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 totrue
.
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 inREDIS_SERVERS
should be URL-decoded. Defaults tofalse
.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 inREDIS_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 tofalse
.
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 butMERCURE_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 tofalse
.RABBITMQ_HOST
(v2.10.0) : The RabbitMQ server host name. This will be ignored ifRABBITMQ_ENABLED
is false.RABBITMQ_USE_SSL
(v3.7.0) : Whether connection is encrypted with SSL/TLS or not. Defaults tofalse
. This will be ignored ifRABBITMQ_ENABLED
is false.RABBITMQ_PORT
(v2.10.0) : The RabbitMQ server port. Defaults to5672
. This will be ignored ifRABBITMQ_ENABLED
is false.RABBITMQ_USER
(v2.10.0) : The RabbitMQ server username credential. This will be ignored ifRABBITMQ_ENABLED
is false.RABBITMQ_PASSWORD
(v2.10.0) : The RabbitMQ server password credential. This will be ignored ifRABBITMQ_ENABLED
is false.RABBITMQ_VHOST
(v2.10.0) : The RabbitMQ server VHost. Defaults to/
. This will be ignored ifRABBITMQ_ENABLED
is false.(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 asRABBITMQ_LEGACY_VISITS_PUBLISHING
true
. Default values isfalse
.
Matomo integration
MATOMO_ENABLED
(v3.7.0) : Tells if visits should be sent to a Matomo instance. Defaults tofalse
.MATOMO_BASE_URL
(v3.7.0) : The external Matomo server URL. This will be ignored ifMATOMO_ENABLED
is false.MATOMO_SITE_ID
(v3.7.0) : The site ID to be used for Shlink visits. This will be ignored ifMATOMO_ENABLED
is false.MATOMO_API_TOKEN
(v3.7.0) : The API token so that Shlink can call Matomo’s API. This will be ignored ifMATOMO_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 valuetrue
, 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.
(v2.8.0) : If provided with valueENABLE_PERIODIC_VISIT_LOCATE
true
, it schedules thevisit:locate
command to be run every hour inside the container using crontab. Defaults tofalse
. 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.
: A comma-separated list of URLs that will receive aVISITS_WEBHOOKS
POST
request when a short URL receives a visit.(v2.9.0) : Used to enable sending orphan visits to the webhooks configured inNOTIFY_ORPHAN_VISITS_TO_WEBHOOKS
VISITS_WEBHOOKS
. Default value isfalse
.
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.