Shlink ఉపయోగించి సొంత URL షార్టనర్ ఎలా తయారు చేయాలి?

మీరు ఏమి నిర్మిస్తున్నారు

Self-hosted URL shortener అనేది ఒక చిన్న సర్వర్. ఇది పొడవైన లింక్‌ను మీరు సొంతం చేసుకున్న చిన్న లింక్‌గా మారుస్తుంది మరియు ప్రతి క్లిక్‌ను లెక్కిస్తుంది. దీని కోసం Shlink ఉత్తమమైనది: ఇది open source, Docker image రూపంలో లభిస్తుంది, మరియు ఒక container మరియు database తో మొత్తం పనిని పూర్తి చేస్తుంది. ఈ గైడ్ దీనిని ఒక VPS లో, సరైన short domain తో, HTTPS, API key, QR codes మరియు click stats తో సహా అమర్చడాన్ని వివరిస్తుంది.

రెండు భాగాలు దీనిని ఒక commercial shortener లాగా పనిచేసేలా చేస్తాయి. API server రీడైరెక్ట్‌లకు సమాధానమిస్తుంది మరియు డేటాను నిల్వ చేస్తుంది. Web client అనేది ఒక ప్రత్యేకమైన static app, ఇది మీ బ్రౌజర్ నుండి ఆ API తో కమ్యూనికేట్ చేస్తుంది. మీరు రెండింటినీ రన్ చేయవచ్చు, లేదా కేవలం API ని మాత్రమే రన్ చేసి command line ద్వారా కూడా నిర్వహించవచ్చు.

ఇక్కడ పేర్కొన్న version సంఖ్యలు జూలై 2026 నాటికి ప్రస్తుతమున్నవి: Shlink 5.1 మరియు shlink-web-client 4.8.

ముందుగా సర్వర్‌కు ఒక చిన్న డొమైన్‌ను పాయింట్ చేయండి

డొమైన్ అనేది ఈ ఉత్పత్తికి కీలకం. s.example.com/abc123 అనేది వినియోగదారులు చూసే లింక్, కాబట్టి ఏదైనా ఇన్‌స్టాల్ చేసే ముందే చిన్నగా ఉండే ఒక పేరును ఎంచుకోండి. Shlink ప్రతి short URLతో పాటు డొమైన్‌ను కూడా స్టోర్ చేస్తుంది. కాబట్టి, తర్వాత డొమైన్‌ను మార్చడం వల్ల మీరు ఇప్పటికే పంపిణీ చేసిన అన్ని లింకులు పనిచేయకుండా పోతాయి.

మీ VPS యొక్క పబ్లిక్ IPv4 అడ్రస్‌ను సూచిస్తూ, ఆ చిన్న డొమైన్ కోసం ఒక DNS A రికార్డును సృష్టించండి. సర్వర్‌కు IPv6 ఉంటే, ఒక AAAA రికార్డును కూడా జోడించండి. ఆ తర్వాత, మీరు ముందుకు వెళ్లే ముందు అది resolve అవుతుందో లేదో నిర్ధారించుకోండి.

dig +short s.example.com A

దీని అవుట్‌పుట్ మీ సర్వర్ అడ్రస్‌ను చూపాలి. ఒకవేళ అది ఖాళీగా ఉంటే, ఆ రికార్డు ఇంకా propagate కాలేదని అర్థం. అటువంటప్పుడు, తర్వాతి దశలన్నీ గందరగోళంగా విఫలమవుతాయి, ఎందుకంటే resolve కాని పేరుకు TLS (transport layer security) సర్టిఫికేట్‌ను జారీ చేయడం సాధ్యం కాదు.

Compose ఫైల్

Shlink కు ఒక డేటాబేస్ అవసరం. పరీక్షల కోసం SQLite సరిపోతుంది, కానీ మీరు భవిష్యత్తులో కూడా ఉపయోగించాలనుకుంటే Postgres సరైన ఎంపిక. ఎందుకంటే సందర్శనల సంఖ్య పెరిగేకొద్దీ, Postgres ఇండెక్స్‌లను మరియు ఏకకాలంలో జరిగే రైట్ ఆపరేషన్లను మెరుగ్గా నిర్వహించగలదు. దీన్ని /opt/shlink/compose.yaml లో ఉంచండి.

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:

