OpenAnalytics-ஐ VPS-ல் நிறுவுவது எப்படி?

முதல் படிக்கு முந்தைய கட்டமைப்பு

OpenAnalytics-ஐ நீங்களே host செய்ய, 4 GB RAM, 25 GB காலி வட்டு இடம், Docker உடன் Compose plugin மற்றும் உங்கள் server-ஐச் சுட்டிக்காட்டும் நான்கு DNS பதிவுகள் கொண்ட Linux VPS தேவை. இதுவே உண்மையான தேவை; இதை முதல் கட்டளைக்கு முன்பே தெரிந்துகொள்வது அவசியம்.

இந்த stack-ல் ஆறு application services மற்றும் மூன்று data stores உள்ளன. Postgres கட்டுப்பாட்டு மையமாகச் செயல்படுகிறது: இதில் கணக்குகள், தளங்கள், API keys மற்றும் பகிரும் இணைப்புகள் சேமிக்கப்படும். ClickHouse மூல நிகழ்வுகளையும் (raw events) dashboard வாசிக்கும் சுருக்கங்களையும் (rollups) சேமிக்கிறது. Valkey இரண்டு முறை இயங்குகிறது; ஒன்று நீடித்திருக்கும் நிகழ்வு வரிசையாகவும் (durable event queue), மற்றொன்று இழக்கக்கூடிய cache-ஆகவும் செயல்படுகிறது. ஏனெனில், இந்த இரண்டு பணிகளுக்கும் வெவ்வேறு eviction policies தேவைப்படுகின்றன. query gateway என்ற ஒரே ஒரு process மட்டுமே ClickHouse-ஐ வாசிக்க அனுமதிக்கப்படுகிறது. இது ஒவ்வொரு query envelope-லும் உள்ள Ed25519 signature-ஐச் சரிபார்த்த பின்னரே அதை இயக்குகிறது.

உங்களுக்கு ஒரே ஒரு binary மற்றும் ஒரு config file மட்டும் போதும் என்றால், இது உங்களுக்கானது அல்ல. இந்த வகையில் GoatCounter ஒரு சிறந்த single-binary விருப்பமாகும்: இது ஒரே Go executable, இயல்பாகவே SQLite, மற்றும் வெளிப்புற database எதுவும் தேவையில்லை. இந்த கனமான stack-ஐப் பயன்படுத்துவதன் மூலம் funnels, web vitals, உங்கள் சொந்த Stripe கணக்கிலிருந்து வருவாய் விவரங்கள் மற்றும் ஒரு MCP (model context protocol) server போன்ற வசதிகளைப் பெறலாம். சுயமாக host செய்யப்படும் analytics கருவிகளுக்கு இடையே தேர்ந்தெடுத்தல் என்ற கட்டுரை இந்த மாற்றங்களை ஒப்பிடுகிறது. இந்த வழிகாட்டி, நீங்கள் ஏற்கனவே முடிவெடுத்துவிட்டீர்கள் என்ற அடிப்படையில் எழுதப்பட்டுள்ளது.

முதலில் DNS பதிவுகளை server-ஐ நோக்கி அமைக்கவும்

எந்தவொரு பணியையும் தொடங்குவதற்கு முன்பாக, நான்கு subdomain-களும் server-ன் public IP-ஐ நோக்கி resolve ஆக வேண்டும். ஏனெனில், Caddy முதல்முறை இயங்கும்போது Let's Encrypt certificates-ஐக் கோரும்; அப்போது பெயர் resolve ஆகவில்லை என்றால் challenge தோல்வியடையும்.

• app.example.com dashboard-ஐ வழங்குகிறது.
• api.example.com API மற்றும் OAuth callbacks-ஐ வழங்குகிறது.
• c.example.com collector மற்றும் tracker script-ஐ வழங்குகிறது.
• rt.example.com realtime stream-ஐ வழங்குகிறது.

நான்கு A records-ஐப் பயன்படுத்தவும், அல்லது ஒரு A record மற்றும் அதைச் சுட்டிக்காட்டும் மூன்று CNAME-களைப் பயன்படுத்தவும். தொடர்வதற்கு முன் dig +short app.example.com மூலம் உறுதிப்படுத்தவும். ஒரு நிமிடம் முன்பு நீங்கள் சேர்த்த பெயர், Let's Encrypt பயன்படுத்தும் resolver-ல் இன்னும் NXDOMAIN என்று cache செய்யப்பட்டிருக்கலாம். எனவே, முதல்முறை certificate முயற்சி தோல்வியடைந்தால், சிறிது நேரம் காத்திருந்து Caddy logs-ஐப் பார்க்கவும். நிறுவுதலை மீண்டும் இயக்குவதால் DNS propagation வேகமாக நடக்காது.

Docker Compose மூலம் OpenAnalytics-ஐ self-host செய்வது எப்படி

