Přeskočit na hlavní obsah

Development Setup

Tento dokument popisuje, jak nastavit a spustit DnA Cruises systém lokálně pro vývoj.

Požadavky​

  • Node.js 18+ (pro Workers API a frontend aplikace)
  • Node.js 20+ (pro Docusaurus docs - Docusaurus vyžaduje Node 20+)
  • npm 9+
  • Cloudflare account (pro D1 databázi, R2 storage, Workers)
  • Wrangler CLI (Cloudflare CLI tool)

Instalace​

1. Clone repository​

git clone https://github.com/DnASound/navigator.git
cd navigator

2. Install dependencies​

# Install all dependencies (monorepo root + all workspaces)
npm install

Tento příkaz nainstaluje dependencies pro:

  • Root workspace (Turbo, shared configs)
  • apps/web (Next.js web app)
  • apps/load (Next.js load app)
  • apps/docs (Docusaurus docs)
  • packages/api (Shared API types)
  • packages/db (Database schema)
  • packages/ui (Shared UI components)
  • workers/api (Cloudflare Worker API)

3. Setup Cloudflare Wrangler CLI​

# Install Wrangler globally
npm install -g wrangler

# Login to Cloudflare
wrangler login

Po přihlášení se otevře browser pro autorizaci.

Lokální vývoj​

Spuštění všech aplikací najednou​

# Z rootu projektu
npm run dev

Tento příkaz spustí:

  • Web app (apps/web) na http://localhost:3000
  • Load app (apps/load) na http://localhost:3001
  • Docs (apps/docs) na http://localhost:3002
  • API Worker (workers/api) na http://localhost:8787

Spuštění jednotlivých aplikací​

Web app:

cd apps/web
npm run dev
# Běží na http://localhost:3000

Load app:

cd apps/load
npm run dev
# Běží na http://localhost:3001

Docs:

cd apps/docs
npm run dev
# Běží na http://localhost:3002

API Worker:

cd workers/api
npm run dev
# Běží na http://localhost:8787

Environment Variables pro Frontend​

Vytvořte .env.local v apps/web/ a apps/load/:

# apps/web/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8787

# apps/load/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8787

Poznámka: NEXT_PUBLIC_* proměnné jsou dostupné v browseru. Nepoužívejte je pro secrets!

Databáze​

Vytvoření D1 databáze​

# Vytvořit development databázi
wrangler d1 create dna-cruises-dev

# Vytvořit production databázi (volitelné)
wrangler d1 create dna-cruises-prod

Po vytvoření databáze zkopírujte database_id z výstupu a přidejte ho do wrangler.toml.

Spuštění migrací​

Lokální databáze (pro development):

cd workers/api
wrangler d1 migrations apply dna-cruises-dev --local

Remote databáze (pro testování na Cloudflare):

cd workers/api
wrangler d1 migrations apply dna-cruises-dev --remote

Poznámka: Migrace se spouštějí z workers/api adresáře, protože wrangler.toml je tam.

Import inventory dat​

Pokud máte _inventura.sql soubor v rootu projektu:

cd packages/db
node scripts/migrate-inventory.js

Nebo použijte D1 SQL editor v Cloudflare Dashboard pro manuální import.

Kontrola databáze​

Lokální databáze:

cd workers/api
wrangler d1 execute dna-cruises-dev --local --command "SELECT COUNT(*) as count FROM items"

Remote databáze:

cd workers/api
wrangler d1 execute dna-cruises-dev --remote --command "SELECT COUNT(*) as count FROM items"

Environment Variables​

Workers API​

Vytvořte .dev.vars v workers/api/:

# JWT Secret - použijte secure random string
# Generování: openssl rand -hex 32
JWT_SECRET=your-secret-key-here

# Environment
ENVIRONMENT=development

# Google OAuth (volitelné pro lokální vývoj)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# DinoSMS API (volitelné pro lokální vývoj)
DINOSMS_API_KEY=your-dinosms-api-key
DINOSMS_SENDER=DnA Cruises

