SSD Nodes Learn Hosting plans →
تعلیمی Matt Connorتحریر: Matt Connor · اپ ڈیٹ شدہ 2026-10-24

OpenAnalytics کو اپنے VPS پر کیسے انسٹال کریں؟

OpenAnalytics کی تنصیب کے لیے 4 GB RAM اور 25 GB ڈسک درکار ہے۔ اس گائیڈ میں ClickHouse، Postgres اور Valkey کے ساتھ مکمل سیٹ اپ اور ضروری DNS کنفیگریشن کی تفصیلات موجود ہیں۔

پہلے مرحلے سے قبل، درکار وسائل

OpenAnalytics کو self-host کرنے کے لیے آپ کو 4 GB RAM، 25 GB خالی ڈسک، Docker بمعہ Compose پلگ ان، اور چار DNS ریکارڈز کے ساتھ ایک Linux VPS درکار ہے جو پہلے سے اس سرور کی طرف اشارہ کر رہے ہوں۔ یہ ایک دیانتدارانہ خلاصہ ہے، اور اسے پہلے کمانڈ سے پہلے ہونا چاہیے، نہ کہ بعد میں۔

یہ اسٹیک چھ ایپلیکیشن سروسز اور تین ڈیٹا اسٹورز پر مشتمل ہے۔ Postgres کنٹرول پلین کو سنبھالتا ہے: اکاؤنٹس، سائٹس، API کیز اور شیئر لنکس۔ ClickHouse خام ایونٹس اور وہ رول اپس (rollups) رکھتا ہے جنہیں ڈیش بورڈ پڑھتا ہے۔ Valkey دو بار چلتا ہے، ایک بار پائیدار ایونٹ کیو (durable event queue) کے طور پر اور دوسری بار کیشے کے طور پر جسے سسٹم کھو سکتا ہے، کیونکہ ان دونوں کاموں کے لیے متضاد eviction پالیسیوں کی ضرورت ہوتی ہے۔ صرف ایک عمل، یعنی query gateway، کو ClickHouse پڑھنے کی اجازت ہے، اور یہ ہر کوئری لفافے پر موجود Ed25519 دستخط کی تصدیق کرتا ہے اس سے پہلے کہ وہ اسے چلائے۔

اگر آپ ایک بائنری اور ایک کنفیگریشن فائل تلاش کر رہے تھے، تو یہ وہ نہیں ہے۔ GoatCounter اس زمرے میں سنگل بائنری آپشن ہے: ایک Go ایگزیکیوٹیبل، بائی ڈیفالٹ SQLite، اور کوئی بیرونی ڈیٹا بیس نہیں۔ یہ بھاری اسٹیک آپ کو فنلز (funnels)، ویب وائٹلز، اپنے Stripe اکاؤنٹ سے ریونیو ایٹری بیوشن، اور ایک MCP (ماڈل کانٹیکسٹ پروٹوکول) سرور فراہم کرتا ہے۔ Self-hosted اینالیٹکس ٹولز کے درمیان انتخاب وہ پوسٹ ہے جو اس موازنے کا جائزہ لیتی ہے۔ یہ گائیڈ فرض کرتی ہے کہ آپ پہلے ہی فیصلہ کر چکے ہیں۔

سب سے پہلے DNS ریکارڈز کو سرور کی طرف پوائنٹ کریں

کسی بھی کام کو شروع کرنے سے پہلے چاروں سب ڈومینز کا سرور کے public IP پر resolve ہونا ضروری ہے، کیونکہ Caddy پہلی بار چلنے پر Let's Encrypt سرٹیفکیٹس کی درخواست کرتا ہے اور اگر نام resolve نہ ہو رہا ہو تو یہ challenge ناکام ہو جاتا ہے۔

  • app.example.com ڈیش بورڈ کو سرو کرتا ہے۔
  • api.example.com API اور OAuth کال بیکس کو سرو کرتا ہے۔
  • c.example.com کلیکٹر اور ٹریکر اسکرپٹ کو سرو کرتا ہے۔
  • rt.example.com ریئل ٹائم اسٹریم کو سرو کرتا ہے۔

چار A ریکارڈز استعمال کریں، یا ایک A ریکارڈ اور تین CNAMEs جو اس کی طرف اشارہ کرتے ہوں۔ آگے بڑھنے سے پہلے dig +short app.example.com کے ساتھ تصدیق کریں۔ ایک منٹ پہلے شامل کیا گیا نام بھی کسی بھی resolver کی طرف سے NXDOMAIN کے طور پر کیش (cache) ہو سکتا ہے جسے Let's Encrypt استعمال کر رہا ہو، لہذا اگر سرٹیفکیٹ کی پہلی کوشش ناکام ہو جائے تو انتظار کرنا اور Caddy کے لاگز پڑھنا بہتر ہے۔ انسٹالیشن کو دوبارہ چلانے سے DNS کی propagation تیز نہیں ہوتی۔

Docker Compose کے ساتھ OpenAnalytics کو self-host کرنے کا طریقہ

