# Spaceship Supreme — release 0.20.1

আপনার দেওয়া database version হলো `11.4.13-MariaDB-cll-lve`; screenshot-এ Node.js `24.20.0` আছে। **Node.js 24.20.0 নির্বাচন করুন।** Panel-এ পুরোনো 14.x-এর পাশে “recommended” লেখা থাকলেও এই project-এর জন্য 24.x প্রয়োজন।

এই package-এ Spaceship-এর জন্য পৃথক hosting profile তৈরি হয়েছে। **Local tests ও static verification সফল হলেও MariaDB server, Passenger এবং আপনার hosting account-এ live acceptance এখনও বাকি।** এটি fresh installation-এর candidate; চালু MySQL database সরাসরি রূপান্তর করার package নয়।

## এই profile-এ যা বদলেছে

| অংশ             | ব্যবস্থা                                                                                                    |
| --------------- | ----------------------------------------------------------------------------------------------------------- |
| Runtime         | Node 24, cPanel-এর Passenger-managed web application                                                        |
| Database        | Explicit `mariadb` dialect; 11.4.13 বা পরের 11.4 patch                                                      |
| Migrations      | `database/mariadb/migrations`-এ পৃথক ২৪টি migration; একই ৬টি seed                                           |
| Rate limit      | Database transaction ও row lock; Redis লাগবে না                                                             |
| Background jobs | একটিমাত্র finite cron; কমপক্ষে ৫ মিনিট ব্যবধান                                                              |
| Limits          | প্রতি process-এ default ৩টি DB connection, queue ৩০, প্রতি SQL statement ৫ সেকেন্ড, lock wait ৩ সেকেন্ড     |
| Cron runtime    | ৩০ সেকেন্ড পরে নতুন batch শুরু বন্ধ; process-এর সর্বোচ্চ সময় ৪৫ সেকেন্ড                                     |
| Delivery        | প্রতি run-এ সর্বোচ্চ ১০টি message attempt, ২৫টি reminder recipient এবং ২৫টি broadcast recipient materialize |

Task start/claim, server timer, authentication, wallet এবং withdrawal request HTTP API-তেই হয়। Notifications, reminder delivery ও statistics cron-এ হয়। স্বাভাবিক অবস্থায় notification কয়েক মিনিট পরে পৌঁছাতে পারে; backlog, failed delivery বা missed cron থাকলে আরও দেরি হবে। ৫ মিনিট অন্তর চালালে সর্বোচ্চ ১২০টি message attempt/hour; এই সংখ্যা guaranteed throughput নয়। Cron-এর সময় সামান্য এগিয়ে-পিছিয়ে হলে persistent ৩০০-second guard একটি run পিছিয়ে দিতে পারে।

