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

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

సెల్ఫ్-హోస్టెడ్ URL షార్టెనర్ అనేది ఒక చిన్న సర్వర్. ఇది పొడవైన లింక్‌ను మీరు సొంతం చేసుకున్న చిన్న లింక్‌గా మారుస్తుంది మరియు దానిపై జరిగే ప్రతి క్లిక్‌ను లెక్కిస్తుంది. దీని కోసం Shlink ఉత్తమమైనది: ఇది ఓపెన్ సోర్స్, Docker ఇమేజ్‌గా విడుదలవుతుంది, మరియు ఒక కంటైనర్ మరియు డేటాబేస్‌తో మొత్తం పనిని పూర్తి చేస్తుంది. ఈ గైడ్ దీనిని ఒక VPSలో, ఒక నిజమైన షార్ట్ డొమైన్ వెనుక, HTTPS, API కీ, QR కోడ్‌లు మరియు క్లిక్ గణాంకాలతో ఎలా సెటప్ చేయాలో వివరిస్తుంది.

రెండు భాగాలు దీనిని ఒక కమర్షియల్ షార్టెనర్‌లా పనిచేసేలా చేస్తాయి. API సర్వర్ రీడైరెక్ట్‌లకు సమాధానమిస్తుంది మరియు డేటాను నిల్వ చేస్తుంది. వెబ్ క్లయింట్ అనేది ఒక ప్రత్యేకమైన స్టాటిక్ యాప్, ఇది మీ బ్రౌజర్ నుండి ఆ APIతో కనెక్ట్ అవుతుంది. మీరు రెండింటినీ రన్ చేయవచ్చు, లేదా కేవలం APIని మాత్రమే రన్ చేసి కమాండ్ లైన్ ద్వారా దానిని నియంత్రించవచ్చు.

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

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

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

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

dig +short s.example.com A

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

Compose ఫైల్

Shlinkకు డేటాబేస్ అవసరం. పరీక్ష కోసం SQLite సరిపోతుంది, కానీ మీరు భవిష్యత్తులో ఉపయోగించాలనుకునే దేనికైనా Postgres సరైన ఎంపిక. ఎందుకంటే విజిట్ రోస్ (visit rows) పెరుగుతూ ఉంటాయి మరియు Postgres ఇండెక్స్‌లను, ఏకకాలంలో జరిగే రైట్‌లను (concurrent writes) మెరుగ్గా నిర్వహిస్తుంది. దీన్ని /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 కోసం గైడ్లో ఉన్నాయి.

డేటాబేస్ పాస్‌వర్డ్, కంపోజ్ ఫైల్ పక్కన ఉన్న .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 ను ముందు భాగంలో ముగించండి

Shlink పోర్ట్ 8080 లో సాధారణ HTTP ని అందిస్తుంది. TLS అనేది రివర్స్ ప్రాక్సీకి సంబంధించినది, మరియు అసలైన హోస్ట్ పేరును పంపడం ఇక్కడ ముఖ్యమైన సెట్టింగ్. Shlink ఏ డొమైన్‌కు షార్ట్ కోడ్ చెందుతుందో నిర్ణయించడానికి Host హెడర్‌ను చదువుతుంది, కాబట్టి దానిని మార్చే ప్రాక్సీ ఉనికిలో ఉన్న లింక్‌లపై 404 ప్రతిస్పందనలను ఇస్తుంది మరియు తప్పుడు డొమైన్‌కు విజిట్ గణాంకాలను జోడిస్తుంది.

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

ఆ తర్వాత సర్టిఫికేట్‌ను జారీ చేయండి. రెన్యూవల్ టైమర్‌తో సహా పూర్తి వివరణ Ubuntu 24.04 లో nginx కోసం Certbot గైడ్ లో ఉంది.

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

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

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 ని మళ్ళీ ఉపయోగించవచ్చు, మరియు మీరు తర్వాత కలిపి గణాంకాలను చూడాలనుకునే లింక్‌లను గ్రూప్ చేయడానికి ట్యాగ్‌లు ఉపయోగపడతాయి.

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

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

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

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

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

QR కోడ్‌లకు ఎటువంటి కాన్ఫిగరేషన్ అవసరం లేదు. ఏదైనా షార్ట్ 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ని జోడించండి.

దీన్ని రన్ అవుతూ ఉంచండి

ఒక షార్టెనర్ నిశ్శబ్దంగా విఫలమవుతుంది. లింకులు రీడైరెక్ట్ అవ్వడం ఆగిపోతాయి, కానీ ఎవరూ మీకు చెప్పరు, ఎందుకంటే లింక్‌పై క్లిక్ చేసిన వ్యక్తి అది పని చేయడం లేదని భావిస్తారు. హోమ్ పేజీకి బదులుగా ఒక అసలైన షార్ట్ URLకి అప్‌టైమ్ చెక్‌ను పాయింట్ చేయండి, మరియు రీడైరెక్ట్ కాని దేనిపైనైనా అలర్ట్ సెట్ చేయండి. సెల్ఫ్-హోస్ట్ చేసిన Uptime Kuma ఇన్‌స్టాన్స్ దీన్ని బాగా చేస్తుంది, మరియు ఇది ఒక నిర్దిష్ట స్టేటస్ కోడ్ కోసం పర్యవేక్షించగలదు.

కంటైనర్‌ను కాకుండా డేటాబేస్‌ను బ్యాకప్ చేయండి. ఒక కమాండ్ దాన్ని డంప్ చేస్తుంది.

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

ఆ ఫైల్ మరియు మీ compose ఫైల్ కలిసి కొత్త సర్వర్‌లో మొత్తం సర్వీస్‌ను తిరిగి నిర్మిస్తాయి. అప్‌గ్రేడ్‌లు sudo docker compose pull మరియు దాని తర్వాత sudo docker compose up -d ద్వారా జరుగుతాయి, మరియు Shlink ప్రారంభంలోనే ఏవైనా కొత్త మైగ్రేషన్లను రన్ చేస్తుంది. మీరు పుల్ చేయడానికి ముందే డంప్ తీసుకోండి, ఎందుకంటే మైగ్రేషన్‌ను రోల్ బ్యాక్ చేయడం సాధ్యం కాదు.

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 రికార్డును మార్చండి. షార్ట్ కోడ్‌లు మరియు వాటి విజిట్ హిస్టరీ అలాగే ఉంటాయి, ఎందుకంటే ప్రతిదీ డేటాబేస్‌లోనే ఉంటుంది.