ایک tagged release کو checkout کریں۔ default branch پر development ہوتی ہے، جبکہ release tag ان images سے مطابقت رکھتا ہے جو باقاعدہ شائع کی جاتی ہیں۔ نیچے دی گئی commands یہ فرض کرتی ہیں کہ Docker اور Compose plugin پہلے سے نصب ہیں، جس کا احاطہ VPS پر Docker Compose سروسز چلانے کے گائیڈ میں کیا گیا ہے۔

git clone https://github.com/OpenLabs-so/openanalytics
cd openanalytics
git checkout "$(git tag -l 'v*' --sort=-v:refname | sed '/-/d' | head -1)"
cd infra/selfhost
./generate-secrets.sh --domain example.com --email you@example.com --with-geoip
docker compose pull && docker compose up -d

checkout لائن میں موجود sed '/-/d' pre-release tags کو ہٹا دیتا ہے، تاکہ آپ release candidate کے بجائے تازہ ترین stable version پر پہنچ جائیں۔ --with-geoip generation کے دوران DB-IP city database کو fetch کرتا ہے۔ اگر آپ اسے چھوڑ دیں گے تو ہر event میں country null رہے گی، جس کی وجہ سے geography view میں کچھ بھی دکھائی نہیں دے گا۔ آپ اسے بعد میں infra/selfhost/geoip/fetch-dbip.sh چلا کر، env/collector.env میں GEOIP_DB_PATH=/geoip/dbip-city-lite.mmdb سیٹ کر کے، اور پھر docker compose up -d --force-recreate collector کے ساتھ collector کو دوبارہ بنا کر شامل کر سکتے ہیں۔ یہ database ماہانہ بنیادوں پر refresh ہوتا ہے، لہذا اسے ہر ماہ fetch کریں ورنہ آپ کا city data غیر درست ہو جائے گا۔

آگے بڑھنے سے پہلے تیار کردہ secrets کا backup لیں

