The definitive self-hosted URL shortener
Find a file
Alejandro Celaya 4dc026d7fc
Merge pull request #544 from Starbix/master
Update dependencies and baseimage
2019-11-15 22:01:14 +01:00
.github Added github funding 2019-10-22 19:37:35 +02:00
bin Fixed typo 2019-11-09 12:08:22 +01:00
config Updated to installer 3.1 2019-11-10 13:07:57 +01:00
data Some more refactorings 2019-11-01 09:52:56 +01:00
docker Fixed docker docs line break 2019-11-10 12:14:00 +01:00
docs/swagger Added support for domain param to command and action to resolve a short URL 2019-10-04 21:17:02 +02:00
hooks Fixed version set during docker image build 2019-08-17 16:05:47 +02:00
module Added forward of query string from short URLs to long one 2019-11-13 21:04:44 +01:00
public Updated to coding styles v2 2019-10-05 17:26:10 +02:00
.dockerignore Updated docker image build so that it sets shlink's version 2019-08-16 19:42:39 +02:00
.env.dist Updated references to SHORTCODE_CHARS in docker docs 2019-10-11 11:41:14 +02:00
.gitattributes Added colors to tests run with phpunit 2019-08-20 18:46:33 +02:00
.gitignore Updated docker image build so that it sets shlink's version 2019-08-16 19:42:39 +02:00
.phpstorm.meta.php Fixed config file being deleted by mistake by build script 2019-01-28 10:52:05 +01:00
.scrutinizer.yml Increased scrutinizer timeout while waiting for code coverage, from 5 min to 10 min 2019-02-17 10:12:13 +01:00
.travis.yml Updated API tests script so that it throws the same exit code returned by phpunit 2019-11-09 11:25:33 +01:00
build.sh Simplified build script to exclude everything from dockerignore for rsync 2019-08-16 19:30:40 +02:00
CHANGELOG.md Updated changelog 2019-11-15 20:30:36 +01:00
composer.json Updated to installer 3.1 2019-11-10 13:07:57 +01:00
docker-compose.override.yml.dist Added mariadb container for development environment 2019-10-06 11:21:41 +02:00
docker-compose.yml Some more refactorings 2019-11-01 09:52:56 +01:00
Dockerfile Readd specific alpine version 2019-11-15 21:42:07 +01:00
indocker Removed custom AccessLogFactory by updating to zend-expressive-swoole 2.2 2018-12-05 21:26:19 +01:00
infection.json Increased MSI to 61% 2018-11-17 17:36:22 +01:00
LICENSE Happy 2019! 2019-01-05 08:41:48 +01:00
migrations.yml Created migrations to rename camel case columns to snake case 2018-10-20 09:10:27 +02:00
phpcs.xml Added all docker stuff to the project 2019-08-16 18:38:26 +02:00
phpstan.neon Updated to coding styles v2 2019-10-05 17:26:10 +02:00
phpunit-api.xml Prepared configs for API tests 2019-01-26 10:19:20 +01:00
phpunit-db.xml Updated structure for tests config files 2019-01-26 09:09:57 +01:00
phpunit.xml.dist Installed EventDispatcher module from external library 2019-08-12 20:54:30 +02:00
README.md Added MariaDB to documentation 2019-10-06 12:27:11 +02:00

Shlink

Build Status Code Coverage Scrutinizer Code Quality Latest Stable Version License Paypal donate

A PHP-based self-hosted URL shortener that can be used to serve shortened URLs under your own custom domain.

Table of Contents

Installation

First make sure the host where you are going to run shlink fulfills these requirements:

  • PHP 7.2 or greater with JSON, APCu, intl, curl, PDO and gd extensions enabled.
  • MySQL, MariaDB, PostgreSQL or SQLite.
  • The web server of your choice with PHP integration (Apache or Nginx recommended).