Spaceship-এর [shared-hosting policy](https://www.spaceship.com/legal/hosting-aup/) অনুযায়ী standalone daemon এবং ৫ মিনিটের কম ব্যবধানে cron চালানো যাবে না। এই profile-এ `worker.js` ও `scheduler.js` শুরু করতে গেলে application প্রত্যাখ্যান করে। PM2, systemd, Docker বা infinite worker shared account-এ চালাবেন না। cPanel-এর অনুমোদিত Node application manager দিয়েই web app চলবে।

## cPanel প্রস্তুতি

1. cPanel → **Setup Node.js App** → Create Application খুলুন।
2. Node version: **24.20.0**; mode: **Production**।
3. Application root হিসেবে public document root-এর বাইরে directory দিন, যেমন `telegram-task-earning`। ZIP extract করার পরে ওই directory-র সরাসরি ভিতরে `package.json` ও `server.js` থাকতে হবে। দ্বিগুণ nested directory হলে root সেই অনুযায়ী ঠিক করুন।
4. Application URL-এ dedicated HTTPS domain/subdomain-এর root নির্বাচন করুন। `/miniapp` application URL হিসেবে দেবেন না; app নিজে সেই route তৈরি করে।
5. Startup file: `infrastructure/cpanel/passenger-entry.cjs`। Panel nested startup path না নিলে root-এ `passenger.cjs` বানিয়ে নিচের content দিন এবং startup file হিসেবে সেটি নির্বাচন করুন:

```js
import('./server.js').catch(() => {
  process.stderr.write('Application startup failed. Check protected logs.\n');
  process.exitCode = 1;
});
```

6. cPanel database manager-এ **নতুন খালি database** এবং সংশ্লিষ্ট user বানান। Migrations-এর জন্য CREATE/ALTER/INDEX/REFERENCES/TRIGGER/CREATE VIEW এবং DML privilege প্রয়োজন; provider-এর database user controls অনুযায়ী দিন। Runtime user-এ প্রয়োজনীয় DML ও SELECT privilege রাখুন। View/trigger definer account মুছে ফেলবেন না।
7. এই profile-এর জন্য `.env.example` নয়, `infrastructure/cpanel/spaceship.env.example` থেকে private `.env` তৈরি করুন। সব placeholder নিজের configuration দিয়ে পূরণ করুন এবং file permission `0600` রাখুন। Panel-এর environment variables ব্যবহার করলে cron-এর shell-এও একই values থাকতে হবে; Passenger-এর variables cron-এ স্বয়ংক্রিয়ভাবে পৌঁছাবে এমন ধরে নেবেন না।
8. Panel-এর Node environment activate করে dependencies install করুন। npm scriptগুলোতে পূর্ণ path দরকার হলে panel যে activation command দেখায় সেটি ব্যবহার করুন। এই command-এ account-specific path থাকে; আন্দাজ করে অন্য account-এর path ব্যবহার করবেন না।

Node setup-এর official workflow: [Spaceship Node.js application guide](https://www.spaceship.com/knowledgebase/setup-nodejs-application-spaceship-hosting/).

## Environment values

নিচের values template-এ আগে থেকেই আছে:

```dotenv
NODE_ENV=production
HOSTING_PROFILE=spaceship
DATABASE_DIALECT=mariadb
DATABASE_CONNECTION_LIMIT=3
DATABASE_QUEUE_LIMIT=30
REDIS_ENABLED=false
RATE_LIMIT_STORE=database
QUEUE_CONCURRENCY=1
QUEUE_BATCH_SIZE=1
QUEUE_LEASE_SECONDS=60
SESSION_COOKIE_SECURE=true
LOG_FORMAT=json
```

অবশ্যই নিজের values দিতে হবে: `APP_ORIGIN`, `TELEGRAM_WEB_APP_URL`, `CORS_ALLOWED_ORIGINS`, database name/user/password, bot token/username, webhook secret এবং সব encryption/session/security key। App origin হবে যেমন `https://earn.your-domain.tld`; Mini App URL হবে একই origin-এর `/miniapp`। `UPLOAD_ROOT` ও `LOG_DIRECTORY` private application directory অনুযায়ী resolve হচ্ছে কি না দেখুন। Public media ছাড়া private storage web থেকে accessible হওয়া চলবে না।

`REDIS_URL` template-এ একটি syntactically valid কিন্তু unused value হিসেবে থাকে; disabled profile-এ কোনো Redis connection হবে না। Rate limiter database unavailable হলে request **503** দিয়ে বন্ধ হয়; memory fallback নেই। Optional cache সরাসরি database থেকে তথ্য নেয়।

`TRUST_PROXY=loopback` একটি starting template value। Spaceship-এর বাস্তব Passenger/proxy path ও forwarded-header sanitization যাচাই করে সেটি ঠিক করুন। `true` দিয়ে সব forwarded IP বিশ্বাস করা যাবে না। Secure cookie, client IP, HTTPS redirect ও forged forwarded-header test live acceptance-এর অংশ।

## Installation commands

নিচের commandগুলো activated Node 24 environment-এ application root থেকে চালাতে হবে। Shared host-এ পুরো test suite বা Docker acceptance চালানোর দরকার নেই; সেগুলো development/CI machine-এর কাজ।

```bash
npm ci --omit=dev --include=optional
npm run verify:environment
npm run database:check
npm run migrate
npm run seed
npm run release:check
```

ZIP-এ built CSS আছে; production dependencies install করলেই server assets পাবে। Panel-এ কেবল **Run NPM Install** থাকলে সেটি দিয়ে installation করে dependency/native-module ফলাফল দেখুন; `sharp` optional native dependencies বাদ দেবেন না।

MariaDB dialect অনুযায়ী `migrate`, `seed`, `rollback`, web startup ও release preflight একই migration directory নির্বাচন করে। Dry run-এ private environment ছাড়াই পরিকল্পনা দেখা যায়:

```bash
npm run migrate:dry-run -- --dialect=mariadb
npm run seed:dry-run -- --dialect=mariadb
```

প্রথম administrator-এর private bootstrap environment সাময়িকভাবে সেট করে `npm run admin:create` চালান; existing admin/TOTP enrollment guide অনুসরণ করুন। Bootstrap password কাজ শেষে environment থেকে সরান। Server restart করে `/health/live`, protected `/health/ready`, `/admin` এবং `/miniapp` যাচাই করুন। Health preflight সফল হওয়া একা পূর্ণ acceptance নয়।

## একটি cron job

Cron schedule দিন:

```cron
*/5 * * * *
```

Command-এর template:

```bash
cd /home/CPANEL_USER/telegram-task-earning && /ABSOLUTE/NODE24/PATH/bin/node bin/run-shared-cron.js >> storage/logs/shared-cron.log 2>&1
```

`CPANEL_USER` ও Node path panel থেকে পাওয়া সঠিক values দিয়ে বদলাতে হবে। Node-এর full path জানতে activated environment-এ `command -v node` ব্যবহার করুন। Log directory আগে তৈরি করুন এবং public access বন্ধ রাখুন। Cron log-এর rotation configure করুন।

Runner database-scoped advisory lock ধরে পুরো কাজ শেষ করে; concurrent run কাজ শুরু করে না। Database-এর persistent timestamp restart-এর পরও অন্তত ৩০০ সেকেন্ড ব্যবধান নিশ্চিত করে। Default কাজ: expired rate-limit bucket cleanup, due reminders/broadcasts materialize, analytics rollup, queued Telegram messages পাঠানো। Pending batches পরের cron-এ চলবে। কোনো public cron URL নেই।

`failed` result দেখলে generic status থেকে সংশ্লিষ্ট job/admin queue screen পরীক্ষা করুন। `partial` হলে সময় শেষ হওয়ায় কিছু batch পরের run-এর জন্য deferred হয়েছে। হার্ড timeout চলমান transaction rollback করতে পারে। Telegram request পৌঁছেছে কিন্তু acknowledgement হারিয়েছে এমন অবস্থায় delivery retry-তে duplicate message হতে পারে; outbox retry controls বজায় আছে, exactly-once provider delivery দাবি করা হচ্ছে না।

Live Telegram webhook registration ও message sending শুধুমাত্র staging checks শেষ করে নিজের installation চালু করার সময় করুন। এই release তৈরির সময় webhook update বা কোনো message পাঠানো হয়নি।

## MariaDB compatibility details

Original MySQL migration/seed files অপরিবর্তিত। MariaDB-এর পৃথক lineage-এ 001–023-এর forward business DDL একই আছে; rollback-এর `DROP CHECK` বদলে `DROP CONSTRAINT` করা হয়েছে। Lineage comment-এর কারণে file checksums আলাদা, তাই MySQL migration history নিয়ে ভুল profile চালালে integrity check ব্যর্থ হয়। Migration 024 যোগ করে `rate_limit_buckets` ও `shared_runtime_state`।

MariaDB 11.4.5 থেকে MySQL-compatible collation aliases আছে; `utf8mb4_0900_ai_ci` MariaDB-তে `utf8mb4_uca1400_nopad_ai_ci`-এর alias। নাম এক হলেও MySQL-এর Unicode ordering-এর সঙ্গে সম্পূর্ণ এক নয়। এই কারণে এটি fresh-install profile; populated MySQL data-এর collation/unique-key conversion আলাদা migration project। [MariaDB compatibility notes](https://mariadb.com/docs/release-notes/community-server/about/compatibility-and-differences/incompatibilities-and-feature-differences-between-mariadb-11-4-and-mysql-8), [collation reference](https://mariadb.com/docs/server/reference/data-types/string-data-types/character-sets/supported-character-sets-and-collations).

MariaDB JSON হলো validated text। Repositories JSON string/object দুটো handle করে; profile merge-তে shared JSON syntax, privacy/notification flags-এ explicit boolean text comparison, referral locking-এ `LOCK IN SHARE MODE` এবং announcement query-তে strict GROUP BY-compatible counting ব্যবহার হয়। [MariaDB JSON reference](https://mariadb.com/docs/server/reference/data-types/string-data-types/json).

## Database ও hosting acceptance — এখনও বাকি

Developer/CI machine-এ MariaDB 11.4.13-এর isolated suite চালানোর configuration দেওয়া আছে:

```bash
docker compose -f infrastructure/docker/compose.mariadb-acceptance.yml up --build --abort-on-container-exit --exit-code-from acceptance
```

Suite নতুন খালি `tte_acceptance` database ছাড়া চলবে না। এটি migrations/seeds, duplicate reward races, competing withdrawal holds, immutable ledger triggers, concurrent outbox claims, JSON/profile queries, analytics, database rate-limit concurrency এবং cron concurrency/cadence পরীক্ষা করে। Real Telegram sender চালায় না। Containers disposable; production database-এর সঙ্গে acceptance runner connect করবেন না।

এই workspace-এ MariaDB/Docker server নেই, তাই live suite execute করা হয়নি। Shared host-এ আরও যাচাই করতে হবে: migration privileges/SQL execution; native `sharp`; Passenger startup/restart; correct proxy/IP handling; outbound HTTPS to Telegram; secure login/TOTP; task claim; withdrawals; scheduled delivery; realistic resource usage; এবং backup restore। Local tests database server-এর বিকল্প নয়।

Backups-এর জন্য `npm run backup -- database --dialect=mariadb ...` ব্যবহার করলে `mariadb-dump` লাগে এবং dump process ৪৫ সেকেন্ডে সীমাবদ্ধ থাকে। Native client availability ও privileges যাচাই করুন। বড় database dump/analytics যদি host-এর budget ছাড়ায়, provider-supported export/off-host processing লাগতে পারে; shared account-এ সময়সীমা এড়িয়ে infinite process চালাবেন না। Database ও media restore প্রথমে আলাদা environment-এ যাচাই করতে হবে।

Readiness সফল, private data inaccessible, real browser/Telegram journeys এবং isolated restore যাচাইয়ের পরে production traffic খুলুন।