Generator تین چیزیں لکھتا ہے۔ .env میں domain names اور image references ہوتے ہیں۔ env/*.env میں ہر service کے لیے secrets کی ایک file ہوتی ہے۔ docker-compose.override.yml میں YAML block scalars کی صورت میں دو Ed25519 key pairs ہوتے ہیں: ایک queries پر دستخط کرنے کے لیے اور دوسرا realtime tokens کے لیے، کیونکہ multi-line PEM کسی env file میں نہیں رک سکتا۔ ہر key کا متعلقہ حصہ صرف اسی service کو دیا جاتا ہے جسے اس کی ضرورت ہو: API کو دونوں private keys ملتی ہیں، query gateway کو query public key ملتی ہے، اور realtime service کو token verify key ملتی ہے۔ یہ تمام files git-ignored ہیں، اور ان میں سے کسی کو بھی انہی values کے ساتھ دوبارہ generate نہیں کیا جا سکتا۔

اب ان files کو machine سے باہر copy کریں۔ ہر loss کا ایک مخصوص نتیجہ ہوتا ہے:

  • Store passwords ضائع ہونے پر آپ Postgres اور ClickHouse سے lock out ہو جاتے ہیں۔ انہیں صرف containers کے اندر سے reset کیا جا سکتا ہے۔
  • OA_CREDENTIAL_KEYRING ضائع ہونے پر ہر stored third-party credential ناقابل بازیافت ہو جاتا ہے۔ اس لیے جس نے Stripe account connect کیا ہو، اسے دوبارہ connect کرنا پڑتا ہے۔
  • ANONYMOUS_IDENTITY_SECRET ضائع ہونے پر visitor identity دوبارہ baseline ہوتی ہے: کل کے تمام visitors نئے شمار ہوتے ہیں، اور یہ تبدیلی charts میں نظر آتی ہے۔
  • AUTH_SECRET ضائع ہونے پر ہر session invalidate ہو جاتا ہے، اس لیے سب کو دوبارہ sign in کرنا پڑتا ہے۔
  • Signing private key ضائع ہونے پر key pair rotate کریں۔ کوئی data ضائع نہیں ہوتا۔

دو secrets کو دو، دو files میں byte-identical ہونا چاہیے۔ ANONYMOUS_IDENTITY_SECRET، collector.env اور worker.env میں موجود ہے، کیونکہ collector visitor hash compute کرتا ہے اور worker اسے لکھتا ہے۔ OA_CREDENTIAL_KEYRING، api.env اور worker.env میں موجود ہے۔ باقی ہر secret جان بوجھ کر صرف ایک service تک محدود ہے، اور جس service کو ایسا secret دے دیا جائے جسے اسے اپنے پاس نہیں رکھنا چاہیے، وہ start ہونے کے بجائے exit ہو جاتی ہے۔

اسٹیک کو چلائیں اور اس کی جانچ کریں

grep OA_IMAGE .env
docker compose pull
docker compose up -d
docker compose logs -f migrate
docker compose ps

migrate، Postgres اور ClickHouse کے اسکیماز لاگو کرنے کے بعد بند ہو جاتا ہے، لہذا ایک رکا ہوا migrate کنٹینر درست اختتامی حالت ہے۔ tracker-build، oa.js کو ایک ایسے والیوم میں کمپائل کرتا ہے جسے Caddy پیش کرتا ہے اور پھر یہ بھی بند ہو جاتا ہے۔ باقی تمام سروسز کی حالت docker compose ps میں healthy ہونی چاہیے۔ اگر کوئی سروس بار بار ری اسٹارٹ ہو رہی ہے تو اس کا مطلب تقریباً ہمیشہ یہ ہوتا ہے کہ وہ انوائرمنٹ ویلیڈیشن میں ناکام ہو رہی ہے، اور لاگ ہر مسئلے کو ایک ہی فہرست میں پرنٹ کرتا ہے نہ کہ ہر ری اسٹارٹ پر ایک۔ اس کی دو عام وجوہات یہ ہیں: ایک ویری ایبل کا خالی رہ جانا، جسے unset سمجھنے کے بجائے مسترد کر دیا جاتا ہے، اور کسی سیکرٹ کا غلط سروس فائل میں رکھا جانا۔

arm64 پر، یا کسی برانچ سے، کوئی پبلش شدہ امیجز موجود نہیں ہوتیں اور آپ کو docker compose up -d --build کے ساتھ مقامی طور پر بلڈ کرنا پڑتا ہے۔ 4 GB ریم والا ہوسٹ اس بلڈ کے دوران میموری ختم ہونے کی وجہ سے رک سکتا ہے۔ پہلے swap شامل کریں، جس کی ضرورت صرف بلڈ کے دوران ہوتی ہے:

fallocate -l 4G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab

بلڈنگ میں تقریباً دس منٹ لگتے ہیں۔ امیجز پل کرنے میں کچھ منٹ لگتے ہیں، اسی لیے ریلیز امیجز موجود ہیں۔

پہلے اکاؤنٹ کا فوری دعویٰ کریں

https://app.example.com کو کھولیں۔ ایسی deployment جس میں ابھی تک کسی نے لاگ ان نہیں کیا، وہاں سائن ان فارم نظر نہیں آتا: یہ پہلا اکاؤنٹ بنانے کی پیشکش کرتا ہے۔ یہ اکاؤنٹ مستقل طور پر مراعات یافتہ (privileged) ہوتا ہے، اور یہ واحد اکاؤنٹ ہے جو deployment settings کی اسکرین دیکھ سکتا ہے۔ ایک بار جب یہ بن جائے تو یہ روٹ 409 کا جواب دیتا ہے، تاکہ کوئی دوسرا شخص آپ کے بعد رسائی حاصل نہ کر سکے۔ یہ کام اسی وقت کریں جب stack مکمل طور پر فعال ہو جائے، نہ کہ اگلے ہفتے۔

Tracker کو انسٹال کریں

ڈیش بورڈ میں ایک سائٹ شامل کریں، یہ آپ کو ٹیگ فراہم کرے گا۔ اس کی شکل مقرر ہے:

<script
  async
  src="https://c.example.com/oa.js"
  data-key="YOUR_TRACKING_KEY"
  data-collector="https://c.example.com"
></script>

اسے صفحے کے head میں رکھیں۔ ٹریکنگ کی (tracking key) ڈیزائن کے لحاظ سے عوامی ہے، لہذا یہ آپ کے HTML میں وہاں ہونی چاہیے جہاں کوئی بھی اسے پڑھ سکے۔ اسکرپٹ window.oa کو انسٹال کرتا ہے، اور oa("track", ...) جیسی کالز کو ایک stub کے ذریعے قطار میں لگایا جاتا ہے اور فائل لوڈ ہوتے ہی انہیں flush کر دیا جاتا ہے، لہذا جلد فائر ہونے والا کوئی custom event ضائع نہیں ہوتا۔ اگر صفحے پر موجود کوئی اور چیز پہلے سے window.oa کی مالک ہے، تو ٹریکر اس کے بجائے window.openanalytics کے طور پر انسٹال ہوتا ہے۔ اگر وہی سائٹ onion service کے طور پر بھی جواب دیتی ہے، تو اس build میں ٹیگ شامل نہ کریں، کیونکہ c.example.com سے حاصل کردہ اسکرپٹ Tor Browser کے وزیٹر کو واپس clearnet پر لے آتا ہے اور ایک ہی صفحہ لوڈ ہونے کے دوران دونوں پتوں کو آپس میں جوڑ دیتا ہے۔

پھر پورے راستے (path) کو شروع سے آخر تک چیک کریں:

curl -s https://c.example.com/oa.js -o /dev/null -w '%{http_code} %{size_download}\n'
curl -s https://api.example.com/health | head -c 200
docker compose logs --tail=50 worker | grep -i batch

پہلی کمانڈ کو 200 اور چند کلو بائٹس پرنٹ کرنے چاہئیں۔ اپنی سائٹ پر ایک صفحہ لوڈ کریں، پھر چند سیکنڈ کے اندر ورکر لاگ میں batch لائن تلاش کریں۔ کلیکٹر (collector) ایونٹ قبول کرتے ہی 202 کا جواب دیتا ہے، اور 202 کا مطلب ہے کہ ایونٹ قطار میں ہے، محفوظ نہیں ہوا۔ ورکر ہی وہ چیز ہے جو ایونٹس کو ClickHouse میں منتقل کرتی ہے۔ اگر ایونٹس قبول ہو رہے ہیں لیکن ڈیش بورڈ میں کچھ ظاہر نہیں ہو رہا تو اس کا مطلب ہے کہ ورکر بلاک ہے، اور Valkey کی قطار کی گہرائی (queue depth) کا مسلسل بڑھنا اس کی تصدیق کرتا ہے۔ اس کی عام وجوہات worker.env میں غلط ClickHouse اسناد، یا حال ہی میں شامل کی گئی migration ٹیبل پر اجازت (grant) کا نہ ہونا ہیں۔

Collector کو عوامی رکھیں اور ڈیش بورڈ کو تصدیق (auth) کے پیچھے رکھیں

Caddy کمپوز فائل کے اندر موجود ہوتا ہے اور خود بخود چاروں ناموں کے لیے سرٹیفکیٹ حاصل کر لیتا ہے، لہذا ڈیفالٹ پاتھ کے لیے آپ کو کسی پراکسی ورک کی ضرورت نہیں ہے۔ اگر سرور پر پہلے سے ایک nginx ریورس پراکسی چل رہی ہے، تو اس کے بجائے فراہم کردہ infra/selfhost/nginx.conf.example کو اسٹیک کے سامنے رکھیں، اور اس کی ہیڈر ہینڈلنگ کو برقرار رکھیں:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header CF-Connecting-IP "";
proxy_set_header True-Client-IP "";
proxy_set_header Fly-Client-IP "";

کلیکٹر روزانہ وزیٹر ہیش کلائنٹ کے IP سے اخذ کرتا ہے، لہذا اسے یہ ایڈریس کنکشن سے لینا چاہیے نہ کہ ہیڈر سے۔ کسی غیر معتبر ہاپ (hop) سے CF-Connecting-IP کو پاس کرنے سے کوئی بھی کالر کسی بھی ایڈریس کا دعویٰ کر سکتا ہے، جو جیو لوکیشن کو خراب کرتا ہے اور وزیٹر کی تعداد کو بلاوجہ بڑھا دیتا ہے۔

رسائی ہوسٹ نیم کے لحاظ سے واضح طور پر تقسیم ہوتی ہے۔ c. اور rt. کو ان تمام سائٹس کے ہر وزیٹر کے لیے قابل رسائی ہونا چاہیے جنہیں آپ ٹریک کر رہے ہیں، لہذا ان دونوں کے سامنے کبھی بھی basic auth یا IP allowlist نہ لگائیں۔ app. اور api. تک صرف ان لوگوں کی رسائی ہونی چاہیے جو سائن ان کرتے ہیں۔ ایپلیکیشن کی اپنی تصدیق (auth) ہی ڈیش بورڈ کی حفاظت کرتی ہے: پاس ورڈ سائن ان ڈیفالٹ طور پر env/api.env میں AUTH_PASSWORD_SIGNIN=enabled کے ذریعے فعال ہوتا ہے، اور Google یا GitHub کے بٹن تب ہی ظاہر ہوتے ہیں جب اس پرووائیڈر کے لیے کلائنٹ آئی ڈی اور کلائنٹ سیکرٹ دونوں موجود ہوں۔ میجک لنکس کے لیے میل ٹرانسپورٹ کی ضرورت ہوتی ہے، اور اس کے بغیر API صرف بھیجے گئے پیغام کو آؤٹ باکس میں لکھتا ہے، لہذا کچھ بھی ڈیلیور نہیں ہوتا اور کوئی ایرر بھی نہیں آتا۔ اگر آپ کی دیگر self-hosted ایپس پہلے سے ایک ہی Authentik لاگ ان کے پیچھے ہیں، تو جلد فیصلہ کریں کہ آیا یہ ڈیش بورڈ ان میں شامل ہوگا یا اپنے الگ اکاؤنٹس رکھے گا، کیونکہ یہاں جو پہلا اکاؤنٹ آپ بنائیں گے وہ مستقل طور پر مراعات یافتہ (privileged) ہوگا۔

ایک سیٹنگ یہ طے کرتی ہے کہ آیا ڈیش بورڈ کام کرے گا یا نہیں۔ env/api.env میں AUTH_TRUSTED_ORIGINS کا ڈیش بورڈ اوریجن سے بالکل مماثل ہونا ضروری ہے۔ غلط یا غائب ہونے کی صورت میں، API کوئی CORS (cross-origin resource sharing) ہیڈرز جاری نہیں کرتا، براؤزر ہر کال کو مسترد کر دیتا ہے، اور آپ کو ایک ایسا ڈیش بورڈ ملتا ہے جو لے آؤٹ تو دکھاتا ہے لیکن ڈیٹا نہیں، جبکہ docker compose ps سب کچھ ٹھیک ہونے کی رپورٹ دیتا ہے۔

جب آپ پراکسی کنفیگریشن میں ہوں، تو خودکار ٹریفک کو سنبھالیں۔ کرالرز کلیکٹر کو کسی بھی دوسری چیز کی طرح ہٹ کرتے ہیں، اور ان کے پیج ویوز ClickHouse اور آپ کے اعداد و شمار میں شامل ہو جاتے ہیں۔ AI کرالرز کو سرور پر بلاک کرنا اس ڈیٹا کا ایک حصہ ڈیٹا بیس میں جانے سے روکتا ہے، جس سے آپ کی درستگی برقرار رہتی ہے اور ڈسک کی جگہ بھی بچتی ہے۔

یہاں cookieless کا کیا مطلب ہے اور اس کی قیمت کیا ہے

یہاں کوئی cookie استعمال نہیں ہوتی۔ وزیٹر کی شناخت ایک salted hash ہے، یہ salt ہر دن تبدیل ہوتا ہے، اور raw IP addresses کو کبھی محفوظ نہیں کیا جاتا۔ Geolocation کو مقامی طور پر آپ کی اپنی ڈسک پر موجود DB-IP فائل کے ذریعے resolve کیا جاتا ہے، لہذا وزیٹر کے بارے میں کوئی بھی معلومات کبھی host سے باہر نہیں جاتیں۔ تلاش کو مقامی رکھنے سے وینڈر ختم ہوتا ہے، ڈیٹا نہیں، اور یہی وہ حد ہے جو تب سامنے آتی ہے جب آپ اپنی SearXNG instance چلاتے ہیں اور آپ کے سرور کا IP وہ چیز بن جاتا ہے جسے سرچ انجنز دیکھتے ہیں۔

اس کا فائدہ یہ ہے کہ وزیٹر کے آلے پر کوئی مستقل شناخت کنندہ (identifier) موجود نہیں ہوتا، جو کہ خاص طور پر وہ چیز ہے جو کسی ٹریکر کو EU ePrivacy کی رضامندی کے قوانین کے دائرہ کار میں لاتی ہے۔ اسی وجہ سے اس طرح کے صرف مجموعی (aggregate-only) سیٹ اپ عام طور پر بغیر کسی consent banner کے چلائے جاتے ہیں۔ GDPR اب بھی اس بات کا احاطہ کرتا ہے کہ آپ کیا محفوظ کرتے ہیں اور کتنی دیر کے لیے، اور آپ کے کیس کا فیصلہ آپ کے اپنے قانونی مشیر کرتے ہیں، نہ کہ کوئی README۔

اس کی قیمت یہ ہے کہ آپ دنوں کے درمیان شناخت برقرار نہیں رکھ سکتے۔ Salt کی تبدیلی کا مطلب ہے کہ جو شخص پیر کو وزٹ کرتا ہے اور پھر بدھ کو دوبارہ آتا ہے، اسے ڈیزائن کے مطابق دو الگ وزیٹر گنا جاتا ہے اور اس کا کوئی متبادل حل نہیں ہے۔ روزانہ کے unique counts درست ہوتے ہیں۔ ہفتہ وار اور ماہانہ unique counts روزانہ کے اعداد و شمار سے بنائے جاتے ہیں اور یہ رسائی کو بڑھا چڑھا کر پیش کریں گے، لہذا طویل مدتی "returning visitor" کا کوئی بھی عدد اس چیز کی پیمائش نہیں کر رہا جو اس کے لیبل پر لکھا ہے۔ Sessions اور journeys ایک ہی دن کے اندر قابل اعتماد ہیں۔ ANONYMOUS_IDENTITY_SECRET کو تبدیل کرنے کا اثر دن کی حد جیسا ہی ہوتا ہے، لہذا اس تبدیلی کو معمول کی صفائی کے بجائے ڈیٹا میں تبدیلی سمجھیں۔

یہ کلیکٹر Do Not Track اور Global Privacy Control کا احترام کرتا ہے، جو کہ براؤزر کا وہ سگنل ہے جو کسی سائٹ کو ذاتی ڈیٹا فروخت یا شیئر نہ کرنے کا کہتا ہے۔ اسکرپٹ ٹیگ میں اسی مقصد کے لیے اپنے سوئچز موجود ہیں: data-respect-gpc، data-respect-dnt، اور data-require-consent، جو رضامندی ملنے تک تمام کلیکشن کو روک کر رکھتا ہے اور جواب کو localStorage میں oa.consent کی کلید کے تحت یاد رکھتا ہے۔ data-storage="none" کو سیٹ کرنے سے براؤزر اسٹوریج مکمل طور پر بند ہو جاتی ہے۔

چھ ماہ بعد disk کیوں بھر جاتی ہے

Self-hosted analytics box کو عموماً یہی چیز ختم کرتی ہے، اور عموماً اس کی وجہ events نہیں ہوتے۔

Images سے شروع کریں۔ ایک release دس images publish کرتی ہے، اور disk پر ان کا حجم تقریباً 13 GB ہوتا ہے۔ Upgrade کے دوران نئی generation، پرانی generation کو ہٹانے سے پہلے pull کی جاتی ہے، اس لیے کچھ وقت کے لیے دونوں generations موجود رہتی ہیں۔ ایک بھی page view آنے سے پہلے ہی 25 GB کی requirement کا بڑا حصہ اسی میں استعمال ہو جاتا ہے۔

پھر snapshots آتے ہیں۔ snapshot.sh stack کو stop کرتا ہے، دونوں data volumes کو ہر secret کے ساتھ archive کرتا ہے، اور پھر stack restart کرتا ہے۔ یہاں صرف cold copies محفوظ ہوتی ہیں، کیونکہ ClickHouse پس منظر میں parts merge کرتا ہے، اور merge کے دوران لی گئی copy consistent نہیں ہوتی۔ upgrade.sh ہر upgrade سے پہلے خودکار طور پر ایک snapshot لیتا ہے، اس لیے archives اسی disk پر جمع ہوتے رہتے ہیں، جب تک آپ ان کی تعداد محدود نہ کریں۔

./snapshot.sh create --label before-something-risky
./snapshot.sh list
./snapshot.sh --keep 3

Limit کے قریب موجود host پر upgrade سے پہلے پچھلی generation reclaim کریں۔ یہ اس وقت محفوظ ہے جب stack چل رہا ہو، کیونکہ running containers کو support کرنے والی images اب بھی referenced ہوتی ہیں:

docker image prune -a -f

پھر events خود آتے ہیں۔ ClickHouse columnar data کو مؤثر طور پر compress کرتا ہے، اس لیے raw event volume زیادہ تر لوگوں کے اندازے سے آہستہ بڑھتا ہے، اور dashboard جن rollup tables کو پڑھتا ہے وہ raw table کے مقابلے میں چھوٹی ہوتی ہیں۔ اندازہ لگانے کے بجائے measure کریں:

docker system df -v
docker compose exec clickhouse df -h /var/lib/clickhouse

ہر table کا حجم معلوم کرنے کے لیے اسے ان ClickHouse credentials کے ساتھ چلائیں جو generator نے infra/selfhost/env/ کے تحت لکھے ہیں:

SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size, sum(rows) AS row_count
FROM system.parts
WHERE active
GROUP BY table
ORDER BY sum(bytes_on_disk) DESC;

یہ reading پہلے ہفتے اور پھر چوتھے ہفتے میں لیں۔ دو points سے growth rate معلوم ہو جاتی ہے، اور growth rate بتاتی ہے کہ volume کو کب resize کرنے کی ضرورت ہوگی۔ October 2026 تک self-hosting guide میں raw events کے لیے retention یا time-to-live knob documented نہیں ہے، اس لیے disk کا size اپنی measured rate کے مطابق رکھیں؛ یہ نہ سمجھیں کہ پرانی rows خود بخود expire ہو جائیں گی۔

ایک deletion trap کے بارے میں پہلے سے جان لینا مفید ہے۔ کسی site یا account کو delete کرنے پر worker کے لیے کام queue کیا جاتا ہے، اور اس worker کے لیے CLICKHOUSE_MAINTENANCE_USER اور CLICKHOUSE_MAINTENANCE_PASSWORD set ہونا ضروری ہے، جبکہ ClickHouse میں matching oa_maintenance user بھی موجود ہونا چاہیے۔ ان کے بغیر deletion queue ہمیشہ کے لیے رکی رہتی ہے۔ Site dashboard سے غائب ہو جاتی ہے، لیکن ہر row disk پر موجود رہتی ہے۔ یوں cleanup دکھائی دیتا ہے، مگر کوئی space واپس نہیں ملتی۔

اپ گریڈز، اور تین اخراجات

git fetch --tags
git checkout "$(git tag -l 'v*' --sort=-v:refname | sed '/-/d' | head -1)"
cd infra/selfhost
./upgrade.sh

upgrade.sh عمل کرنے سے پہلے تین اخراجات ظاہر کرتا ہے۔ Downtime ایک حقیقت ہے: کلیکٹر کے بند ہونے کے دوران جو ایونٹس موصول ہوتے ہیں وہ ضائع ہو جاتے ہیں، کیونکہ ٹریکر انہیں دوبارہ بھیجنے (retry) کی کوشش نہیں کرتا۔ Rollback کرنے سے ڈیٹا کا نقصان ہوتا ہے، کیونکہ rollback.sh --to backups/<snapshot> دونوں اسٹورز کو مکمل طور پر تبدیل کر دیتا ہے اور اس اسنیپ شاٹ کے بعد لکھی گئی ہر قطار (row) کو ضائع کر دیتا ہے۔ ڈسک تیسرا خرچ ہے، جو کہ اوپر بیان کردہ اسنیپ شاٹ کا ڈھیر ہے۔

ری اسٹارٹ کے دو اصول ایسے ہیں جن میں غلطی کا امکان زیادہ ہوتا ہے۔ API سے پہلے query gateway کو آن کریں، کیونکہ نیا API ایسے query fields بھیجتا ہے جنہیں پرانا گیٹ وے مسترد کر دیتا ہے۔ اور ClickHouse کو ری اسٹارٹ کے بجائے دوبارہ تخلیق (recreate) کرنے کی ضرورت ہوتی ہے، کیونکہ docker compose restart کنٹینر کے اصل ماحول کو دوبارہ استعمال کرتا ہے اور آپ کی تبدیلیوں کو خاموشی سے نظر انداز کر دیتا ہے:

docker compose up -d --force-recreate clickhouse

ڈیش بورڈ میں بھی اسی قسم کا جال موجود ہے۔ env/web.env میں موجود تینوں NEXT_PUBLIC_* اوریجنز براؤزر بنڈل میں کمپائل ہوتے ہیں اور کنٹینر شروع ہونے پر تبدیل ہو جاتے ہیں، لہذا غلط ہوسٹ نیم پر کال کرنے والا ڈیش بورڈ docker compose up -d --force-recreate web سے ٹھیک ہوتا ہے، نہ کہ restart سے۔ ویب کنٹینر کا لاگ ان اوریجنز کو پرنٹ کرتا ہے جن کے ساتھ وہ شروع ہوا تھا، اور یہ تصدیق کرنے کا سب سے تیز طریقہ ہے کہ اصلاح لاگو ہو گئی ہے۔

اگر کنفیگریشن میں تبدیلی کے بعد ClickHouse شروع ہونے سے انکار کر دے، تو اس کے لاگ کی پہلی لائن پڑھیں۔ oa-entrypoint: سے شروع ہونے والی لائن کا مطلب ہے کہ انٹری پوائنٹ آپ کی سیٹ کردہ ویلیو کو مسترد کر رہا ہے۔ اس کے علاوہ کچھ بھی ہونے کا مطلب عام طور پر یہ ہے کہ کنفیگریشن فائل میں XML غلط ہے، اور اس کی سب سے عام وجہ XML کمنٹ کے اندر ڈبل ہائفن کا استعمال ہے، جو وہاں غیر قانونی ہے۔

AGPL-3.0، اور نام

Code AGPL-3.0 کے تحت licensed ہے، تاہم ایک exception موجود ہے: v0.7.0 سے browser tracker، apps/tracker/ کے اندر موجود تمام چیزیں، اور اس سے بننے والا oa.js، MIT کے تحت ہے۔ اس لیے اپنی pages میں paste کیا جانے والا tag AGPL کی شرائط ساتھ نہیں لاتا۔ اسے اپنی sites کے لیے بغیر ترمیم کے چلانے پر publishing کی کوئی obligation نہیں بنتی۔ Obligation اس وقت شروع ہوتی ہے جب آپ code میں ترمیم کر کے اس modified version کو network service کے طور پر چلاتے ہیں۔ اس صورت میں license آپ سے تقاضا کرتا ہے کہ اس service کے users کو اپنے modified source code کی پیشکش کریں۔ اس میں clients کو اپنے instance پر dashboards دینا بھی شامل ہے، اور اسے کسی ایسی چیز میں bundle کرنا بھی شامل ہے جسے آپ فروخت کرتے ہیں۔ اپنی تبدیلیاں public fork میں رکھنے سے یہ requirement پوری ہو جاتی ہے؛ اس کے لیے کوئی اضافی process درکار نہیں۔

Brand code سے الگ ہے۔ "OpenAnalytics" نام اور project کا hosted domain اس instance کی شناخت کرتے ہیں جسے اس کے authors چلاتے ہیں، اور یہ license grant کا حصہ نہیں ہیں۔ آپ کی deployment brand استعمال کیے بغیر software چلاتی ہے، اس لیے paying customers کے سامنے service پیش کرنے سے پہلے اسے اپنا الگ نام دیں۔

FAQ

کیا میں 1 GB RAM والے VPS پر OpenAnalytics چلا سکتا ہوں؟

نہیں۔ یہ پروجیکٹ تقریباً 4 GB RAM اور 25 GB فری ڈسک کا تقاضا کرتا ہے، کیونکہ ایک ڈیپلائمنٹ میں Postgres، ClickHouse اور دو Valkey انسٹینسز کے ساتھ ساتھ چھ ایپلیکیشن سروسز چلتی ہیں۔ صرف ClickHouse ہی ایک چھوٹا پروسیس نہیں ہے۔ 1 GB والے باکس پر کنٹینرز شروع تو ہو جاتے ہیں لیکن کرنل کا out-of-memory killer ان میں سے کسی ایک کو، عام طور پر ClickHouse کو، بند کر دیتا ہے۔ اگر 1 GB کا پلان ہی حتمی حد ہے، تو GoatCounter جیسا سنگل بائنری ٹول استعمال کریں، جو بغیر کسی بیرونی ڈیٹا بیس کے SQLite پر چلتا ہے۔

کیا مجھے OpenAnalytics کے ساتھ کوکی بینر کی ضرورت ہے؟

یہ آپ کے وکیل سے پوچھنے کا سوال ہے، اور تکنیکی حقائق آپ کے حق میں ہیں۔ اس میں کوئی کوکی نہیں ہوتی، وزیٹر کی شناخت ایک salted hash ہوتی ہے جو روزانہ تبدیل ہوتی ہے، اور خام IP ایڈریسز کبھی سٹور نہیں کیے جاتے، لہذا وزیٹر کی شناخت کے لیے کوئی مستقل ڈیٹا نہیں لکھا جاتا۔ GDPR اب بھی اس بات کا تعین کرتا ہے کہ آپ کیا سٹور کرتے ہیں اور اسے کتنی دیر تک رکھتے ہیں۔ اگر آپ ڈیٹا اکٹھا کرنے کے لیے واضح اجازت (consent) چاہتے ہیں، تو اسکرپٹ ٹیگ پر data-require-consent سیٹ کریں: اس صورت میں ٹریکر تب تک کچھ جمع نہیں کرے گا جب تک اجازت نہ مل جائے اور وہ اس جواب کو oa.consent کے تحت localStorage میں محفوظ رکھے گا۔

ایونٹس 202 کیوں دیتے ہیں لیکن ڈیش بورڈ پر کبھی ظاہر نہیں ہوتے؟

202 کا مطلب ہے کہ کلیکٹر نے ایونٹ کو قبول کر کے قطار (queue) میں لگا دیا ہے، نہ کہ یہ کہ اس نے اسے سٹور کر لیا ہے۔ ورکر اس قطار سے ڈیٹا نکال کر ClickHouse میں ڈالتا ہے، لہذا کامیاب درخواستوں کے باوجود خالی ڈیش بورڈ کا مطلب ہے کہ مسئلہ ورکر میں ہے۔ docker compose logs --tail=50 worker پڑھیں اور Valkey کی قطار کی گہرائی (queue depth) دیکھیں۔ اگر قطار مسلسل بڑھ رہی ہے تو اس کا مطلب ہے کہ ورکر بلاک ہے، اور اس کی عام وجوہات worker.env میں غلط ClickHouse اسناد یا کسی حالیہ مائیگریشن کے بعد ٹیبل پر درکار اجازت (grant) کا نہ ہونا ہے۔

جب ہر کنٹینر ہیلتھی ہے تو ڈیش بورڈ خالی کیوں ہے؟

سب سے پہلے env/api.env میں AUTH_TRUSTED_ORIGINS کو چیک کریں۔ اسے ڈیش بورڈ کے اوریجن (origin) سے بالکل مطابقت رکھنی چاہیے، اور اگر ایسا نہ ہو تو API کوئی CORS ہیڈرز جاری نہیں کرتا، جس کی وجہ سے براؤزر ہر کال کو مسترد کر دیتا ہے اور آپ کو ڈیٹا کے بغیر ایک کام کرنے والا لے آؤٹ نظر آتا ہے۔ دوسری چیز جو چیک کرنی ہے وہ env/web.env میں موجود تین NEXT_PUBLIC_* ویلیوز ہیں، جو ویب کنٹینر شروع ہونے پر تبدیل (substitute) ہوتی ہیں۔ انہیں درست کرنے کے لیے docker compose up -d --force-recreate web کی ضرورت ہوتی ہے، کیونکہ سادہ ری سٹارٹ پرانی ویلیوز کو ہی برقرار رکھتا ہے۔

کیا AGPL-3.0 مجھے کلائنٹس کو یہ سروس پیش کرنے سے روکتی ہے؟

نہیں۔ یہ صرف ایک شرط عائد کرتی ہے۔ کوڈ کو بغیر ترمیم کے چلائیں تو آپ کسی کے مقروض نہیں ہیں۔ اگر آپ اس میں ترمیم کرتے ہیں اور اس ترمیم شدہ ورژن کو بطور سروس چلاتے ہیں جسے دوسرے لوگ استعمال کرتے ہیں، تو آپ کو ان صارفین کو اپنا ترمیم شدہ سورس کوڈ فراہم کرنا ہوگا، جسے ایک پبلک فورک (fork) کے ذریعے پورا کیا جا سکتا ہے۔ اس کے علاوہ، "OpenAnalytics" کا نام کوڈ کے ساتھ لائسنس یافتہ نہیں ہے، لہذا آپ جو کچھ بھی فروخت کریں اسے اپنا نام دینا ہوگا۔

کیا یہ مضمون مفید تھا؟