സ്വന്തം ഹോസ്റ്റിംഗ് വഴികാട്ടി
Nibomo രണ്ട് വ്യത്യസ്ത വഴികൾ പിന്തുണയ്ക്കുന്നു: ഒരു ലോക്കൽ ഡെവലപ്മെന്റ് എൻവയോൺമെന്റും AWS ലെ ഒരു പ്രൊഡക്ഷൻ ഡിപ്ലോയ്മെന്റും. ലോക്കൽ ഡെവലപ്മെന്റിനായി Docker Compose PostgreSQL ഉം മൈഗ്രേഷനുകളും പ്രവർത്തിപ്പിക്കുന്നു; അത് പ്രൊഡക്ഷൻ ഡിപ്ലോയ്മെന്റ് രീതിയല്ല.
ലോക്കൽ ഡെവലപ്മെന്റിനുള്ള ആവശ്യകതകൾ
- Git
- Bash
- GNU Make
- Docker Compose ഉള്ള Docker
- Node.js 24
- npm
നൽകിയിരിക്കുന്ന Docker Compose ഫയൽ നിലവിൽ PostgreSQL 18.4 പ്രവർത്തിപ്പിക്കുന്നു. വേറിട്ട ലോക്കൽ PostgreSQL ഇൻസ്റ്റാളേഷൻ ആവശ്യമില്ല.
ലോക്കൽ ക്വിക്ക് സ്റ്റാർട്ട്
git clone https://github.com/kirill-markin/flashcards-open-source-app.git
cd flashcards-open-source-app
cp .env.example .env
make db-up
npm install --prefix api
npm install --prefix apps/auth
npm install --prefix apps/backend
npm install --prefix apps/web
npm install --prefix apps/admin
make db-up PostgreSQL തുടങ്ങുകയും മൈഗ്രേഷൻ കണ്ടെയ്നർ വഴി scripts/deploy/migrate.sh പ്രവർത്തിപ്പിക്കുകയും ചെയ്യുന്നു. .env.example ൽ നിന്ന് പകർത്തിയ ഡിഫോൾട്ട് പാസ്വേഡുകൾ ഉപയോഗിക്കുമ്പോൾ, മൈഗ്രേഷൻ ഈ ലോക്കൽ റൺടൈം കണക്ഷനുകൾ സജ്ജമാക്കുന്നു:
- ബാക്കെൻഡ്:
postgresql://backend_app:backend_app@localhost:5432/flashcards - ഓതന്റിക്കേഷൻ:
postgresql://auth_app:auth_app@localhost:5432/flashcards - റിപ്പോർട്ടിംഗ്:
postgresql://reporting_readonly:reporting_readonly@localhost:5432/flashcards
.env ൽ BACKEND_DB_PASSWORD, AUTH_DB_PASSWORD, അല്ലെങ്കിൽ REPORTING_DB_PASSWORD മാറ്റുകയാണെങ്കിൽ, ബന്ധപ്പെട്ട കണക്ഷൻ URL ലും അതേ മാറ്റിയ പാസ്വേഡ് ഉപയോഗിക്കുക.
വേഗത്തിലുള്ള, ലോക്കലിൽ മാത്രമുള്ള തുടക്കം
ബാക്കെൻഡ് Make ടാർഗറ്റ് റൂട്ടിലെ .env ലോഡ് ചെയ്യുന്നില്ല. ആവശ്യമായ ലോക്കൽ ക്രമീകരണങ്ങൾ വ്യക്തമായി നൽകുക:
AUTH_MODE=none \
ALLOW_INSECURE_LOCAL_AUTH=true \
DATABASE_URL=postgresql://backend_app:backend_app@localhost:5432/flashcards \
REPORTING_DATABASE_URL=postgresql://reporting_readonly:reporting_readonly@localhost:5432/flashcards \
make backend-dev
ക്ലയന്റുകൾ വേറിട്ട ടെർമിനലുകളിൽ പ്രവർത്തിപ്പിക്കുക:
make web-dev
make admin-dev
ഈ വഴി മനഃപൂർവം make auth-dev തുടങ്ങുന്നില്ല. AUTH_MODE=none വ്യക്തമായും സുരക്ഷിതമല്ലാത്ത, localhost ൽ മാത്രം ഉപയോഗിക്കാനുള്ള മോഡാണ്; ഡിപ്ലോയ് ചെയ്ത എൻവയോൺമെന്റിൽ ഒരിക്കലും ഇത് ഉപയോഗിക്കരുത്.
ഇത് കോർ ബാക്കെൻഡ്, പൊതു Agent API ഡിസ്കവറി, വെബ്, അഡ്മിൻ ഡെവലപ്മെന്റ് എന്നിവ ഉൾക്കൊള്ളുന്നു, പക്ഷേ Chat V2 ലഭ്യമാക്കുന്നില്ല.
പൂർണ്ണ ലോക്കൽ Cognito ഫ്ലോ
ഓതന്റിക്കേഷൻ ടാർഗറ്റ് റൂട്ടിലെ .env ലോഡ് ചെയ്യുന്നു, ബാക്കെൻഡ് ടാർഗറ്റ് ചെയ്യുന്നില്ല. ആദ്യം പകർത്തിയ .env ലെ പഴയ DATABASE_URL ഓതന്റിക്കേഷൻ റോളിന്റെ URL കൊണ്ട് മാറ്റി, നിങ്ങളുടെ യഥാർത്ഥ Cognito മൂല്യങ്ങൾ ചേർക്കുക:
DATABASE_URL=postgresql://auth_app:auth_app@localhost:5432/flashcards
AUTH_MODE=cognito
COGNITO_USER_POOL_ID=<your-user-pool-id>
COGNITO_CLIENT_ID=<your-client-id>
COGNITO_REGION=<your-aws-region>
SESSION_ENCRYPTION_KEY=<64-character-hex-value>
ഓതന്റിക്കേഷൻ തുടങ്ങുക:
make auth-dev
ബാക്കെൻഡ് ടെർമിനലിൽ, .env വ്യക്തമായി ലോഡ് ചെയ്യുക, തുടർന്ന് ആ പ്രോസസ്സിനായി അതിലെ ഓതന്റിക്കേഷൻ ഡാറ്റാബേസ് URL ബാക്കെൻഡ് റോളിന്റെ URL കൊണ്ട് ഓവർറൈഡ് ചെയ്യുക:
set -a
source .env
set +a
DATABASE_URL=postgresql://backend_app:backend_app@localhost:5432/flashcards \
make backend-dev
make web-dev, make admin-dev എന്നിവ അവയുടെ സ്വന്തം ടെർമിനലുകളിൽ പ്രവർത്തിപ്പിക്കുക. രണ്ട് ടാർഗറ്റുകളും റൂട്ടിലെ .env ലോഡ് ചെയ്യുന്നു.
സേവനങ്ങൾ ഈ ലോക്കൽ വിലാസങ്ങൾ ഉപയോഗിക്കുന്നു:
| സേവനം | വിലാസം |
|---|---|
| PostgreSQL | localhost:5432 |
| ഓതന്റിക്കേഷൻ, കോൺഫിഗർ ചെയ്തിട്ടുണ്ടെങ്കിൽ | http://localhost:8081 |
| ബാക്കെൻഡ് API | http://localhost:8080/v1 |
| വെബ് ആപ്പ് | http://localhost:3000 |
| അഡ്മിൻ ആപ്പ് | http://localhost:3001 |
PostgreSQL ഉം മൈഗ്രേഷൻ കണ്ടെയ്നറും നിർത്താൻ:
make db-down
ലോക്കൽ കോൺഫിഗറേഷൻ
.env.example ൽ നിന്ന് തുടങ്ങുക; ലഭ്യമായ വേരിയബിളുകളും ഏതൊക്കെ മൂല്യങ്ങൾ ലോക്കലിൽ മാത്രമുള്ളതാണെന്നും അതിൽ വിവരിച്ചിരിക്കുന്നു. മുകളിൽ കാണിച്ചതുപോലെ, ഓതന്റിക്കേഷൻ പ്രവർത്തിപ്പിക്കുന്നതിന് മുമ്പ് അതിലെ പഴയ DATABASE_URL മാറ്റുക.
പ്രധാന ലോക്കൽ ക്രമീകരണങ്ങൾ:
- Docker നുള്ളിലെ സ്കീമ മൈഗ്രേഷനുകൾക്കായി
MIGRATION_DATABASE_URL make auth-devനായി റൂട്ടിലെ.envൽauth_appറോളിലേക്ക് സജ്ജമാക്കിയDATABASE_URLmake backend-devനായിbackend_appറോളായി നൽകുന്നDATABASE_URL- ബാക്കെൻഡ് ഓതന്റിക്കേഷനായി
AUTH_MODE,ALLOW_INSECURE_LOCAL_AUTH - ലോക്കൽ വെബ്, അഡ്മിൻ ഒറിജിനുകൾക്കായി
BACKEND_ALLOWED_ORIGINS - ബ്രൗസർ ഓതന്റിക്കേഷനായി
ALLOWED_REDIRECT_URIS,COOKIE_DOMAIN - യഥാർത്ഥ OTP പരീക്ഷിക്കുമ്പോൾ Cognito, സെഷൻ എൻക്രിപ്ഷൻ മൂല്യങ്ങൾ
Agent API ബാക്കെൻഡിന്റെ ഭാഗമാണ്. ബാക്കെൻഡ് തുടങ്ങിയ ശേഷം അതിന്റെ പൊതു ലോക്കൽ ഡിസ്കവറി രേഖ http://localhost:8080/v1/agent ൽ ലഭ്യമാണ്. സംരക്ഷിത Agent പ്രവർത്തനങ്ങൾക്ക് ApiKey ഓതന്റിക്കേഷൻ ആവശ്യമാണ്, അവ AUTH_MODE=none വഴിയിൽ ലഭ്യമല്ല.
ഓരോ വഴിയിലും AI യുടെ പരിധി
മുകളിലെ ലോക്കൽ കമാൻഡുകൾ അസിങ്ക്രണസ് ചാറ്റ് വർക്കർ തുടങ്ങുന്നില്ല. വേഗത്തിലുള്ള വഴി AUTH_MODE=none ഉം ഉപയോഗിക്കുന്നു, Chat V2 ഈ മോഡ് നിരസിക്കുന്നു; ഒരു OpenAI കീയോ അതിഥി ക്വോട്ടയോ ചേർത്താലും ആ വഴിയിൽ AI പ്രവർത്തിക്കില്ല. പൂർണ്ണ ലോക്കൽ Cognito ഫ്ലോ പിന്തുണയുള്ള ഒരു ഓതന്റിക്കേഷൻ ട്രാൻസ്പോർട്ട് നൽകുന്നു, പക്ഷേ അതും വർക്കർ തുടങ്ങുന്നില്ല.
AWS CDK ഡിപ്ലോയ്മെന്റ് വർക്കർ Lambda സൃഷ്ടിക്കുകയും അതിനെ വിളിക്കാൻ ബാക്കെൻഡിനെ കോൺഫിഗർ ചെയ്യുകയും ചെയ്യുന്നു. OPENAI_API_KEY പോലുള്ള ദാതാവിന്റെ ക്രെഡൻഷ്യലുകൾ പിന്തുണയുള്ള ഓതന്റിക്കേറ്റ് ചെയ്ത അഭ്യർത്ഥനകൾക്ക് മോഡൽ കോളുകൾ സാധ്യമാക്കുന്നു. GUEST_AI_WEIGHTED_MONTHLY_TOKEN_CAP അതിഥി AI വേറിട്ട് സജീവമാക്കുകയും പരിമിതപ്പെടുത്തുകയും ചെയ്യുന്നു; സൈൻ ഇൻ ചെയ്തവരുടെയോ bearer ഓതന്റിക്കേഷൻ ഉപയോഗിക്കുന്നവരുടെയോ AI യെ അത് നിയന്ത്രിക്കുന്നില്ല. Langfuse ക്രമീകരണങ്ങൾ ഐച്ഛികമായ ട്രേസിംഗ് കോൺഫിഗറേഷനാണ്.
നേറ്റീവ് ക്ലയന്റുകൾ
ഇതേ റിപ്പോസിറ്ററിയിൽ iOS, Android ക്ലയന്റുകളുമുണ്ട്, പക്ഷേ ലോക്കൽ വെബ്/സെർവർ കമാൻഡുകൾ അവ ബിൽഡ് ചെയ്യുകയോ വിതരണം ചെയ്യുകയോ ചെയ്യുന്നില്ല.
iOS പ്രോജക്റ്റ് ലോക്കൽ API, ഓതന്റിക്കേഷൻ ഹോസ്റ്റുകൾ ഇവിടെ നിന്ന് വായിക്കുന്നു:
apps/ios/Flashcards/Config/Local.xcconfig
ആവശ്യമുള്ളപ്പോൾ ഉദാഹരണ ഫയലിൽ നിന്ന് അത് സൃഷ്ടിക്കുക:
cp apps/ios/Flashcards/Config/Local.xcconfig.example apps/ios/Flashcards/Config/Local.xcconfig
അവയുടെ വേറിട്ട ബിൽഡ്, ടെസ്റ്റ് പ്രക്രിയകൾക്കായി റിപ്പോസിറ്ററിയിലെ iOS README, Android README എന്നിവ കാണുക.
പ്രൊഡക്ഷൻ AWS CDK ഉപയോഗിക്കുന്നു
പിന്തുണയുള്ള പ്രൊഡക്ഷൻ ഡിപ്ലോയ്മെന്റ് ഉൾപ്പെടുത്തിയിട്ടുള്ള AWS CDK സ്റ്റാക്കാണ്. ഇത് ഏത് ദാതാവിലും പ്രവർത്തിക്കുന്ന തരത്തിലല്ല, AWS അധിഷ്ഠിതമായാണ് നിർമ്മിച്ചിരിക്കുന്നത്. ഇതിൽ ഉൾപ്പെടുന്നവ:
- ഒരു VPC ഉം പ്രൈവറ്റ് സബ്നെറ്റുകളും
- Amazon RDS ലെ PostgreSQL 18
- Amazon Cognito പാസ്വേഡ് ഇല്ലാത്ത ഇമെയിൽ OTP
- ബാക്കെൻഡ്, ഓതന്റിക്കേഷൻ, MCP സേവനങ്ങൾക്കായി API Gateway ഉം Lambda യും
- ഒരു അസിങ്ക്രണസ് ചാറ്റ് വർക്കർ Lambda യും ഒരു Cognito കസ്റ്റം ഇമെയിൽ സെൻഡർ Lambda യും
- വെബ്, അഡ്മിൻ ആപ്പുകൾക്കായി S3 ഉം CloudFront ഉം
- ഡാറ്റാബേസ്, സെഷൻ, ഇമെയിൽ, മോണിറ്ററിംഗ്, ഐച്ഛികമായ AI ക്രെഡൻഷ്യലുകൾ എന്നിവയ്ക്കായി Secrets Manager
- CloudWatch അലാറങ്ങൾ, SNS അറിയിപ്പുകൾ, ഒരു RDS ബാക്കപ്പ് പ്ലാൻ
- ഒരു GitHub Actions OIDC ഡിപ്ലോയ്മെന്റ് റോൾ
- പൊതു ഡൊമെയ്നുകൾക്കായി Cloudflare സജ്ജീകരണ സ്ക്രിപ്റ്റുകൾ
ഡിപ്ലോയ്മെന്റ് app.<domain>, admin.<domain>, api.<domain>, auth.<domain>, mcp.<domain> എന്നിവ ലഭ്യമാക്കുന്നു. റൂട്ട് ഡൊമെയ്ൻ മറ്റൊന്നിനും ഉപയോഗിക്കുന്നില്ലെങ്കിൽ, അതിന് ഒരു അപെക്സ് റീഡയറക്ടും സൃഷ്ടിക്കാം.
ഇവയുള്ള ഒരു ഓപ്പറേറ്റർ മെഷീനിൽ നിന്ന് പ്രൊഡക്ഷൻ ഹെൽപ്പർ പ്രവർത്തിപ്പിക്കുക:
- Node.js 24 ഉം npm ഉം
- Bash ഉം GNU Make ഉം
- പ്രവർത്തിക്കുന്ന Docker
- ഡിപ്ലോയ്മെന്റ് അക്കൗണ്ടിലേക്ക് ഓതന്റിക്കേറ്റ് ചെയ്ത AWS CLI
- ലക്ഷ്യ റിപ്പോസിറ്ററിയിലേക്ക് ഓതന്റിക്കേറ്റ് ചെയ്ത GitHub CLI
curl,jq, Python 3
ഡിപ്ലോയ് ചെയ്യുന്നതിന് മുമ്പ്, റൂട്ടിലെ .env ൽ ഓപ്പറേറ്റർ മൂല്യങ്ങൾ കോൺഫിഗർ ചെയ്യുക. ആവശ്യമായവയിൽ AWS റീജിയൻ, ഡൊമെയ്ൻ, അലേർട്ട് ഇമെയിൽ, GitHub റിപ്പോസിറ്ററി, Cloudflare ക്രെഡൻഷ്യലുകൾ, Resend ക്രെഡൻഷ്യലുകൾ, ബാക്കെൻഡ് Sentry കോൺഫിഗറേഷൻ എന്നിവ ഉൾപ്പെടുന്നു. OpenAI, Langfuse ക്രെഡൻഷ്യലുകൾ ഐച്ഛികമാണ്.
റിപ്പോസിറ്ററിയുടെ റൂട്ടിൽ നിന്നുള്ള, ശുപാർശ ചെയ്യുന്ന ആദ്യ ഡിപ്ലോയ്മെന്റ് കമാൻഡ്:
npm ci --prefix apps/auth
bash scripts/deploy/first-deploy.sh \
--region eu-central-1 \
--domain example.com \
--alert-email alerts@example.com
ഡിപ്ലോയ്മെന്റ് ഹെൽപ്പർ ഓതന്റിക്കേഷൻ പാക്കേജ് ബണ്ടിൽ ചെയ്യുന്നുണ്ടെങ്കിലും അത് ഇൻസ്റ്റാൾ ചെയ്യാത്തതിനാൽ, ഒരു ക്ലീൻ ചെക്ക്ഔട്ടിൽ നിന്ന് ഓതന്റിക്കേഷൻ പാക്കേജ് വ്യക്തമായി ഇൻസ്റ്റാൾ ചെയ്യേണ്ടത് നിലവിൽ ആവശ്യമാണ്. ഹെൽപ്പർ യഥാർത്ഥ AWS, Cloudflare, GitHub റിസോഴ്സുകൾ സൃഷ്ടിക്കുകയോ മാറ്റുകയോ ചെയ്യുന്നു. ഇത് പ്രവർത്തിപ്പിക്കുന്നതിന് മുമ്പ് റിപ്പോസിറ്ററിയിലെ ഡിപ്ലോയ്മെന്റ് രേഖകളും ക്ലൗഡ് ചെലവുകളും പരിശോധിക്കുക. ഇത് CDK ബൂട്ട്സ്ട്രാപ്പ് ചെയ്യുന്നു, ഇൻഫ്രാസ്ട്രക്ചർ ഡിപ്ലോയ് ചെയ്യുന്നു, മൈഗ്രേഷനുകൾ പ്രവർത്തിപ്പിക്കുന്നു, വെബ്, അഡ്മിൻ അസറ്റുകൾ അപ്ലോഡ് ചെയ്യുന്നു, ഒഴിവാക്കിയിട്ടില്ലെങ്കിൽ പൊതു app, admin, api, auth, mcp DNS റെക്കോർഡുകൾ കോൺഫിഗർ ചെയ്യുന്നു, ഇല്ലാത്ത GitHub Actions കോൺഫിഗറേഷൻ പൂരിപ്പിക്കുന്നു.
ഡിപ്ലോയ്മെന്റിന് ശേഷം:
-
ALERT_EMAILഇൻബോക്സിലേക്ക് അയച്ച SNS സബ്സ്ക്രിപ്ഷൻ സ്ഥിരീകരിക്കുക. -
വേറിട്ട Resend സെൻഡിംഗ് ഡൊമെയ്ൻ DNS റെക്കോർഡുകൾ കോൺഫിഗർ ചെയ്ത് പരിശോധിച്ചുറപ്പിക്കുക:
bash scripts/setup/setup-resend-domain.sh \ --domain example.com \ --subdomain mail
first-deploy.sh ഡിഫോൾട്ടായി പൊതു ആപ്ലിക്കേഷൻ ഡൊമെയ്നുകൾക്കായി scripts/cloudflare/setup-dns.sh പ്രവർത്തിപ്പിക്കുന്നു. അത് setup-resend-domain.sh പ്രവർത്തിപ്പിക്കുന്നില്ല; രണ്ടാമത്തേത് mail.<domain> നുള്ള ഇമെയിൽ സെൻഡർ റെക്കോർഡുകൾ സൃഷ്ടിക്കുകയും ആ ഡൊമെയ്ൻ Resend ൽ പരിശോധിച്ചുറപ്പിക്കുകയും ചെയ്യുന്നു. --skip-dns ഉപയോഗിച്ചാണ് ഡിപ്ലോയ് ചെയ്യുന്നതെങ്കിൽ, AWS CDK വഴികാട്ടിയിൽ വിവരിച്ചിരിക്കുന്നതുപോലെ പൊതു റെക്കോർഡുകൾ വേറിട്ട് കോൺഫിഗർ ചെയ്യുക.
ഡാറ്റാ പോർട്ടബിലിറ്റി
വർക്ക്സ്പേസ് പാക്കേജ് ഇംപോർട്ടും എക്സ്പോർട്ടും കാർഡുകൾ, അവയുടെ ടാഗുകൾ, ബന്ധപ്പെട്ട മീഡിയ എന്നിവ മാത്രമേ കൈമാറുന്നുള്ളൂ. ആവർത്തന ചരിത്രം, FSRS ഷെഡ്യൂളർ നില, വർക്ക്സ്പേസ് ക്രമീകരണങ്ങൾ, പൂർണ്ണ ഡെക്ക് ഘടനകൾ, അക്കൗണ്ട് ഡാറ്റ എന്നിവ അത് കൈമാറുന്നില്ല.
പാക്കേജുകളെ ഉള്ളടക്ക കൈമാറ്റമായി മാത്രം കാണുക; ഹോസ്റ്റ് ചെയ്തതിൽ നിന്ന് സ്വന്തമായി ഹോസ്റ്റ് ചെയ്തതിലേക്കുള്ള പൂർണ്ണ മൈഗ്രേഷനായോ ദുരന്ത വീണ്ടെടുക്കലിനുള്ള ബാക്കപ്പായോ അല്ല. ഡിപ്ലോയ് ചെയ്ത PostgreSQL ഡാറ്റാബേസും മീഡിയ സ്റ്റോറേജും ബാക്കപ്പ് ചെയ്യുന്നതിന്റെയും പുനഃസ്ഥാപിക്കുന്നതിന്റെയും ഉത്തരവാദിത്തം ഓപ്പറേറ്റർമാർക്കാണ്.
ഓപ്പറേറ്ററുടെ ഉത്തരവാദിത്തങ്ങൾ
സ്വന്തം ഹോസ്റ്റിംഗ് എന്നാൽ ഇവ നിങ്ങൾ നൽകുകയും പരിപാലിക്കുകയും ചെയ്യുന്നു എന്നാണ്:
- AWS ഇൻഫ്രാസ്ട്രക്ചറും അതിന്റെ ചെലവുകളും
- Cloudflare DNS ഉം ഡൊമെയ്ൻ കോൺഫിഗറേഷനും
- Resend ഇമെയിൽ ഡെലിവറി ക്രെഡൻഷ്യലുകളും ഡൊമെയ്ൻ റെക്കോർഡുകളും
- ആവശ്യമായ Sentry മോണിറ്ററിംഗ് കോൺഫിഗറേഷൻ
- ഐച്ഛികമായ AI ദാതാവിന്റെയും Langfuse ന്റെയും ക്രെഡൻഷ്യലുകൾ
- സീക്രട്ടുകൾ, അപ്ഗ്രേഡുകൾ, മൈഗ്രേഷനുകൾ, അലേർട്ടുകൾ, ബാക്കപ്പുകൾ, പുനഃസ്ഥാപന പരിശോധന
- സ്വന്തം iOS അല്ലെങ്കിൽ Android റിലീസുകൾ വേണമെങ്കിൽ നേറ്റീവ് മൊബൈൽ ബിൽഡുകളും വിതരണവും
ഈ സിസ്റ്റങ്ങളിൽ പലതിനുമുള്ള ഓട്ടോമേഷൻ സ്റ്റാക്കിൽ ഉൾപ്പെടുന്നു, പക്ഷേ അതിന് ഇപ്പോഴും ഒരു ഓപ്പറേറ്റർ ആവശ്യമാണ്. Docker Compose ഈ പ്രൊഡക്ഷൻ ആർക്കിടെക്ചറിന് പകരമാകുന്നില്ല.