Generování JWT_SECRET:

openssl rand -hex 32

Poznámka: .dev.vars je v .gitignore - necommitovat secrets do gitu!

Frontend aplikace​

Vytvořte .env.local v apps/web/ a apps/load/:

# apps/web/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8787

# apps/load/.env.local
NEXT_PUBLIC_API_URL=http://localhost:8787

Poznámka: NEXT_PUBLIC_* proměnné jsou dostupné v browseru. Nepoužívejte je pro secrets!

Workers Builds (CI/CD)​

Workers jsou automaticky deployovány přes Cloudflare Workers Builds při push do GitHub.

Konfigurace​

  • Production: Automaticky deploy při push do main branch
  • Development: Automaticky deploy při push do dev branch
  • Root directory: workers/api
  • Deploy commands:
    • Production: npx wrangler deploy --env production
    • Development: npx wrangler deploy --env development

Bindings​

Bindings (D1, R2, environment variables) se automaticky přenášejí z wrangler.toml při každém deployi.

Důležité:

  • Deploy command MUSÍ obsahovat --env <environment> flag
  • Bindings se přenášejí z [env.production] nebo [env.development] sekcí v wrangler.toml
  • Bindings se nemusí zobrazovat v Dashboardu, ale jsou aktivní a funkční
  • V build logu uvidíš potvrzení všech bindings při deployi

Ověření deploymentu​

Po push do main nebo dev branch:

  1. Zkontroluj build status v Cloudflare Dashboard → Workers & Pages → [Worker name] → Builds
  2. V build logu uvidíš seznam všech bindings
  3. Worker je dostupný na: https://[worker-name].dnasound.workers.dev

Troubleshooting​

Workers API neběží lokálně​

Problém: wrangler dev selhává nebo databáze není dostupná

Řešení:

  1. Zkontroluj, že jsi v workers/api adresáři
  2. Zkontroluj, že .dev.vars existuje a obsahuje všechny potřebné proměnné
  3. Zkontroluj, že D1 databáze existuje: wrangler d1 list
  4. Zkontroluj wrangler.toml - database_id musí být správný

Frontend se nemůže připojit k API​

Problém: NEXT_PUBLIC_API_URL není nastaven nebo API neběží

Řešení:

  1. Zkontroluj, že API Worker běží na http://localhost:8787
  2. Zkontroluj, že .env.local existuje v apps/web/ nebo apps/load/
  3. Restartuj Next.js dev server po změně .env.local

Docusaurus neběží​

Problém: Docusaurus vyžaduje Node.js 20+

Řešení:

# Použij nvm pro přepnutí Node verze
nvm use 20

# Nebo použij Node 20 přímo
node --version  # mělo by být v20.x.x

Migrace selhávají​

Problém: wrangler d1 migrations apply selhává

Řešení:

  1. Zkontroluj, že jsi v workers/api adresáři
  2. Zkontroluj, že databáze existuje: wrangler d1 list
  3. Zkontroluj, že database_id v wrangler.toml je správný
  4. Pro lokální migrace použij --local flag
  5. Pro remote migrace použij --remote flag

Porty jsou obsazené​

Problém: Port 3000, 3001, 3002 nebo 8787 je už používán

Řešení:

  1. Najdi proces používající port: lsof -i :3000 (macOS/Linux)
  2. Ukonči proces nebo změň port v package.json nebo next.config.js
  3. Pro Next.js: PORT=3003 npm run dev
  4. Pro Wrangler: změň port v wrangler.toml nebo použij --port flag

TypeScript chyby​

Problém: TypeScript hlásí chyby po změnách

Řešení:

# Z rootu projektu
npm run type-check

# Nebo v konkrétním workspace
cd apps/web && npm run type-check

Dependencies nejsou nainstalované​

Problém: Module not found chyby

Řešení:

# Z rootu projektu
npm install

# Pokud to nepomůže, smaž node_modules a znovu nainstaluj
rm -rf node_modules apps/*/node_modules packages/*/node_modules workers/*/node_modules
npm install