రెండు పబ్లిష్ చేసిన పోర్ట్‌లు 127.0.0.1 కి బైండ్ అవుతాయి, కాబట్టి తదుపరి విభాగంలో రివర్స్ ప్రాక్సీని అమర్చే వరకు ఇంటర్నెట్ నుండి ఏదీ అందుబాటులో ఉండదు. Docker తన సొంత ఫార్వార్డింగ్ రూల్స్‌ను హోస్ట్ ఫైర్‌వాల్ కంటే ముందుగా రాస్తుంది. అంటే, ఒక సాధారణ 8080:8080 లైన్ ఫైర్‌వాల్ క్లోజ్డ్ అని కనిపించే సర్వర్‌లో కూడా అప్లికేషన్‌ను బయట ప్రపంచానికి బహిర్గతం చేస్తుంది. లూప్‌బ్యాక్ అడ్రస్‌కు బైండ్ చేయడం వల్ల ఈ సమస్య ఉండదు. ఈ పద్ధతి మీరు ఈ విధంగా రన్ చేసే ప్రతి అప్లికేషన్‌కు వర్తిస్తుంది. దీని గురించి మరిన్ని వివరాలు VPS పై Docker Compose గైడ్ లో ఉన్నాయి.

డేటాబేస్ పాస్‌వర్డ్ compose ఫైల్ పక్కన ఉన్న ఒక .env ఫైల్ నుండి వస్తుంది, కాబట్టి అది ఎప్పటికీ YAML లో ఉండదు.

sudo mkdir -p /opt/shlink
printf 'DB_PASSWORD=%s\n' "$(openssl rand -base64 24)" | sudo tee /opt/shlink/.env
sudo chmod 600 /opt/shlink/.env

దీన్ని ప్రారంభించి API అందుబాటులోకి వస్తుందో లేదో గమనించండి.

cd /opt/shlink
sudo docker compose up -d
sudo docker compose logs -f shlink

మొదటిసారి ప్రారంభించినప్పుడు డేటాబేస్ మైగ్రేషన్లు జరుగుతాయి, కాబట్టి తర్వాత కంటే దీనికి ఎక్కువ సమయం పడుతుంది. ఇది స్థిరపడిన తర్వాత, సేవ స్థానికంగా స్పందిస్తుందో లేదో తనిఖీ చేయండి.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/rest/health

ఒక 200 అంటే API పని చేస్తోందని మరియు డేటాబేస్ కనెక్షన్ సరిగ్గా ఉందని అర్థం. ఇక్కడ ఒక 500 వస్తే, అది దాదాపు ఎప్పుడూ డేటాబేస్ సమస్యే అవుతుంది: .env లోని DB_PASSWORD, Postgres సృష్టించబడినప్పుడు ఉన్న దానితో సరిపోలడం లేదు. ఎందుకంటే Postgres ఇమేజ్ ఖాళీ డేటా డైరెక్టరీని ప్రారంభించేటప్పుడు మాత్రమే POSTGRES_PASSWORD ని చదువుతుంది. మీరు వాల్యూమ్‌ను తొలగించి మళ్లీ ప్రారంభించే వరకు, తర్వాత పాస్‌వర్డ్‌ను ఎడిట్ చేసినా ఎటువంటి ఫలితం ఉండదు.

దీని ముందు HTTPS ను ముగించండి (Terminate)

Shlink పోర్ట్ 8080 పై plain HTTPని అందిస్తుంది. TLS అనేది ఒక reverse proxy బాధ్యత, మరియు ఇక్కడ ముఖ్యమైన సెట్టింగ్ ఏమిటంటే అసలైన host name ను అలాగే పంపడం. Shlink ఒక short code ఏ domain కు చెందినదో నిర్ణయించడానికి Host header ను చదువుతుంది, కాబట్టి దానిని మార్చే (rewrite చేసే) proxy ఉంటే, ఉన్న లింక్‌లకు కూడా 404 responses వస్తాయి మరియు visit stats తప్పు domain కు అనుసంధానించబడతాయి.

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;
    }
}

ఆ తర్వాత certificate ను జారీ చేయండి. Renewal timer తో సహా పూర్తి వివరాలు Ubuntu 24.04 లో nginx కోసం Certbot గైడ్ లో ఉన్నాయి.

sudo certbot --nginx -d s.example.com

compose ఫైల్‌లోని IS_HTTPS_ENABLED: "true" అనేది Shlink తిరిగి ఇచ్చే short URLs లో https:// వచ్చేలా చేస్తుంది. ఇది స్వయంగా TLS ను ఎనేబుల్ చేయదు. దీనిని HTTPS proxy వెనుక false గా ఉంచితే, API ఇచ్చే ప్రతి లింక్ ఒక http:// లింక్ అవుతుంది, ఇది మళ్ళీ redirect అవుతుంది. దీనివల్ల అదనపు round trip సమయం పడుతుంది మరియు web client లో ఇది తప్పుగా కనిపిస్తుంది.