Then, you will need a built version of the project. There are a few ways to get it.

  • Using a dist file

    The easiest way to install shlink is by using one of the pre-bundled distributable packages.

    Just go to the latest version and download the shlink_X.X.X_dist.zip file you will find there.

    Finally, decompress the file in the location of your choice.

  • Building from sources

    If for any reason you want to build the project yourself, follow these steps:

    • Clone the project with git (git clone https://github.com/shlinkio/shlink.git), or download it by clicking the Clone or download green button.
    • Download the Composer PHP package manager inside the project folder.
    • Run ./build.sh 1.0.0, replacing the version with the version number you are going to build (the version number is only used for the generated dist file).

    After that, you will have a shlink_x.x.x_dist.zip dist file inside the build directory.

    This is the process used when releasing new shlink versions. After tagging the new version with git, the Github release is automatically created by travis, attaching generated dist file to it.

Despite how you built the project, you are going to need to install it now, by following these steps:

  • If you are going to use MySQL, MariaDB or PostgreSQL, create an empty database with the name of your choice.

  • Recursively grant write permissions to the data directory. Shlink uses it to cache some information.

  • Setup the application by running the bin/install script. It is a command line tool that will guide you through the installation process. Take into account that this tool has to be run directly on the server where you plan to host Shlink. Do not run it before uploading/moving it there.

  • Expose shlink to the web, either by using a traditional web server + fast CGI approach, or by using a swoole non-blocking server.

    • Using a web server:

      For example, assuming your domain is doma.in and shlink is in the /path/to/shlink folder, these would be the basic configurations for Nginx and Apache.

      Nginx:

      server {
          server_name doma.in;
          listen 80;
          root /path/to/shlink/public;
          index index.php;
          charset utf-8;
      
          location / {
              try_files $uri $uri/ /index.php$is_args$args;
          }
      
          location ~ \.php$ {
              fastcgi_split_path_info ^(.+\.php)(/.+)$;
              fastcgi_pass unix:/var/run/php/php7.2-fpm.sock;
              fastcgi_index index.php;
              include fastcgi.conf;
          }
      
          location ~ /\.ht {
              deny all;
          }
      }
      

      Apache:

      <VirtualHost *:80>
          ServerName doma.in
          DocumentRoot "/path/to/shlink/public"
      
          <Directory "/path/to/shlink/public">
              Options FollowSymLinks Includes ExecCGI
              AllowOverride all
              Order allow,deny
              Allow from all
          </Directory>
      </VirtualHost>
      
    • Using swoole:

      Important! Swoole support is still experimental. Use it with care, and report any found issue.

      First you need to install the swoole PHP extension with pecl, pecl install swoole.

      Once installed, it's actually pretty easy to get shlink up and running with swoole. Just run ./vendor/bin/zend-expressive-swoole start -d and you will get shlink running on port 8080.

      However, by doing it this way, you are loosing all the access logs, and the service won't be automatically run if the server has to be restarted.

      For that reason, you should create a daemon script, in /etc/init.d/shlink_swoole, like this one, replacing /path/to/shlink by the path to your shlink installation:

      #!/bin/bash
      ### BEGIN INIT INFO
      # Provides:          shlink_swoole
      # Required-Start:    $local_fs $network $named $time $syslog
      # Required-Stop:     $local_fs $network $named $time $syslog
      # Default-Start:     2 3 4 5
      # Default-Stop:      0 1 6
      # Description:       Shlink non-blocking server with swoole
      ### END INIT INFO
      
      SCRIPT=/path/to/shlink/vendor/bin/zend-expressive-swoole\ start
      RUNAS=root
      
      PIDFILE=/var/run/shlink_swoole.pid
      LOGDIR=/var/log/shlink
      LOGFILE=${LOGDIR}/shlink_swoole.log
      
      start() {
        if [[ -f "$PIDFILE" ]] && kill -0 $(cat "$PIDFILE"); then
          echo 'Shlink with swoole already running' >&2
          return 1
        fi
        echo 'Starting shlink with swoole' >&2
        mkdir -p "$LOGDIR"
        touch "$LOGFILE"
        local CMD="$SCRIPT &> \"$LOGFILE\" & echo \$!"
        su -c "$CMD" $RUNAS > "$PIDFILE"
        echo 'Shlink started' >&2
      }
      
      stop() {
        if [[ ! -f "$PIDFILE" ]] || ! kill -0 $(cat "$PIDFILE"); then
          echo 'Shlink with swoole not running' >&2
          return 1
        fi
        echo 'Stopping shlink with swoole' >&2
        kill -15 $(cat "$PIDFILE") && rm -f "$PIDFILE"
        echo 'Shlink stopped' >&2
      }
      
      case "$1" in
        start)
          start
          ;;
        stop)
          stop
          ;;
        restart)
          stop
          start
          ;;
        *)
          echo "Usage: $0 {start|stop|restart}"
      esac
      

      Then run these commands to enable the service and start it:

      • sudo chmod +x /etc/init.d/shlink_swoole
      • sudo update-rc.d shlink_swoole defaults
      • sudo update-rc.d shlink_swoole enable
      • /etc/init.d/shlink_swoole start

      Now again, you can access shlink on port 8080, but this time the service will be automatically run at system start-up, and all access logs will be written in /var/log/shlink/shlink_swoole.log (you will probably want to rotate those logs. You can find an example logrotate config file here).

  • Generate your first API key by running bin/cli api-key:generate. You will need the key in order to interact with shlink's API.

  • Finally access to https://app.shlink.io and configure your server to start creating short URLs.

