Shlink ile Kendi URL Kısaltıcınızı Kurun
Shlink ve Docker Compose kullanarak kendi VPS sunucunuzda URL kısaltıcı oluşturun. DNS ayarları, Postgres veritabanı, API anahtarları ve detaylı tıklama istatistikleri.
Ne inşa ediyorsunuz
Kendi kendine barındırılan (self-hosted) bir URL kısaltıcı, uzun bir bağlantıyı size ait kısa bir bağlantıya dönüştüren ve her tıklamayı sayan küçük bir sunucudur. Shlink bu iş için en uygun tercihtir: açık kaynaklıdır, Docker imajı olarak dağıtılır ve tüm işi bir container ile bir veritabanı üzerinde gerçekleştirir. Bu kılavuz, Shlink'i bir VPS üzerinde, gerçek bir kısa alan adı arkasında, HTTPS, API anahtarı, QR kodları ve tıklama istatistikleri ile yapılandırmanızı sağlar.
İki bileşen, sistemin ticari bir kısaltıcı gibi çalışmasını sağlar. API sunucusu yönlendirmelere yanıt verir ve verileri tutar. Web istemcisi ise tarayıcınızdan bu API ile iletişim kuran ayrı bir statik uygulamadır. Her ikisini de çalıştırabilir veya yalnızca API'yi çalıştırıp komut satırı üzerinden yönetebilirsiniz.
Buradaki sürüm numaraları 19 Kasım 2026 itibarıyla güncel olanlardır: Shlink 5.1.8 ve shlink-web-client 4.9.0.
Önce kısa alan adını sunucuya yönlendirin
Alan adı ürünün kendisidir. s.example.com/abc123 insanların göreceği bağlantıdır, bu nedenle kısa bir isim seçin ve herhangi bir kurulum yapmadan önce bu seçimi tamamlayın. Shlink her kısa URL'yi varsayılan alan adı veya özel olarak atanmış bir alan adı ile ilişkilendirir. Alan adını daha sonra değiştirmek, eski alan adını Shlink'e yönlendirmeye devam etmenizi gerektirir; aksi takdirde paylaştığınız bağlantılar çalışmaz hale gelir.
Kısa alan adınız için VPS genel IPv4 adresinize işaret eden bir adet DNS A kaydı oluşturun. Sunucunuzda IPv6 varsa bir AAAA kaydı da ekleyin. Ardından devam etmeden önce çözümleme yapıldığını doğrulayın.
dig +short s.example.com AÇıktı, sunucunuzun adresi olmalıdır. Eğer çıktı boşsa kayıt henüz yayılmamıştır. Bu durumda sonraki tüm adımlar karmaşık hatalar verecektir; çünkü çözümleme yapmayan bir isim için TLS (transport layer security) sertifikası düzenlenemez.
Compose dosyası
Shlink bir veritabanına ihtiyaç duyar. SQLite test için uygundur ancak kalıcı olması planlanan her yapı için Postgres doğru tercihtir; çünkü ziyaret kayıtları birikir ve Postgres, indeksleri ve eş zamanlı yazma işlemlerini daha iyi yönetir. Bunu /opt/shlink/compose.yaml içine yerleştirin.
services:
shlink:
image: shlinkio/shlink:stable
restart: unless-stopped
ports:
- "127.0.0.1:8080:8080"
environment:
DEFAULT_DOMAIN: s.example.com
IS_HTTPS_ENABLED: "true"
DB_DRIVER: postgres
DB_HOST: database
DB_NAME: shlink
DB_USER: shlink
DB_PASSWORD: ${DB_PASSWORD}
depends_on:
- database
database:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_DB: shlink
POSTGRES_USER: shlink
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- shlink_db:/var/lib/postgresql/data
web-client:
image: shlinkio/shlink-web-client:stable
restart: unless-stopped
ports:
- "127.0.0.1:8081:8080"
volumes:
shlink_db:Her iki yayınlanan port da 127.0.0.1 adresine bağlanır, bu nedenle bir sonraki bölümde yer alan reverse proxy kurulana kadar internet üzerinden hiçbir şeye erişilemez. Docker, kendi yönlendirme kurallarını ana makine güvenlik duvarının önüne yazar; bu da basit bir 8080:8080 satırının, güvenlik duvarı kapalı görünen bir sunucuda bile uygulamayı dış dünyaya açacağı anlamına gelir. Loopback adresine bağlamak bu durumu önler. Aynı yöntem bu şekilde çalıştırdığınız tüm uygulamalar için geçerlidir ve VPS üzerinde Docker Compose rehberi içerisinde daha ayrıntılı olarak ele alınmıştır.
Veritabanı parolası, compose dosyasının yanındaki bir .env dosyasından gelir, böylece YAML dosyasına asla yazılmaz.
sudo mkdir -p /opt/shlink
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" | sudo tee /opt/shlink/.env
sudo chmod 600 /opt/shlink/.envServisi başlatın ve API'nin ayağa kalkışını izleyin.
cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlinkİlk başlatma veritabanı migrasyonlarını çalıştırır, bu nedenle sonraki başlatmalardan daha uzun sürer. Servis kararlı hale geldiğinde, yerel olarak yanıt verip vermediğini kontrol edin.
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/healthBir 200, API'nin canlı olduğunu ve veritabanı bağlantısının çalıştığını gösterir. Bir 503, Shlink'in çalıştığını ancak veritabanı kontrolünün başarısız olduğunu belirtir. Sağlık kontrolü uç noktası, herhangi bir veritabanı hatası için 503 yanıtını verir, asla 500 vermez. Eğer curl 000 çıktısı verirse, herhangi bir HTTP yanıt kodu alınamamış demektir; konteynerin durup durmadığını veya yeniden başlatılıp başlatılmadığını anlamadan önce bağlantıyı ve yukarıdaki logları kontrol edin. Loglar bir veritabanı kimlik doğrulama hatası gösteriyorsa, .env içindeki DB_PASSWORD değerinin Postgres oluşturulurken kullanılanla eşleştiğinden emin olun; çünkü Postgres imajı POSTGRES_PASSWORD dosyasını yalnızca boş bir veri dizinini ilk kez başlatırken okur. .env dosyasını daha sonra düzenlemek mevcut veritabanı parolasını değiştirmez; veritabanı rolünün parolasını da değiştirin veya mevcut parolayı .env içine geri yazın.
HTTPS sonlandırmasını ön tarafta yapma
Shlink, 8080 numaralı port üzerinden düz HTTP sunar. TLS işlemi bir reverse proxy üzerinde yapılmalıdır; bu noktada önemli olan tek ayar, orijinal ana makine (host) adının iletilmesidir. Shlink, kısa kodları aramak için Host başlığını kullanır ve varsayılan alan adındaki bağlantılarla eşleşme sağlanamazsa geri dönüş (fallback) mekanizmasını devreye sokar. Bu nedenle, yeniden yazılmış bir host adı yanlış bağlantının seçilmesine veya yalnızca başka bir alan adında var olan bir kod için 404 hatası dönülmesine neden olabilir.
server {
server_name s.example.com;
listen 80;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Ardından sertifikayı oluşturun. Yenileme zamanlayıcısı da dahil olmak üzere adım adım kılavuz için Ubuntu 24.04 üzerinde nginx için Certbot rehberi bölümüne bakabilirsiniz.
sudo certbot --nginx -d s.example.comCompose dosyasındaki IS_HTTPS_ENABLED: "true" ayarı, Shlink'in döndürdüğü kısa URL'lerde https:// yazdırmasını sağlar. Bu ayar tek başına TLS'i etkinleştirmez. Bunu bir HTTPS proxy'sinin arkasında false olarak bırakırsanız, API'nin döndürdüğü her bağlantı bir http:// bağlantısı olur ve ardından yönlendirme yapar. Bu durum fazladan bir gidiş-dönüş süresine (round trip) neden olur ve web istemcisinde hatalı görünür.
API anahtarı oluşturma
Yönetim API'si bir anahtara ihtiyaç duyar; sağlık durumu uç noktası herkese açıktır. Anahtarı container içindeki CLI aracılığıyla oluşturun.
sudo docker compose exec shlink shlink api-key:generate --name "web client"Komut, anahtarı yalnızca bir kez ekrana yazdırır. Anahtar hash'lenmiş olarak saklandığı ve tekrar gösterilemeyeceği için hemen kopyalayın. shlink api-key:list, anahtarların isimlerini ve etkin olup olmadıklarını listeler ancak anahtarın kendisini göstermez. Bir anahtarı iptal etmek için shlink api-key:disable komutunu ve anahtar ismini kullanın.
REST yönetim çağrıları için anahtarı X-Api-Key başlığı içerisinde gönderin.
curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urlsshortUrls anahtarına sahip bir JSON nesnesi, anahtarın çalıştığı anlamına gelir. type değeri https://shlink.io/api/error/invalid-api-key olan ve Invalid API key başlığını taşıyan bir 401, anahtarın hatalı, devre dışı veya süresinin dolmuş olduğu anlamına gelir.
Komut satırından kısa bağlantılar oluşturma
CLI, bağlantı oluşturmanın en hızlı yoludur ve betiklerle (script) uyumlu çalışır.
sudo docker compose exec shlink shlink short-url:create https://example.com/a/very/long/path
sudo docker compose exec shlink shlink short-url:create https://example.com/docs --custom-slug docs --tag reference--custom-slug, oluşturulan bir kod yerine okunabilir bir bağlantı sağlar. Slug'lar her alan adı için benzersizdir; bu nedenle halihazırda alınmış bir slug üzerinde ikinci bir deneme yapıldığında, ilk bağlantının üzerine sessizce yazmak yerine işlem başarısız olur. --tag tekrarlanabilir ve etiketler (tags), daha sonra toplu istatistiklerini görmek isteyeceğiniz bağlantıları gruplandırmanızı sağlar.
Mevcut olanları listeleyin, ardından bir bağlantının trafiğini inceleyin.
sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docsshort-url:visits, her tıklama için tarih, yönlendiren (referrer) ve kullanıcı aracısı (user agent) bilgilerini içeren bir satır yazdırır. Ülke ve şehir sütunları, bir GEOLITE_LICENSE_KEY ortam değişkeni tanımlamadığınız sürece boş kalır. Bu değişken, Shlink'in GeoLite2 veritabanını indirmek için kullandığı ücretsiz bir MaxMind anahtarıdır. Bu anahtar olmadan ziyaretler kaydedilmeye devam eder, ancak konum bilgisi alınamaz.
Web istemcisi ve QR kodları
Web istemcisi artık 127.0.0.1:8081 adresinde yer almaktadır ve kendi proxy girişine ihtiyaç duyar; eğer dış dünyaya açmak istemiyorsanız bir SSH tüneli de kullanabilirsiniz. İlk yüklemede bir sunucu URL'si ve bir API anahtarı ister. https://s.example.com adresini ve oluşturduğunuz anahtarı girin. İstemci her ikisini de tarayıcı depolama alanında tutar ve API'nizi doğrudan çağırır, bu nedenle veriler başka bir tarafa aktarılmaz. Arayüzü API'den ayırmak dikkat çekici bir yöntemdir; çünkü bu, Halcyon'un bir Jellyfin kütüphanesini 1990'ların video kiralama dükkanı gibi göstermesini sağlayan yöntemle aynıdır ve arka plandaki medya sunucusunda herhangi bir değişiklik gerektirmez.
QR kodları API'den değil, web istemcisinden gelir. Shlink 5, kısa bir URL'nin sonuna /qr-code ekleme şeklindeki eski yöntemi kaldırmıştır, bu nedenle bu adres artık bir görsel döndürmez. Web istemcisi, Shlink'e herhangi bir istek göndermeden kodu doğrudan tarayıcınızda çizer. Kısa URL listesindeki herhangi bir bağlantıda QR kodu seçeneğini açın, boyutu, formatı ve kenar boşluğunu ayarlayın ve sonucu indirin. Küçük boyutlarda basıldığında veya kısmen kapandığında bile taranabilmesi için hata düzeltme seviyesini yükseltin. Aynı iletişim kutusu üzerinden renkler ve logo da eklenebilir.
Servisi çalışır durumda tutma
Bir kısaltıcı sessizce başarısız olabilir. Bağlantılar yönlendirmeyi durdurur ve kimse size haber vermez, çünkü bağlantıya tıklayan kişi bağlantının ölü olduğunu varsayar. Uptime kontrolünü ana sayfa yerine gerçek bir kısa URL'ye yönlendirin ve yönlendirme dışındaki her türlü durumda uyarı alın. Self-hosted bir Uptime Kuma örneği bu işi iyi yapar ve belirli bir durum kodunu izleyebilir.
Container'ı değil, veritabanını yedekleyin. Tek bir komut ile dump alınabilir.
sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gzBu dosya, compose dosyanız ve .env ile birlikte tüm servisi yeni bir sunucuda yeniden oluşturur. Sunucudaki her uygulamanın bu yedekten kendi sürümüne ihtiyacı vardır. Fotoğraf kütüphaneleri ise zorlu bir durumdur; çünkü PhotoPrism ve Immich hem orijinalleri diskte tutar hem de veritabanında satırlar barındırır. Bu nedenle sadece dump almak veritabanı kayıtlarını geri getirir ancak tek bir fotoğrafı veya PhotoPrism'in dosya tabanlı ayarlarını geri getirmez. Kullanıcı arayüzü, indirme ve indeksleme tercihlerini tutan settings.yml dosyası dahil olmak üzere PhotoPrism yapılandırmasını da yedekleyin. Yükseltmeler sudo docker compose pull ve ardından sudo docker compose up -d ile yapılır; Shlink ise başlangıçta tüm yeni migrasyonları çalıştırır. Migrasyon geri alınamayacağı için pull işleminden önce dump alın.
FAQ
Neden bir reverse proxy ekledikten sonra kısa bağlantılarım 404 hatası veriyor?
Shlink, kısa kodu Host başlığındaki alan adıyla eşleştirir. Proxy farklı bir host gönderirse, Shlink o alan adını kontrol eder ve ardından varsayılan alan adı bağlantısıyla eşleşmeye çalışır; kod ikisinde de bulunamazsa 404 hatası döner. Nginx location bloğunda proxy_set_header Host $host; ayarını yapın ve proxy'yi yeniden yükleyin. Bağlantılar, container'ı yeniden başlatmaya gerek kalmadan hemen çalışmaya başlar.
Postgres kullanmam gerekiyor mu, yoksa SQLite yeterli mi?
SQLite, Shlink'i denemek için uygundur ve ikinci bir container gerektirmez. Önemli bağlantılar yayınlamadan önce Postgres'e geçin; çünkü her tıklamada ziyaret satırları artar ve SQLite yazma işlemlerini sıraya koyar (serialize). Daha sonra geçiş yapmak, bağlantılarınızı dışa aktarıp yeniden içe aktarmanızı gerektirir; bu nedenle başlangıçta Postgres seçmek sizi bu göç işleminden kurtarır.
Kopyalamayı unuttuğum bir API anahtarını kurtarabilir miyim?
Hayır. Shlink anahtarın bir özetini (hash) saklar, bu nedenle api-key:list yalnızca isimleri ve durumu gösterir, değeri asla göstermez. shlink api-key:generate ile yeni bir tane oluşturun, web istemcisine yapıştırın ve ardından eskisini shlink api-key:disable ile devre dışı bırakarak çalışmasını durdurun.
Ziyaret istatistiklerimde neden ülke sütunları boş?
Coğrafi konum belirleme, Shlink'in yalnızca GEOLITE_LICENSE_KEY sağladığınızda indirdiği GeoLite2 veritabanına ihtiyaç duyar. Anahtar, MaxMind'dan ücretsiz alınabilir. Bunu environment bölümüne ekleyin, container'ı yeniden oluşturun; yeni ziyaretler konumlandırılacaktır. Bundan önce kaydedilen ziyaretler, shlink visit:locate komutunu çalıştırana kadar boş kalacaktır.
Shlink'i farklı bir sunucuya nasıl taşırım?
Alan adını koruyun ve verileri taşıyın. Veritabanını pg_dump ile dışa aktarın (dump), dump dosyasını, compose dosyasını ve .env dosyasını yeni sunucuya kopyalayın, yalnızca veritabanını başlatın, dump dosyasını boş veritabanına geri yükleyin, ardından gerçek trafik gelmeden önce Shlink ve web istemcisini başlatın. DNS kaydını en son değiştirin. Kısa kodlar ve ziyaret geçmişleri korunur, çünkü her şey veritabanında saklanır.