API కీని సృష్టించడం

కీ లేకుండా ఏదీ APIతో కమ్యూనికేట్ చేయలేదు. కంటైనర్ లోపల CLI ద్వారా ఒక కీని రూపొందించండి.

sudo docker compose exec shlink shlink api-key:generate --name "web client"

ఈ కమాండ్ కీని ఒకసారి మాత్రమే ప్రింట్ చేస్తుంది. దీన్ని వెంటనే కాపీ చేసుకోండి, ఎందుకంటే ఇది హ్యాష్ చేయబడి నిల్వ చేయబడుతుంది మరియు మళ్ళీ చూపబడదు. shlink api-key:list ప్రతి కీ పేరును మరియు అది ఎనేబుల్ చేయబడిందో లేదో చూపిస్తుంది, కానీ కీని ఎప్పటికీ చూపదు. shlink api-key:disable మరియు కీ పేరును ఉపయోగించి ఒక కీని రద్దు చేయవచ్చు.

ప్రతి REST కాల్ కీని X-Api-Key హెడర్‌లో కలిగి ఉంటుంది.

curl -H "X-Api-Key: YOUR_KEY" https://s.example.com/rest/v3/short-urls

shortUrls కీ ఉన్న JSON ఆబ్జెక్ట్ అంటే కీ పనిచేస్తుందని అర్థం. INVALID_API_KEYని కలిగి ఉన్న 401 అంటే కీ తప్పుగా ఉందని, డిసేబుల్ చేయబడిందని లేదా దాని గడువు ముగిసిందని అర్థం.

కమాండ్ లైన్ నుండి షార్ట్ లింక్‌లను సృష్టించడం

లింక్‌లను తయారు చేయడానికి CLI అత్యంత వేగవంతమైన మార్గం, మరియు ఇది స్క్రిప్ట్‌లకు బాగా ఉపయోగపడుతుంది.

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 మీకు జనరేట్ చేయబడిన కోడ్‌కు బదులుగా చదవగలిగే లింక్‌ను ఇస్తుంది. స్లగ్‌లు (slugs) ప్రతి డొమైన్‌కు ప్రత్యేకంగా ఉంటాయి, కాబట్టి ఇప్పటికే ఉన్న స్లగ్‌ను మళ్ళీ ఉపయోగించడానికి ప్రయత్నిస్తే అది విఫలమవుతుంది; అంతే తప్ప మొదటి లింక్‌ను నిశ్శబ్దంగా ఓవర్‌రైట్ చేయదు. --tag ను మళ్ళీ మళ్ళీ ఉపయోగించవచ్చు, మరియు మీరు తర్వాత కలిపి గణాంకాలను చూడాలనుకునే లింక్‌లను ట్యాగ్‌ల (tags) ద్వారా సమూహపరచవచ్చు.

ఏమి ఉన్నాయో జాబితా చేయండి, ఆపై ఒక లింక్ యొక్క ట్రాఫిక్‌ను పరిశీలించండి.

sudo docker compose exec shlink shlink short-url:list
sudo docker compose exec shlink shlink short-url:visits docs

short-url:visits ప్రతి క్లిక్‌కు ఒక వరుసను ప్రింట్ చేస్తుంది, అందులో తేదీ, రిఫరర్ (referrer) మరియు యూజర్ ఏజెంట్ (user agent) ఉంటాయి. మీరు GEOLITE_LICENSE_KEY ఎన్విరాన్‌మెంట్ వేరియబుల్‌ను సెట్ చేయకపోతే దేశం మరియు నగరం కాలమ్‌లు ఖాళీగా ఉంటాయి. ఇది Shlink ఉపయోగించే ఉచిత MaxMind కీ, దీని ద్వారా GeoLite2 డేటాబేస్‌ను డౌన్‌లోడ్ చేసుకుంటుంది. ఇది లేకపోయినా సందర్శనలు రికార్డ్ చేయబడతాయి, కేవలం వాటి భౌగోళిక స్థానం మాత్రం నమోదు కాదు.

వెబ్ క్లయింట్ మరియు QR కోడ్‌లు

