DOCSEARCHbyAlgolia
Submit Docs

Shlink Documentation

website·Indexed 35 days ago

https://shlink.io/documentation

Self-hosted, API-first URL shortener. Documentation covers installation via Docker or dist files, REST API authentication and error management, CLI usage, and advanced configurations including Redis/Valkey caching, reverse proxy setup, and multiple domain support. Includes guides for the Shlink Web Client and integrations with Matomo, Microsoft PowerToys, and GNOME Shell.

Tokens
20.1K
Snippets
86
Records
179
Agent score
72%

What's inside Shlink

  1. Overview of the Shlink Web Client

    The Shlink web client (shlink-web-client) is the official Progressive Web Application (PWA) for Shlink. It provides a graphical user interface for managing short URLs, creating new links, and accessing detailed, customizable visit statistics. It is designed to support all Shlink features shortly after their release.

  2. Overview of Shlink self-hosted URL shortener

    Shlink is an open-source, PHP-based self-hosted URL shortener (MIT license) that allows users to maintain control over their shortened URLs by serving them under their own domains. It provides anonymized visit statistics and visitor geolocation for every click.

  3. Overview of Shlink dynamic rule-based redirects

    Shlink 4.0.0 introduced a system to dynamically redirect visitors to different long URLs based on runtime conditions. Rules are checked sequentially by priority. If a rule matches, the visitor is redirected to that rule's long URL; otherwise, they are redirected to the default long URL. For a rule to match, all conditions within that rule must be true (AND logic).

  4. Manage short URLs with custom slugs and tags

    Shlink allows for the creation of personalized short URLs using custom slugs or multi-segment custom slugs. Users can also assign tags to short URLs to classify them for future analytics.

  5. Understand how Shlink tracks and geolocates visits

    Shlink tracks every instance a short URL is opened and attempts to geolocate the visitor using a MaxMind GeoLite2 database to match the visitor's IP address. To ensure the GeoLite2 database remains current, users must configure their own license key. For data protection compliance, Shlink stores an anonymized version of the visitor's IP address by default, though this behavior can be opted-out of.

  6. Choose a runtime for serving Shlink

    Shlink can be served using three primary runtime options. The choice depends on performance requirements, installation preference, and the need for background task processing.

    • RoadRunner: The officially recommended runtime. A Go-based PHP application server that loads Shlink into memory for high performance. It natively supports heavy background tasks such as GeoLite2 database updates and real-time updates.
    • FrankenPHP: A Go-based PHP application server with worker mode. It offers high performance and built-in HTTPS support, but does not support background tasks natively (requires separate long-running tasks configuration).
    • Classic Web Server: The traditional approach using a web server (e.g., Nginx, Apache) and FastCGI (e.g., php-fpm). It is the least performant because Shlink must bootstrap on every request, but it is a predictable option for those experienced with standard PHP hosting.

  7. Manage Shlink instances using the Command Line Interface

    Shlink provides a suite of command line tools to compensate for the lack of an integrated GUI. These tools allow developers and administrators to perform installation, update the software, and manage the Shlink instance, including creating short URLs, viewing visit statistics, and managing domains.

  8. Enable visit geolocation using GeoLite2

    Shlink uses the MaxMind GeoLite2 database to geolocate visits to short URLs. To keep the database up-to-date, Shlink requires a GeoLite2 license key. If no license key is provided, Shlink will simply not geolocate visits.

  9. Understand Shlink Docker runtime and security changes

    Starting with v4.0.0, Shlink Docker images:

    1. Run as a non-root user by default for improved security.
    2. Use RoadRunner as the default runtime. The -roadrunner tag suffix is still supported for explicit versioning.

  10. Use Redis or Valkey for shared caching and locks in Shlink

    Shlink can use a shared cache server like Redis or Valkey for three primary purposes:

    1. Caching: Persisting data in fast storage for quick access. By default, Shlink uses APCu (classic web servers) or in-memory storage (Roadrunner).
    2. Shared Locks: Ensuring tasks (like geolocating visits) do not run in parallel across multiple Shlink instances. A shared cache server is required to synchronize locks across a cluster.
    3. Real-time Updates: Publishing updates via Pub/Sub.

  11. Microsoft SQL Server limitations on ARM architecture

    The official Shlink Docker image does not include Microsoft SQL Server drivers for ARM architecture because Microsoft does not provide an official driver for this platform. If running Shlink on an ARM device, you must use a different supported database engine (e.g., MySQL, MariaDB, or PostgreSQL).

  12. Understand Shlink's API-first architecture

    Shlink is designed as a cloud-native, API-first service. It treats all user interfaces (such as shlink-web-client) as external consumers. This separation allows the core service to focus on a single responsibility, simplifying Docker image creation and Kubernetes deployment. Because it is API-first, Shlink does not manage end-user permissions or roles; these are handled by the consumer application's own backend.