141 lines
3.4 KiB
Markdown
141 lines
3.4 KiB
Markdown
# Xtablo API
|
|
|
|
This is the backend API for Xtablo, built with [Hono](https://hono.dev/) and TypeScript.
|
|
|
|
## Development
|
|
|
|
This package is part of the Xtablo monorepo managed with Turborepo and pnpm workspaces.
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js >= 20.0.0
|
|
- pnpm 10.x
|
|
|
|
### Available Commands
|
|
|
|
From the root of the monorepo:
|
|
|
|
```bash
|
|
# Start development server
|
|
pnpm run dev:api
|
|
|
|
# Build the API
|
|
turbo run build --filter=@xtablo/api
|
|
|
|
# Run tests
|
|
pnpm run test:api
|
|
|
|
# Type checking
|
|
turbo run typecheck --filter=@xtablo/api
|
|
|
|
# Linting
|
|
turbo run lint --filter=@xtablo/api
|
|
turbo run lint:fix --filter=@xtablo/api
|
|
|
|
# Format code
|
|
turbo run format --filter=@xtablo/api
|
|
```
|
|
|
|
From within the `apps/api` directory:
|
|
|
|
```bash
|
|
# Start development server
|
|
pnpm dev
|
|
|
|
# Build
|
|
pnpm build
|
|
|
|
# Start production server
|
|
pnpm start
|
|
|
|
# Run tests
|
|
pnpm test
|
|
pnpm test:watch
|
|
|
|
# Linting and formatting
|
|
pnpm lint
|
|
pnpm lint:fix
|
|
pnpm format
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
apps/api/
|
|
├── src/
|
|
│ ├── __tests__/ # Test files
|
|
│ ├── helpers/ # Helper functions
|
|
│ ├── middlewares/ # Hono middlewares
|
|
│ ├── routers/ # API route handlers
|
|
│ ├── types/ # TypeScript type definitions
|
|
│ ├── config.ts # Configuration
|
|
│ ├── index.ts # Entry point
|
|
│ └── secrets.ts # Secret management
|
|
├── dist/ # Compiled output
|
|
├── docs/ # API documentation
|
|
├── examples/ # Usage examples
|
|
├── Dockerfile # Docker configuration
|
|
├── cloudbuild.yaml # Google Cloud Build config
|
|
├── package.json
|
|
├── tsconfig.json
|
|
└── turbo.json # Turborepo config
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
See `.env.example` for required environment variables.
|
|
|
|
## Deployment
|
|
|
|
The API is deployed to Google Cloud Run. See `cloudbuild.yaml` for deployment configuration.
|
|
|
|
## Dokploy Deployment
|
|
|
|
Prefer a Dokploy `Application` instead of a Compose service.
|
|
|
|
Dokploy supports Dockerfile-based applications directly, which fits this API better than maintaining a dedicated compose wrapper. Configure the application like this:
|
|
|
|
- Build Type: `Dockerfile`
|
|
- Dockerfile Path: `apps/api/Dockerfile`
|
|
- Docker Context Path: `.`
|
|
- Docker Build Stage: `final`
|
|
- Port: `8080`
|
|
- Run Command: leave empty and use the image `CMD`
|
|
|
|
Set these Dokploy environment variables:
|
|
|
|
- `NODE_ENV`
|
|
- `DD_SERVICE=xtablo-api`
|
|
- `DD_ENV`
|
|
- `DD_VERSION`
|
|
- `DD_LOGS_INJECTION=true`
|
|
- `SUPABASE_URL`
|
|
- `SUPABASE_SERVICE_ROLE_KEY`
|
|
- `SUPABASE_CONNECTION_STRING`
|
|
- `SUPABASE_CA_CERT`
|
|
- `STRIPE_SECRET_KEY`
|
|
- `STRIPE_WEBHOOK_SECRET`
|
|
- `STRIPE_SOLO_PRICE_ID`
|
|
- `STRIPE_TEAM_PRICE_ID`
|
|
- `STRIPE_FOUNDER_PRICE_ID`
|
|
- `EMAIL_USER`
|
|
- `EMAIL_CLIENT_ID`
|
|
- `EMAIL_CLIENT_SECRET`
|
|
- `EMAIL_REFRESH_TOKEN`
|
|
- `R2_ACCOUNT_ID`
|
|
- `R2_ACCESS_KEY_ID`
|
|
- `R2_SECRET_ACCESS_KEY`
|
|
- `TASKS_SECRET`
|
|
|
|
For Datadog logs, the Dokploy host should already run a Datadog Agent with Docker log collection enabled. Then add these Docker Swarm labels in Dokploy `Advanced Settings -> Swarm Settings -> Labels`:
|
|
|
|
- `com.datadoghq.tags.service=xtablo-api`
|
|
- `com.datadoghq.tags.env=${DD_ENV}`
|
|
- `com.datadoghq.tags.version=${DD_VERSION}`
|
|
- `com.datadoghq.ad.logs=[{"source":"nodejs","service":"xtablo-api"}]`
|
|
|
|
This gives you:
|
|
|
|
- container logs in Datadog with `source: nodejs`
|
|
- service tagging as `xtablo-api`
|
|
- APM/log correlation via `dd-trace` plus `DD_LOGS_INJECTION=true`
|