OpenAnalytics-ஐ சொந்தமாக VPS-ல் நிறுவுவது எப்படி?

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

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

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

உங்களுக்கு ஒரே ஒரு 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-ஐச் சுட்டிக்காட்ட வேண்டும். ஏனெனில், 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-ஐப் பார்ப்பது நல்லது. நிறுவல் (install) செயல்முறையை மீண்டும் இயக்குவதால் DNS propagation வேகம் அதிகரிக்காது.

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

ஒரு tagged release-ஐ checkout செய்யவும். Default branch-ல் தான் மேம்பாட்டுப் பணிகள் நடக்கும், வெளியிடப்பட்ட images-க்கு அந்த release tag-தான் பொருந்தும். 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-ஐப் பதிவிறக்கும். இதைத் தவிர்த்தால் ஒவ்வொரு 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 செய்யப்பட்டுள்ளன, மேலும் இவற்றை மீண்டும் அதே மதிப்புகளுடன் உருவாக்க முடியாது.

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

• Store passwords-ஐ இழந்தால், Postgres மற்றும் ClickHouse-க்குள் நுழைய முடியாது; இவற்றை container-க்குள் இருந்து மட்டுமே reset செய்ய முடியும்.
• OA_CREDENTIAL_KEYRING-ஐ இழந்தால், சேமிக்கப்பட்ட அனைத்து third-party நற்சான்றிதழ்களும் (credentials) மீட்க முடியாததாகிவிடும்; எனவே Stripe கணக்கை இணைத்த எவரும் அதை மீண்டும் இணைக்க வேண்டியிருக்கும்.
• ANONYMOUS_IDENTITY_SECRET-ஐ இழந்தால், பார்வையாளர்களின் அடையாளம் (visitor identity) மீண்டும் தொடக்கத்திலிருந்து கணக்கிடப்படும்: நேற்று வந்த பார்வையாளர்கள் அனைவரும் புதியவர்களாகக் கருதப்படுவார்கள், இது வரைபடங்களில் (charts) மாற்றத்தை ஏற்படுத்தும்.
• AUTH_SECRET-ஐ இழந்தால், அனைத்து session-களும் செல்லாததாகிவிடும், எனவே பயனர்கள் அனைவரும் மீண்டும் 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-ஆக compile செய்துவிட்டு அதுவும் வெளியேறிவிடும். மற்ற அனைத்தும் docker compose ps-ல் healthy என்று காட்ட வேண்டும். ஒரு service மீண்டும் மீண்டும் restart ஆகிறது என்றால், அது பெரும்பாலும் environment validation-ல் தோல்வியடைகிறது என்று அர்த்தம்; 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 செய்ய சுமார் பத்து நிமிடங்கள் ஆகும். Image-களை pull செய்ய சில நிமிடங்கள் ஆகும், இதற்காகவே release images வழங்கப்படுகின்றன.

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

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

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

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

<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-ல் எவரும் பார்க்கும் வகையில் வைக்கலாம். இந்த script window.oa-ஐ நிறுவுகிறது. oa("track", ...) போன்ற அழைப்புகள் ஒரு stub மூலம் வரிசைப்படுத்தப்பட்டு, கோப்பு ஏற்றப்பட்டவுடன் செயல்படுத்தப்படும். எனவே, தொடக்கத்திலேயே தூண்டப்படும் custom event-கள் இழக்கப்படாது. பக்கத்தில் ஏற்கனவே window.oa பயன்பாட்டில் இருந்தால், tracker அதற்குப் பதிலாக window.openanalytics ஆக நிறுவப்படும்.

பின்பு, முழுப் பாதையையும் சரிபார்க்கவும்:

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 அளவிலான தரவை வெளியீடாகக் காட்ட வேண்டும். உங்கள் தளத்தில் ஒரு பக்கத்தை ஏற்றவும், சில நொடிகளில் worker log-ல் batch வரியைத் தேடவும். ஒரு event-ஐ ஏற்றுக்கொண்டவுடன் collector 202 என்று பதிலளிக்கும். 202 என்பது event வரிசைப்படுத்தப்பட்டதைக் குறிக்கும், அது இன்னும் சேமிக்கப்படவில்லை. 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-ஐப் பயன்படுத்தவும், அதன் 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, client IP-லிருந்து தினசரி visitor hash-ஐ உருவாக்குகிறது, எனவே அது connection-லிருந்து அந்த முகவரியைப் பெற வேண்டுமே தவிர, header-லிருந்து பெறக்கூடாது. நம்பகத்தன்மையற்ற hop-லிருந்து CF-Connecting-IP-ஐ அனுமதிப்பது, எந்தவொரு caller-ம் எந்த முகவரியையும் உரிமை கோர வழிவகுக்கும்; இது geolocation-ஐப் பாதிப்பதோடு visitor எண்ணிக்கையையும் தவறாக உயர்த்தும்.

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

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

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

Cookieless என்பது இங்கே எதைக் குறிக்கிறது மற்றும் அதன் விளைவுகள் என்ன

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

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

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

இந்த collector, 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-ன் போது, பழைய பதிப்பை நீக்குவதற்கு முன்பே புதிய பதிப்பு தரவிறக்கம் செய்யப்படுவதால், சிறிது காலம் இரண்டு தலைமுறை images-களும் வட்டில் இருக்கும். ஒரு page view கூட வருவதற்கு முன்பே, இதுவே 25 GB தேவையில் பெரும்பகுதியை எடுத்துக்கொள்கிறது.

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

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

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

docker image prune -a -f

பிறகு நிகழ்வுகள் (events) குறித்த தரவுகள். ClickHouse columnar தரவுகளை மிகச் சிறப்பாகச் சுருக்குவதால், raw event-களின் அளவு பெரும்பாலானோர் எதிர்பார்ப்பதை விட மெதுவாகவே வளரும். Dashboard வாசிக்கும் rollup tables-ன் அளவு raw table-ஐ விட மிகச் சிறியது. ஊகிப்பதற்குப் பதிலாக அளவீடு செய்யுங்கள்:

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

ஒவ்வொரு table-ன் அளவையும் அறிய, 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 வழிகாட்டியில் raw events-க்கான retention அல்லது time-to-live வசதி எதுவும் இல்லை. எனவே, பழைய தரவுகள் தானாகவே நீங்கிவிடும் என்று கருதாமல், நீங்கள் அளவிட்ட வளர்ச்சி விகிதத்திற்கு ஏற்ப வட்டின் அளவைத் தீர்மானிக்கவும்.

நீக்குதல் தொடர்பான ஒரு சிக்கலைத் தெரிந்துகொள்வது அவசியம். ஒரு site அல்லது account-ஐ நீக்கும்போது, அதற்கான பணி worker-க்கு அனுப்பப்படும். அந்த worker-க்கு CLICKHOUSE_MAINTENANCE_USER மற்றும் CLICKHOUSE_MAINTENANCE_PASSWORD அமைக்கப்பட்டிருக்க வேண்டும், மேலும் ClickHouse-ல் அதற்கு இணையான oa_maintenance user இருக்க வேண்டும். இவை இல்லையென்றால், நீக்கும் பணி நிரந்தரமாகக் காத்திருப்புப் பட்டியலில் (queue) இருக்கும். 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 குவியல் ஆகும்.

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

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 மற்றும் பெயர்

இந்தக் குறியீடு 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-ல் இயங்கும் மற்றும் external database தேவையில்லாத GoatCounter போன்ற single-binary கருவியைப் பயன்படுத்தவும்.

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

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

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

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

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

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

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

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