వెబ్ క్లయింట్ ఇప్పుడు 127.0.0.1:8081 వద్ద ఉంది మరియు దీనికి ప్రత్యేకమైన proxy ఎంట్రీ అవసరం, లేదా మీరు దీన్ని పబ్లిష్ చేయకూడదనుకుంటే SSH tunnel ను ఉపయోగించవచ్చు. మొదటిసారి లోడ్ అయినప్పుడు ఇది సర్వర్ URL మరియు API key ని అడుగుతుంది. https://s.example.com మరియు మీరు రూపొందించిన కీని నమోదు చేయండి. క్లయింట్ ఈ రెండింటినీ బ్రౌజర్ స్టోరేజ్‌లో ఉంచుకుని నేరుగా మీ APIని కాల్ చేస్తుంది, కాబట్టి డేటా ఎవరికీ చేరదు. ఇంటర్‌ఫేస్‌ను API నుండి వేరు చేయడం గమనించదగ్గ పద్ధతి, ఎందుకంటే ఇదే పద్ధతిని ఉపయోగించి Halcyon ఒక Jellyfin లైబ్రరీని 1990ల నాటి అద్దె దుకాణంలా మార్చగలుగుతుంది, దీని కోసం వెనుక ఉన్న మీడియా సర్వర్‌లో ఎటువంటి మార్పులు చేయాల్సిన అవసరం లేదు.

QR కోడ్‌లకు ఎటువంటి కాన్ఫిగరేషన్ అవసరం లేదు. ఏదైనా short URL చివరన /qr-code ని జోడిస్తే, API ఆ చిత్రాన్ని అందిస్తుంది.

https://s.example.com/docs/qr-code?size=500&format=svg&margin=20

size అనేది పిక్సెల్‌లలో వెడల్పును సూచిస్తుంది మరియు ఇది 50 నుండి 1000 వరకు విలువలను తీసుకుంటుంది, డిఫాల్ట్‌గా 300 ఉంటుంది. format అనేది png లేదా svg. margin అనేది కోడ్ చుట్టూ ఉండే ఖాళీ స్థలం (పిక్సెల్‌లలో), మరియు పూర్తయిన చిత్రం యొక్క పరిమాణం, కోడ్ పరిమాణం మరియు మార్జిన్‌కు రెట్టింపు మొత్తానికి సమానంగా ఉంటుంది. చిన్నగా ప్రింట్ చేసినప్పుడు లేదా పాక్షికంగా కప్పబడినప్పుడు కూడా స్కాన్ అయ్యే కోడ్ కోసం errorCorrection=Q ని జోడించండి.

సేవను నిరంతరం అందుబాటులో ఉంచడం

ఒక shortener నిశ్శబ్దంగా విఫలం కావచ్చు. లింకులు redirect అవ్వడం ఆగిపోతాయి, కానీ ఎవరూ మీకు ఫిర్యాదు చేయరు, ఎందుకంటే ఆ లింక్ పని చేయడం లేదని క్లిక్ చేసిన వారు భావిస్తారు. హోమ్ పేజీకి బదులుగా, నిజమైన short URL కి uptime check ను సెట్ చేయండి. redirect కాకుండా మరే ఇతర ఫలితం వచ్చినా alert వచ్చేలా చూడండి. ఒక self-hosted Uptime Kuma instance ఈ పనిని సమర్థవంతంగా చేస్తుంది, ఇది నిర్దిష్ట status code కోసం పర్యవేక్షించగలదు.

container ను కాకుండా, database ను backup తీసుకోండి. ఒకే కమాండ్‌తో దీన్ని dump చేయవచ్చు.

sudo docker compose exec -T database pg_dump -U shlink shlink | gzip > shlink-$(date +%F).sql.gz

ఆ ఫైల్ మరియు మీ compose ఫైల్ ఉంటే, కొత్త సర్వర్‌లో మొత్తం సేవను తిరిగి నిర్మించవచ్చు. సర్వర్‌లోని ప్రతి అప్లికేషన్‌కు అటువంటి జంట ఫైళ్లు అవసరం. ఫోటో లైబ్రరీ విషయంలో ఇది కొంచెం క్లిష్టంగా ఉంటుంది, ఎందుకంటే PhotoPrism మరియు Immich రెండూ ఒరిజినల్ ఫైళ్లను డిస్క్‌లోనూ, సమాచారాన్ని database లోనూ భద్రపరుస్తాయి. కాబట్టి కేవలం database dump తో ఏమీ పునరుద్ధరించలేము. అప్‌గ్రేడ్లు చేసేటప్పుడు ముందుగా sudo docker compose pull, ఆ తర్వాత sudo docker compose up -d చేయాలి. Shlink ప్రారంభమైనప్పుడు కొత్త migrations ఏవైనా ఉంటే వాటిని స్వయంచాలకంగా అమలు చేస్తుంది. మీరు pull చేసే ముందే dump తీసుకోండి, ఎందుకంటే migration జరిగిన తర్వాత దాన్ని వెనక్కి తీసుకోవడం (rollback) సాధ్యం కాదు.