ஒரு tagged release-ஐ checkout செய்யவும். Development பணிகள் default branch-ல் நடைபெறும், வெளியிடப்பட்ட images-கள் release tag-உடன் ஒத்துப்போகும். Docker மற்றும் Compose plugin ஏற்கனவே நிறுவப்பட்டிருப்பதாகக் கொண்டு கீழே உள்ள கட்டளைகள் வழங்கப்பட்டுள்ளன; இது VPS-ல் Docker Compose services-ஐ இயக்குவது குறித்த பகுதியில் விளக்கப்பட்டுள்ளது.

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-ஐப் பதிவிறக்கும். இதைத் தவிர்த்தால், ஒவ்வொரு 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 மாதந்தோறும் புதுப்பிக்கப்படும், எனவே மாதத்திற்கு ஒருமுறை பதிவிறக்கத்தை மீண்டும் செய்யவும், இல்லையெனில் city தரவுகள் துல்லியமாக இருக்காது.

மேலும் தொடரும் முன் உருவாக்கப்பட்ட secrets-ஐ backup எடுக்கவும்

இந்த generator மூன்று விஷயங்களை உருவாக்குகிறது. .env-ல் domain பெயர்களும் image குறிப்புகளும் உள்ளன. env/*.env-ல் ஒவ்வொரு service-க்கும் தேவையான secrets தனித்தனி கோப்புகளாக உள்ளன. docker-compose.override.yml-ல் மூன்று Ed25519 key pairs-கள் YAML block scalars-ஆக உள்ளன, ஏனெனில் பல வரிகளைக் கொண்ட PEM கோப்பை env கோப்பில் வைக்க முடியாது. இவை அனைத்தும் git-ignore செய்யப்பட்டுள்ளன, மேலும் இவற்றை மீண்டும் அதே மதிப்புகளுடன் உருவாக்க முடியாது.

இந்தக் கோப்புகளை இப்போதே இந்த machine-லிருந்து நகலெடுக்கவும். ஒவ்வொன்றையும் இழப்பது குறிப்பிட்ட பாதிப்புகளை ஏற்படுத்தும்:

• Store passwords-ஐ இழந்தால், Postgres மற்றும் ClickHouse-க்குள் நுழைய முடியாது; இவற்றை container-க்குள் இருந்து மட்டுமே reset செய்ய முடியும்.
• OA_CREDENTIAL_KEYRING-ஐ இழந்தால், சேமிக்கப்பட்ட அனைத்து third-party credentials-களையும் மீட்க முடியாது; எனவே Stripe account-ஐ இணைத்த எவரும் அதை மீண்டும் இணைக்க வேண்டியிருக்கும்.
• ANONYMOUS_IDENTITY_SECRET-ஐ இழந்தால், பார்வையாளர்களின் அடையாளம் மீண்டும் தொடங்கும்: நேற்று வந்த பார்வையாளர்கள் அனைவரும் புதியவர்களாகக் கருதப்படுவார்கள், இது charts-ல் மாற்றத்தை ஏற்படுத்தும்.
• AUTH_SECRET-ஐ இழந்தால், அனைத்து sessions-களும் செல்லாததாகிவிடும், எனவே அனைவரும் மீண்டும் login செய்ய வேண்டியிருக்கும்.
• Signing private key-ஐ இழந்தால், அந்த pair-ஐ மட்டும் மாற்றினால் போதும். எந்தத் தரவும் இழக்கப்படாது.

இரண்டு secrets, இரண்டு கோப்புகளிலும் ஒரே மாதிரியான byte மதிப்புகளைக் கொண்டிருக்க வேண்டும். ANONYMOUS_IDENTITY_SECRET என்பது collector.env மற்றும் worker.env ஆகிய இரண்டிலும் இருக்க வேண்டும், ஏனெனில் collector பார்வையாளரின் hash-ஐக் கணக்கிடுகிறது, worker அதை எழுதுகிறது. OA_CREDENTIAL_KEYRING என்பது api.env மற்றும் worker.env ஆகிய இரண்டிலும் இருக்க வேண்டும். மற்ற அனைத்து secrets-களும் ஒரு குறிப்பிட்ட service-க்கு மட்டுமே உரியவை; ஒரு service-க்குத் தேவையில்லாத secret வழங்கப்பட்டால், அது தொடங்காமல் வெளியேறிவிடும்.

Stack-ஐ இயக்கி சரிபார்த்தல்

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

migrate ஆனது Postgres மற்றும் ClickHouse schemas-ஐப் பொருத்திவிட்டு வெளியேறிவிடும், எனவே migrate container நிறுத்தப்பட்ட நிலையில் இருப்பதுதான் சரியான இறுதி நிலை. tracker-build ஆனது oa.js-ஐ Caddy வழங்கும் volume-ஆகத் தொகுத்துவிட்டு வெளியேறிவிடும். மற்ற அனைத்துமே docker compose ps-ல் healthy என்று இருக்க வேண்டும். ஒரு service மீண்டும் மீண்டும் restart ஆகிறது என்றால், அது பெரும்பாலும் environment validation-ல் தோல்வியடைகிறது என்று அர்த்தம். ஒவ்வொரு restart-க்கும் ஒரு பிழை என்று காட்டாமல், அனைத்துப் பிரச்சினைகளையும் ஒரே பட்டியலாக log-ல் காட்டும். இதற்கு இரண்டு பொதுவான காரணங்கள் உள்ளன: ஒன்று, ஒரு variable-ஐ காலியாக விடுவது (இது unset என்று கருதப்படாமல் நிராகரிக்கப்படும்), மற்றொன்று, ஒரு secret-ஐத் தவறான service file-ல் வைப்பது.

arm64 கட்டமைப்பில் அல்லது ஒரு branch-லிருந்து இயக்கும்போது, வெளியிடப்பட்ட images இருக்காது, எனவே நீங்கள் docker compose up -d --build மூலம் locally build செய்ய வேண்டும். 4 GB host-ல் build செய்யும்போது இடையில் memory பற்றாக்குறை ஏற்படும். எனவே, build செய்யும்போது மட்டும் தேவைப்படும் swap-ஐ முதலில் சேர்க்கவும்:

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

Build செய்வதற்கு சுமார் பத்து நிமிடங்கள் ஆகும். Pull செய்வதற்குச் சில நிமிடங்கள் ஆகும், இதற்காகவே release images வழங்கப்படுகின்றன.

முதல் கணக்கை உடனடியாகக் கோருங்கள்

https://app.example.com-ஐத் திறக்கவும். யாரும் இதுவரை உள்நுழையாத ஒரு deployment-ல் உள்நுழைவுப் படிவம் காட்டப்படாது: அது முதல் கணக்கை உருவாக்கக் கேட்கும். அந்த கணக்கு நிரந்தரமாக privileged கணக்காக இருக்கும், மேலும் deployment settings திரையைப் பார்க்கும் ஒரே கணக்கு அது மட்டுமே. அது உருவாக்கப்பட்டவுடன், அந்த route 409-ஐப் பதிலளிக்கும், எனவே உங்களுக்குப் பின்னால் யாரும் உள்ளே வர முடியாது. stack ஆரோக்கியமாக இருக்கும் அந்த நிமிடமே இதைச் செய்யுங்கள், அடுத்த வாரம் வரை காத்திருக்க வேண்டாம்.

Tracker-ஐ நிறுவுதல்

Dashboard-ல் ஒரு site-ஐச் சேர்த்தால், அது உங்களுக்கு tag-ஐ வழங்கும். அதன் வடிவம் நிலையானது:

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

இதை page head-ல் சேர்க்கவும். Tracking key பொதுவானது (public), எனவே HTML-ல் எவரும் பார்க்கும் வகையில் இது இருக்கலாம். இந்த script window.oa-ஐ நிறுவுகிறது. oa("track", ...) போன்ற அழைப்புகள் ஒரு stub மூலம் வரிசைப்படுத்தப்பட்டு (queued), file load ஆனதும் அனுப்பப்படும். எனவே, தொடக்கத்திலேயே fire செய்யப்படும் custom event-கள் இழக்கப்படாது. page-ல் ஏற்கனவே window.oa பயன்பாட்டில் இருந்தால், tracker window.openanalytics என்ற பெயரில் தன்னை நிறுவிக் கொள்ளும். அதே site onion service ஆகவும் செயல்பட்டால், அந்த build-ல் இந்த tag-ஐச் சேர்க்க வேண்டாம். ஏனெனில், c.example.com-லிருந்து பெறப்படும் script, Tor Browser பயனரை மீண்டும் clearnet-க்குக் கொண்டு வந்து, ஒரே page load-ல் இரண்டு முகவரிகளையும் இணைத்துவிடும்.

பின்பு, முழுப் பாதையையும் (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 மற்றும் சில kilobytes அளவிலான தரவை அச்சிட வேண்டும். உங்கள் site-ல் ஒரு page-ஐ load செய்யவும். சில நொடிகளில் worker log-ல் batch line உள்ளதா என்று பார்க்கவும். Collector ஒரு event-ஐ ஏற்றுக் கொண்டவுடன் 202 என்று பதிலளிக்கும். 202 என்பது event வரிசைப்படுத்தப்பட்டுள்ளது (queued) என்பதைக் குறிக்கும், அது சேமிக்கப்படவில்லை. Worker தான் event-களை ClickHouse-க்கு மாற்றுகிறது. Event-கள் ஏற்கப்பட்டும் dashboard-ல் தெரியவில்லை என்றால், worker தடுக்கப்பட்டுள்ளது என்று பொருள். Valkey queue-ன் அளவு தொடர்ந்து அதிகரிப்பது இதை உறுதிப்படுத்தும். worker.env-ல் உள்ள தவறான ClickHouse credentials அல்லது migration மூலம் சேர்க்கப்பட்ட table-க்கு உரிய அனுமதி (grant) இல்லாததே இதற்குப் பொதுவான காரணங்கள்.

Collector-ஐ பொதுவெளியிலும், dashboard-ஐ அங்கீகாரத்திற்குப் பின்னாலும் வைத்திருத்தல்

Caddy, compose file-க்குள் இயங்கி நான்கு பெயர்களுக்கும் தானாகவே certificates-ஐப் பெற்றுக்கொள்கிறது, எனவே default path-க்கு நீங்கள் எந்த proxy வேலையும் செய்யத் தேவையில்லை. உங்கள் server-ல் ஏற்கனவே an nginx reverse proxy இயங்கிக்கொண்டிருந்தால், அதற்குப் பதிலாக வழங்கப்பட்ட infra/selfhost/nginx.conf.example-ஐப் பயன்படுத்தி stack-ஐ முன்னால் வைக்கவும், அதன் header handling-ஐ மாற்றாமல் அப்படியே வைத்திருக்கவும்:

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

Collector, தினசரி visitor hash-ஐ client IP-லிருந்து பெறுகிறது, எனவே அது connection-லிருந்து அந்த முகவரியை எடுக்க வேண்டும், header-லிருந்து எடுக்கக்கூடாது. நம்பகத்தன்மையற்ற hop-லிருந்து CF-Connecting-IP-ஐ அனுமதிப்பது, எந்தவொரு caller-ம் எந்த முகவரியையும் உரிமை கோர வழிவகுக்கும்; இது geolocation-ஐப் பாதிப்பதோடு visitor எண்ணிக்கையையும் தவறாக உயர்த்தும்.

Hostname அடிப்படையில் access பிரிக்கப்படுகிறது. நீங்கள் அளவிடும் ஒவ்வொரு தளத்தின் பார்வையாளர்களும் c. மற்றும் rt.-ஐ அணுக முடியும் என்பதால், அந்த இரண்டிற்கும் முன்னால் basic auth அல்லது IP allowlist-ஐ வைக்க வேண்டாம். app. மற்றும் api.-ஐ உள்நுழையும் நபர்கள் மட்டுமே அணுகினால் போதுமானது. Dashboard-ஐப் பாதுகாப்பது application-ன் சொந்த அங்கீகாரமே ஆகும்: env/api.env-ல் உள்ள AUTH_PASSWORD_SIGNIN=enabled மூலம் password sign-in default-ஆகச் செயல்படும். Google அல்லது GitHub buttons அந்தந்த provider-க்கான client ID மற்றும் client secret இரண்டும் இருக்கும்போது மட்டுமே தோன்றும். Magic links-க்கு mail transport தேவை; அது இல்லையென்றால் API அந்த மின்னஞ்சலை outbox-ல் மட்டுமே எழுதும், எனவே எதுவும் அனுப்பப்படாது, பிழையும் காட்டப்படாது. உங்கள் பிற self-hosted apps ஏற்கனவே a single Authentik login-க்கு பின்னால் இருந்தால், இந்த dashboard-ஐ அதனுடன் இணைப்பதா அல்லது தனி கணக்குகளை வைத்திருப்பதா என்பதை முன்கூட்டியே முடிவு செய்யுங்கள், ஏனெனில் நீங்கள் உருவாக்கும் முதல் கணக்கே நிரந்தரமாக privileged கணக்காக இருக்கும்.

Dashboard செயல்படுமா என்பதை ஒரு setting தீர்மானிக்கிறது. env/api.env-ல் உள்ள AUTH_TRUSTED_ORIGINS, dashboard origin-உடன் சரியாகப் பொருந்த வேண்டும். அது தவறாகவோ அல்லது விடுபட்டோ இருந்தால், API எந்த CORS (cross-origin resource sharing) headers-ஐயும் அனுப்பாது, browser அனைத்து அழைப்புகளையும் நிராகரிக்கும். இதனால் dashboard அதன் layout-ஐக் காட்டும், ஆனால் தரவுகள் எதையும் காட்டாது, அதே சமயம் docker compose ps அனைத்தும் சரியாக இருப்பதாகக் காட்டும்.

Proxy config-ல் இருக்கும்போதே, தானியங்கி traffic-ஐக் கவனியுங்கள். Crawlers மற்றவற்றைப் போலவே collector-ஐயும் அணுகும், அவற்றின் page views ClickHouse-ல் பதிவாகி உங்கள் புள்ளிவிவரங்களில் சேரும். Blocking AI crawlers at the server செய்வதன் மூலம், தரவுத்தளத்தின் துல்லியம் மற்றும் disk பயன்பாடு பாதிக்கப்படுவதற்கு முன்பே அவற்றை வடிகட்ட முடியும்.

இங்கு cookieless என்பதன் பொருள் மற்றும் அதன் விளைவுகள்

இதில் cookie பயன்படுத்தப்படுவதில்லை. பார்வையாளரின் அடையாளம் ஒரு salted hash மூலம் உருவாக்கப்படுகிறது; இந்த salt ஒவ்வொரு நாளும் மாற்றப்படும், மேலும் raw IP முகவரிகள் சேமிக்கப்படுவதில்லை. Geolocation தகவல்கள் உங்கள் disk-ல் உள்ள DB-IP கோப்பைப் பயன்படுத்தி உள்ளூர் அளவிலேயே கண்டறியப்படுகின்றன, எனவே பார்வையாளர் குறித்த எந்தத் தகவலும் host-ஐ விட்டு வெளியேறுவதில்லை. தேடல்களை உள்ளூர் அளவில் வைத்திருப்பது vendor-ஐ மட்டுமே நீக்குகிறது, தரவுகளை அல்ல; நீங்கள் சொந்தமாக SearXNG instance-ஐ இயக்கும்போது உங்கள் server-ன் IP-யையே தேடுபொறிகள் காண்பது போன்ற அதே வரம்புதான் இதற்கும் பொருந்தும்.

இதன் மூலம் பார்வையாளரின் சாதனத்தில் எந்தவொரு அடையாளமும் (identifier) நிரந்தரமாகச் சேமிக்கப்படுவதில்லை; இதுவே EU ePrivacy ஒப்புதல் விதிகளின் கீழ் ஒரு tracker-ஐக் கொண்டுவரும் முக்கிய காரணியாகும். இத்தகைய aggregate-only அமைப்புகள் பெரும்பாலும் ஒப்புதல் பதாகை (consent banner) இல்லாமலேயே இயங்குகின்றன. நீங்கள் சேமிக்கும் தரவுகள் மற்றும் அதன் கால அளவு குறித்து GDPR விதிகள் பொருந்தும்; உங்கள் வழக்கறிஞரே உங்கள் தரவுப் பயன்பாட்டிற்கான முடிவுகளை எடுக்க வேண்டும், README கோப்பு அல்ல.

இதன் விளைவாக, ஒருவரின் அடையாளத்தை பல நாட்களுக்குத் தொடர்ந்து கண்காணிக்க முடியாது. Salt rotation காரணமாக, திங்கள் மற்றும் புதன் கிழமைகளில் வரும் ஒரு நபர் இரண்டு தனித்தனி பார்வையாளர்களாகக் கருதப்படுவார்; இது வடிவமைப்பின் ஒரு பகுதி, இதற்கு மாற்று வழி இல்லை. தினசரி தனித்துவமான பார்வையாளர்களின் எண்ணிக்கை (daily unique counts) துல்லியமாக இருக்கும். வாராந்திர மற்றும் மாதாந்திர எண்ணிக்கைகள் தினசரி தரவுகளிலிருந்து கணக்கிடப்படுவதால், அவை பார்வையாளர்களின் எண்ணிக்கையை மிகைப்படுத்திக் காட்டும்; எனவே நீண்ட கால "திரும்பி வரும் பார்வையாளர்" (returning visitor) புள்ளிவிவரங்கள் அதன் பெயருக்கேற்ற துல்லியமான அளவீட்டைத் தராது. ஒரு நாளுக்குள் அமர்வுகள் (sessions) மற்றும் பயணங்கள் (journeys) நம்பகமானவை. ANONYMOUS_IDENTITY_SECRET-ஐ மாற்றுவது ஒரு நாள் முடிவடைவதைப் போன்ற விளைவையே ஏற்படுத்தும், எனவே அந்த மாற்றத்தை வழக்கமான பராமரிப்பாகக் கருதாமல் தரவு மாற்றமாகக் கருதவும்.

இந்தத் தரவு சேகரிப்பான் Do Not Track மற்றும் Global Privacy Control ஆகியவற்றை மதிக்கிறது; இவை தனிப்பட்ட தரவை விற்கவோ அல்லது பகிரவோ கூடாது என்று தளத்திற்கு அறிவுறுத்தும் browser சிக்னல்கள் ஆகும். Script tag-ல் இதற்கான கட்டுப்பாடுகள் உள்ளன: data-respect-gpc, data-respect-dnt, மற்றும் data-require-consent; இவை ஒப்புதல் கிடைக்கும் வரை தரவு சேகரிப்பை நிறுத்தி வைக்கும், மேலும் அந்த முடிவை localStorage-ல் oa.consent என்ற key-ன் கீழ் நினைவில் கொள்ளும். data-storage="none"-ஐ அமைப்பதன் மூலம் browser storage முழுமையாக முடக்கப்படும்.

ஆறு மாதங்களுக்குப் பிறகு வட்டு (disk) ஏன் நிரம்புகிறது

இதுவே ஒரு self-hosted analytics server-ன் செயல்பாட்டை முடக்கும் முக்கிய காரணியாகும்; பொதுவாக நிகழ்வுகள் (events) இதற்கு காரணமல்ல.

முதலில் images-ஐ கவனிக்கவும். ஒரு release பத்து images-ஐ வெளியிடுகிறது, இவை வட்டில் சுமார் 13 GB இடத்தைப் பிடிக்கின்றன. ஒரு upgrade-ன் போது, பழைய பதிப்பை நீக்குவதற்கு முன்பே புதிய பதிப்பு தரவிறக்கம் செய்யப்படுவதால், சிறிது காலம் இரண்டு பதிப்புகளும் வட்டில் இருக்கும். ஒரு page view கூட வருவதற்கு முன்பே, இதுவே 25 GB தேவையின் பெரும்பகுதியை எடுத்துக்கொள்கிறது.

அடுத்து snapshots. snapshot.sh stack-ஐ நிறுத்திவிட்டு, அனைத்து secrets-உடன் சேர்த்து இரண்டு data volumes-ஐயும் archive செய்துவிட்டு, மீண்டும் தொடங்கும். ClickHouse பின்னணியில் parts-ஐ ஒன்றிணைப்பதால் (merge), அந்த நேரத்தில் எடுக்கப்படும் நகல் சீரானதாக இருக்காது; எனவே cold copies மட்டுமே பாதுகாப்பானவை. upgrade.sh ஒவ்வொரு upgrade-க்கு முன்பும் தானாகவே ஒரு snapshot-ஐ எடுக்கும், எனவே நீங்கள் அவற்றை வரம்பிடாத வரை, அந்த archives ஒரே வட்டில் சேர்ந்து கொண்டே இருக்கும்.

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

வட்டு கொள்ளளவு அதன் எல்லையை நெருங்கும்போது, upgrade செய்வதற்கு முன் முந்தைய பதிப்பை நீக்கிவிடவும். stack இயங்கிக்கொண்டிருக்கும்போதே இதைச் செய்வது பாதுகாப்பானது, ஏனெனில் இயங்கும் containers-க்கு ஆதாரமாக இருக்கும் images ஏற்கனவே குறிக்கப்பட்டுள்ளன (referenced):

docker image prune -a -f

பிறகு நிகழ்வுகள் (events) பற்றி பார்ப்போம். ClickHouse columnar தரவுகளை வலுவாகச் சுருக்குவதால் (compress), மூல நிகழ்வுகளின் அளவு மக்கள் எதிர்பார்ப்பதை விட மெதுவாகவே வளர்கிறது. dashboard வாசிக்கும் rollup tables, மூல அட்டவணையை விட அளவில் சிறியவை. ஊகிப்பதை விட அளவிடுவது சிறந்தது:

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

ஒவ்வொரு அட்டவணைக்குமான அளவைப் பெற, infra/selfhost/env/-ன் கீழ் generator உருவாக்கிய ClickHouse credentials-ஐப் பயன்படுத்தி இதை இயக்கவும்:

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;

முதல் வாரத்திலும், நான்காவது வாரத்திலும் இந்த அளவீட்டை எடுக்கவும். இரண்டு புள்ளிகள் உங்களுக்கு வளர்ச்சி விகிதத்தைத் தரும், அந்த விகிதம் வட்டின் அளவை எப்போது அதிகரிக்க வேண்டும் என்பதைத் தெரிவிக்கும். ஆகஸ்ட் 2026 நிலவரப்படி, self-hosting வழிகாட்டி மூல நிகழ்வுகளுக்கான எந்தவொரு retention அல்லது time-to-live அமைப்பையும் கொண்டிருக்கவில்லை. எனவே, பழைய தரவுகள் தானாகவே நீங்கிவிடும் என்று கருதாமல், நீங்கள் அளவிட்ட வளர்ச்சி விகிதத்திற்கு ஏற்ப வட்டின் அளவைத் தீர்மானிக்கவும்.

நீக்குதல் தொடர்பான ஒரு சிக்கலைத் தெரிந்துகொள்வது அவசியம். ஒரு site அல்லது account-ஐ நீக்கும்போது, அதற்கான பணி worker-க்கு வரிசைப்படுத்தப்படும். அந்த worker-க்கு CLICKHOUSE_MAINTENANCE_USER மற்றும் CLICKHOUSE_MAINTENANCE_PASSWORD அமைக்கப்பட்டிருக்க வேண்டும், மேலும் ClickHouse-ல் அதற்கு இணையான oa_maintenance user இருக்க வேண்டும். இவை இல்லையென்றால், நீக்குதல் பணி நிரந்தரமாக வரிசையிலேயே இருக்கும். dashboard-லிருந்து அந்த site மறைந்துவிடும், ஆனால் அனைத்து தரவுகளும் வட்டில் அப்படியே இருக்கும். இதனால், தரவுகள் நீக்கப்பட்டுவிட்டதாகத் தோன்றும், ஆனால் வட்டில் இடம் கிடைக்காது.

மேம்படுத்தல்கள் மற்றும் மூன்று செலவுகள்

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

upgrade.sh செயல்படுவதற்கு முன்பு மூன்று செலவுகளைக் குறிப்பிடுகிறது. Downtime என்பது நிஜமானது: collector செயலிழந்து இருக்கும்போது முயற்சி செய்யப்படும் நிகழ்வுகள் இழக்கப்படுகின்றன, ஏனெனில் tracker அவற்றை மீண்டும் முயற்சிப்பதில்லை. Rollback தரவை இழக்கச் செய்கிறது, ஏனெனில் rollback.sh --to backups/<snapshot> இரண்டு stores-களையும் மொத்தமாக மாற்றியமைத்து, அந்த snapshot எடுக்கப்பட்ட பிறகு எழுதப்பட்ட ஒவ்வொரு வரிசையையும் நீக்கிவிடுகிறது. Disk என்பது மூன்றாவது செலவு, இது மேலே விவரிக்கப்பட்ட snapshot pile ஆகும்.

இரண்டு restart விதிகளைத் தவறாகப் புரிந்துகொள்வது எளிது. API-க்கு முன்பாக query gateway-ஐத் தொடங்கவும், ஏனெனில் புதிய API, பழைய gateway நிராகரிக்கும் query fields-ஐ அனுப்பக்கூடும். மேலும், ClickHouse-க்கு restart செய்வதை விட recreate செய்வது அவசியம், ஏனெனில் docker compose restart container-ன் அசல் environment-ஐ மீண்டும் பயன்படுத்துகிறது மற்றும் நீங்கள் செய்த மாற்றங்களை அமைதியாகப் புறக்கணிக்கிறது:

docker compose up -d --force-recreate clickhouse

Dashboard-லும் இதே போன்ற சிக்கல் உள்ளது. env/web.env-ல் உள்ள மூன்று NEXT_PUBLIC_* origins-களும் browser bundle-க்குள் compile செய்யப்பட்டு, container தொடங்கும் போது மாற்றப்படுகின்றன. எனவே, தவறான hostname-ஐ அழைக்கும் dashboard, docker compose up -d --force-recreate web மூலம் சரிசெய்யப்பட வேண்டும், ஒருபோதும் restart மூலம் அல்ல. Web container-ன் log அது எந்த origins-களுடன் தொடங்கியது என்பதைக் காட்டுகிறது, இது திருத்தம் சரியாகச் செயல்படுகிறதா என்பதை உறுதிப்படுத்த விரைவான வழியாகும்.

Config மாற்றத்திற்குப் பிறகு ClickHouse தொடங்க மறுத்தால், அதன் log-ன் முதல் வரியைப் படிக்கவும். oa-entrypoint: என்று தொடங்கும் வரி, நீங்கள் அமைத்த மதிப்பை entrypoint நிராகரிப்பதைக் குறிக்கிறது. மற்றவை பொதுவாக config கோப்பு செல்லாத XML வடிவில் இருப்பதைக் குறிக்கும். இதற்கு மிக முக்கியமான காரணம் XML comment-க்குள் இருக்கும் double hyphen ஆகும், இது அங்கு அனுமதிக்கப்படாது.

AGPL-3.0 மற்றும் பெயர்

இந்தக் குறியீடு (code) AGPL-3.0 உரிமத்தின் கீழ் உள்ளது. மாற்றங்கள் செய்யாமல் உங்கள் தளங்களில் இதை இயக்குவதால், எந்தவொரு வெளியீட்டு கடமையும் உங்களுக்கு ஏற்படாது. நீங்கள் குறியீட்டை மாற்றி, அந்த மாற்றியமைக்கப்பட்ட பதிப்பை ஒரு network service-ஆக இயக்கும்போதுதான் இந்தக் கடமை தொடங்குகிறது: அவ்வாறு செய்யும்போது, மாற்றியமைக்கப்பட்ட source code-ஐ அந்தச் சேவையைப் பயன்படுத்தும் பயனர்களுக்கு வழங்க வேண்டும் என்று உரிமம் கோருகிறது. உங்கள் instance-ல் வாடிக்கையாளர்களுக்கு dashboard வழங்குவது அல்லது நீங்கள் விற்கும் ஒரு பொருளுடன் இதை இணைப்பது ஆகியவையும் இதில் அடங்கும். உங்கள் மாற்றங்களை ஒரு public fork-ஆக வைத்திருப்பது, கூடுதல் நடைமுறைகள் ஏதுமின்றி இந்த உரிம நிபந்தனையை நிறைவு செய்யும்.

இந்தத் தயாரிப்பின் பெயர் (brand) குறியீட்டிலிருந்து தனிப்பட்டது. "OpenAnalytics" என்ற பெயர் மற்றும் திட்டத்தின் hosted domain ஆகியவை அதன் ஆசிரியர்கள் இயக்கும் instance-ஐக் குறிக்கின்றன; அவை உரிமத்தின் ஒரு பகுதி அல்ல. உங்கள் deployment இந்த மென்பொருளை அந்தப் பெயர் இல்லாமலேயே இயக்குகிறது, எனவே பணம் செலுத்தும் வாடிக்கையாளர்களுக்குச் சேவையை வழங்குவதற்கு முன், அதற்கு நீங்களே ஒரு பெயரைச் சூட்டுங்கள்.

FAQ

1 GB VPS-ல் என்னால் OpenAnalytics-ஐ இயக்க முடியுமா?

முடியாது. இந்த project-க்கு சுமார் 4 GB RAM மற்றும் 25 GB காலி வட்டு இடம் தேவைப்படுகிறது. ஏனெனில், ஒரு deployment-ல் Postgres, ClickHouse மற்றும் இரண்டு Valkey instances ஆகியவற்றுடன் ஆறு application services இயங்குகின்றன. ClickHouse ஒரு சிறிய process அல்ல. 1 GB அளவுள்ள server-ல் containers தொடங்கினாலும், kernel-ன் out-of-memory killer ஏதேனும் ஒன்றை, பெரும்பாலும் ClickHouse-ஐ, நிறுத்திவிடும். 1 GB திட்டம் மட்டுமே சாத்தியம் என்றால், SQLite-ஐப் பயன்படுத்தி, வெளிப்புற database இன்றி இயங்கும் GoatCounter போன்ற single-binary கருவியைப் பயன்படுத்தவும்.

OpenAnalytics-க்கு cookie banner தேவையா?

இது உங்கள் வழக்கறிஞர் முடிவு செய்ய வேண்டிய விஷயம், ஆனால் தொழில்நுட்ப ரீதியாக உங்களுக்குச் சாதகமான அம்சங்கள் உள்ளன. இதில் cookies பயன்படுத்தப்படுவதில்லை; பார்வையாளரின் அடையாளம் தினசரி மாறும் salted hash மூலம் குறிக்கப்படுகிறது. மூல IP முகவரிகள் சேமிக்கப்படுவதில்லை, எனவே பார்வையாளரை அடையாளம் காணும் வகையில் நிரந்தரமான தரவு எதுவும் எழுதப்படுவதில்லை. இருப்பினும், நீங்கள் எதைச் சேமிக்கிறீர்கள் மற்றும் எவ்வளவு காலம் வைத்திருக்கிறீர்கள் என்பது GDPR விதிகளுக்கு உட்பட்டது. தரவு சேகரிப்பை முறைப்படுத்த விரும்பினால், script tag-ல் data-require-consent-ஐ அமைக்கவும்: அப்போதுதான் பயனர் அனுமதி அளிக்கும் வரை tracker எதையும் சேகரிக்காது, மேலும் அந்த அனுமதி oa.consent-ன் கீழ் localStorage-ல் சேமிக்கப்படும்.

events ஏன் 202 குறியீட்டைத் தருகின்றன, ஆனால் dashboard-ல் தெரிவதில்லை?

202 என்பது collector அந்த event-ஐ ஏற்றுக்கொண்டு வரிசையில் (queue) சேர்த்துள்ளது என்பதைக் குறிக்கிறதே தவிர, அது சேமிக்கப்பட்டுவிட்டது என்று அர்த்தமல்ல. worker அந்த வரிசையிலிருந்து தரவை எடுத்து ClickHouse-ல் சேர்க்கும். எனவே, கோரிக்கைகள் வெற்றிகரமாக இருந்து dashboard காலியாக இருந்தால், worker-ல் சிக்கல் உள்ளது என்று பொருள். docker compose logs --tail=50 worker-ஐப் படித்து, Valkey வரிசையின் அளவைக் கவனிக்கவும். வரிசை தொடர்ந்து வளர்ந்துகொண்டே இருந்தால், worker தடுக்கப்பட்டுள்ளது என்று அர்த்தம். இதற்கு, worker.env-ல் உள்ள ClickHouse credentials தவறாக இருப்பது அல்லது சமீபத்திய migration-ல் உருவாக்கப்பட்ட table-க்குத் தேவையான அனுமதி (grant) விடுபட்டிருப்பதுதான் பொதுவான காரணங்கள்.

அனைத்து containers-ம் சரியாக இயங்கும்போது dashboard ஏன் காலியாக உள்ளது?

முதலில் env/api.env-ல் உள்ள AUTH_TRUSTED_ORIGINS-ஐச் சரிபார்க்கவும். இது dashboard origin-உடன் சரியாகப் பொருந்த வேண்டும். பொருந்தவில்லை எனில், API எந்த CORS headers-ஐயும் வழங்காது; இதனால் browser அனைத்து அழைப்புகளையும் நிராகரிக்கும், உங்களுக்குத் தரவுகள் இன்றி dashboard அமைப்பு மட்டும் தெரியும். இரண்டாவதாக, env/web.env-ல் உள்ள மூன்று NEXT_PUBLIC_* மதிப்புகளைச் சரிபார்க்கவும். web container தொடங்கும்போது இவை மாற்றப்படும். இவற்றைச் சரிசெய்ய docker compose up -d --force-recreate web தேவை, ஏனெனில் சாதாரண restart பழைய மதிப்புகளையே வைத்திருக்கும்.

AGPL-3.0 உரிமம், இதை வாடிக்கையாளர்களுக்கு வழங்குவதைத் தடுக்கிறதா?

இல்லை, இது ஒரே ஒரு நிபந்தனையை மட்டுமே விதிக்கிறது. குறியீட்டை மாற்றாமல் பயன்படுத்தினால் நீங்கள் யாருக்கும் எதையும் வழங்க வேண்டியதில்லை. மாற்றங்களைச் செய்து, அந்த மாற்றியமைக்கப்பட்ட பதிப்பை மற்றவர்கள் பயன்படுத்தும் சேவையாக வழங்கினால், அந்தப் பயனர்களுக்கு உங்கள் மாற்றியமைக்கப்பட்ட source code-ஐ வழங்க வேண்டும்; ஒரு public fork மூலம் இதைச் செய்யலாம். மேலும், "OpenAnalytics" என்ற பெயர் குறியீட்டுடன் உரிமம் பெறப்படவில்லை, எனவே நீங்கள் விற்கும் எந்தவொரு பொருளுக்கும் தனிப் பெயர் வைத்திருக்க வேண்டும்.