Bonus

There are a couple of time-consuming tasks that shlink expects you to do manually, or at least it is recommended, since it will improve runtime performance.

Those tasks can be performed using shlink's CLI, so it should be easy to schedule them to be run in the background (for example, using cron jobs):

  • For shlink older than 1.18.0 or not using swoole as the web server: Resolve IP address locations: /path/to/shlink/bin/cli visit:locate

    If you don't run this command regularly, the stats will say all visits come from unknown locations.

  • Generate website previews: /path/to/shlink/bin/cli short-url:process-previews

    Running this will improve the performance of the doma.in/abc123/preview URLs, which return a preview of the site.

    Important! Generating previews is considered deprecated and the feature will be removed in Shlink v2.

  • For shlink older than v1.17.0: Update IP geolocation database: /path/to/shlink/bin/cli visit:update-db

    When shlink is installed it downloads a fresh GeoLite2 db file. Running this command will update this file.

    The file is updated the first Tuesday of every month, so it should be enough running this command the first Wednesday.

Any of these commands accept the -q flag, which makes it not display any output. This is recommended when configuring the commands as cron jobs.

In future versions, it is planed that, when using swoole to serve shlink, some of these tasks are automatically run without blocking the request and also, without having to configure cron jobs. Probably resolving IP locations and generating previews.

Update to new version

When a new Shlink version is available, you don't need to repeat the entire process yourself. Instead, follow these steps:

  1. Rename your existing Shlink directory to something else (ie. shlink ---> shlink-old).
  2. Download and extract the new version of Shlink, and set the directories name to that of the old version. (ie. shlink).
  3. Run the bin/update script in the new version's directory to migrate your configuration over.
  4. If you are using shlink with swoole, restart the service by running /etc/init.d/shlink_swoole restart.

The bin/update script will ask you for the location from previous shlink version, and use it in order to import the configuration. It will then update the database and generate some assets shlink needs to work.

Right now, it does not import cached info (like website previews), but it will. For now you will need to regenerate them again.

Important! It is recommended that you don't skip any version when using this process. The update gets better on every version, but older versions might make assumptions.

Using a docker image

Starting with version 1.15.0, an official docker image is provided. You can learn how to use it by reading the docs.

The idea is that you can just generate a container using the image and provide custom config via env vars.

Once shlink is installed, there are two main ways to interact with it:

  • The command line. Try running bin/cli and see all the available commands.

    All of those commands can be run with the --help/-h flag in order to see how to use them and all the available options.

    It is probably a good idea to symlink the CLI entry point (bin/cli) to somewhere in your path, so that you can run shlink from any directory.

  • The REST API. The complete docs on how to use the API can be found here, and a sandbox which also documents every endpoint can be found here.

    However, you probably don't want to consume the raw API yourself. That's why a nice web client is provided that can be directly used from https://app.shlink.io, or you can host it yourself too.

Both the API and CLI allow you to do the same operations, except for API key management, which can be done from the command line interface only.

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  help                        Displays help for a command
  list                        Lists commands
 api-key
  api-key:disable             Disables an API key.
  api-key:generate            Generates a new valid API key.
  api-key:list                Lists all the available API keys.
 config
  config:generate-charset     [DEPRECATED] Generates a character set sample just by shuffling the default one, "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ". Then it can be set in the SHORTCODE_CHARS environment variable
  config:generate-secret      [DEPRECATED] Generates a random secret string that can be used for JWT token encryption
 db
  db:create                   Creates the database needed for shlink to work. It will do nothing if the database already exists
  db:migrate                  Runs database migrations, which will ensure the shlink database is up to date.
 short-url
  short-url:delete            [short-code:delete] Deletes a short URL
  short-url:generate          [shortcode:generate|short-code:generate] Generates a short URL for provided long URL and returns it
  short-url:list              [shortcode:list|short-code:list] List all short URLs
  short-url:parse             [shortcode:parse|short-code:parse] Returns the long URL behind a short code
  short-url:process-previews  [shortcode:process-previews|short-code:process-previews] [DEPRECATED] Processes and generates the previews for every URL, improving performance for later web requests.
  short-url:visits            [shortcode:visits|short-code:visits] Returns the detailed visits information for provided short code
 tag
  tag:create                  Creates one or more tags.
  tag:delete                  Deletes one or more tags.
  tag:list                    Lists existing tags.
  tag:rename                  Renames one existing tag.
 visit
  visit:locate                [visit:process] Resolves visits origin locations.
  visit:update-db             [DEPRECATED] Updates the GeoLite2 database file used to geolocate IP addresses

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com