FAQ

రివర్స్ ప్రాక్సీని జోడించిన తర్వాత నా షార్ట్ లింకులు ఎందుకు 404 ఎర్రర్‌ను చూపుతున్నాయి?

Shlink అనేది Host హెడర్‌లోని డొమైన్‌తో షార్ట్ కోడ్‌ను సరిపోల్చుతుంది. ప్రాక్సీ తన సొంత పేరును లేదా అంతర్గత అడ్రస్‌ను పంపినప్పుడు, Shlink ఆ కోడ్ కోసం లింకులు లేని డొమైన్‌లో వెతుకుతుంది, అందుకే అది 404 అని సమాధానం ఇస్తుంది. nginx లొకేషన్ బ్లాక్‌లో proxy_set_header Host $host;ని సెట్ చేసి, ప్రాక్సీని రీలోడ్ చేయండి. కంటైనర్‌ను రీస్టార్ట్ చేయాల్సిన అవసరం లేకుండానే లింకులు వెంటనే పనిచేయడం ప్రారంభిస్తాయి.

నాకు Postgres అవసరమా, లేక SQLite సరిపోతుందా?

Shlinkని పరీక్షించి చూడటానికి SQLite సరిపోతుంది మరియు దీనికి రెండవ కంటైనర్ అవసరం లేదు. మీరు ముఖ్యమైన లింకులను పబ్లిష్ చేసే ముందు Postgresకి మారండి, ఎందుకంటే ప్రతి క్లిక్‌తో విజిట్ రోస్ (visit rows) పెరుగుతాయి మరియు SQLite రైట్స్ (writes) ను సీరియలైజ్ చేస్తుంది. తర్వాత మారడం అంటే మీ లింకులను ఎగుమతి చేసి మళ్లీ దిగుమతి చేసుకోవడం, కాబట్టి ప్రారంభంలోనే Postgresని ఎంచుకోవడం వల్ల ఆ మైగ్రేషన్ శ్రమ తప్పుతుంది.

నేను కాపీ చేయడం మర్చిపోయిన API కీని తిరిగి పొందవచ్చా?

లేదు. Shlink కీ యొక్క హ్యాష్‌ను మాత్రమే నిల్వ చేస్తుంది, కాబట్టి api-key:list పేర్లను మరియు స్థితిని చూపుతుంది కానీ కీ విలువను ఎప్పటికీ చూపదు. shlink api-key:generate తో కొత్త కీని జనరేట్ చేయండి, దానిని వెబ్ క్లయింట్‌లో పేస్ట్ చేయండి, ఆపై పాత కీని shlink api-key:disable తో డిసేబుల్ చేయండి, తద్వారా అది పనిచేయడం ఆగిపోతుంది.

నా విజిట్ గణాంకాలలో కంట్రీ కాలమ్స్ ఎందుకు ఖాళీగా ఉన్నాయి?

జియోలొకేషన్ కోసం GeoLite2 డేటాబేస్ అవసరం, దీనిని మీరు GEOLITE_LICENSE_KEY అందించినప్పుడు మాత్రమే Shlink డౌన్‌లోడ్ చేసుకుంటుంది. ఈ కీ MaxMind నుండి ఉచితంగా లభిస్తుంది. దీనిని ఎన్విరాన్‌మెంట్ సెక్షన్‌లో జోడించి, కంటైనర్‌ను రీక్రియేట్ చేయండి, అప్పుడు కొత్త విజిట్స్ లొకేషన్ వివరాలతో నమోదవుతాయి. అంతకుముందు నమోదైన విజిట్స్, మీరు shlink visit:locate రన్ చేసే వరకు ఖాళీగానే ఉంటాయి.

నేను Shlinkని వేరే సర్వర్‌కు ఎలా తరలించాలి?

డొమైన్‌ను అలాగే ఉంచి డేటాను తరలించండి. pg_dump తో డేటాబేస్‌ను డంప్ చేయండి, ఆ డంప్ ఫైల్‌ను మరియు కంపోజ్ ఫైల్‌ను కొత్త సర్వర్‌కు కాపీ చేయండి, స్టాక్‌ను ప్రారంభించండి, ఆపై అసలైన ట్రాఫిక్ రాకముందే ఖాళీ డేటాబేస్‌లోకి డంప్‌ను రీస్టోర్ చేయండి. DNS రికార్డును చివరగా మార్చండి. షార్ట్ కోడ్‌లు మరియు వాటి విజిట్ హిస్టరీ అలాగే ఉంటాయి, ఎందుకంటే ప్రతిదీ డేటాబేస్‌లోనే ఉంటుంది.