gravl/backend/README.md

Gravl Backend

Node.js / Express API server for the Gravl application.

Development

Prerequisites

• Node.js 18+
• PostgreSQL 14+ (or use Docker Compose)
• Docker & Docker Compose (for containerized development)

Getting Started

# Install dependencies
npm install

# Create .env file (copy from .env.example)
cp .env.example .env

# Run database migrations
npm run migrate

# Start development server
npm run dev

The API will be available at http://localhost:3001.

Health Check Endpoint

The API exposes a health check endpoint for deployment verification:

curl http://localhost:3001/api/health

Expected response:

{
  "status": "ok",
  "timestamp": "2026-03-03T18:30:00Z"
}

This endpoint is used by the deployment scripts to verify the backend is healthy after deployment.

---

Deployment

Quick Start

See /docs/DEPLOYMENT.md for comprehensive deployment documentation.

# Deploy the application
scripts/deploy.sh

# Check deployment status
scripts/build-check.sh

How It Works

1. Automatic build: scripts/deploy.sh builds fresh Docker images
2. Zero downtime: Old containers are replaced with --force-recreate
3. Health verification: API health endpoint is polled before deployment completes
4. Rollback: Use git to revert and redeploy if issues arise

Prerequisites for Deployment

• Docker and Docker Compose installed
• Git remote configured and accessible
• Backend listening on port 3001
• Health endpoint (/api/health) responding with 200 OK

Example Deployment Workflow

# 1. Make code changes and commit
git add . && git commit -m "feat: new API endpoint"

# 2. Deploy from project root
cd /workspace/gravl
scripts/deploy.sh

# 3. Verify deployment
scripts/build-check.sh

# 4. Check logs if needed
docker compose logs gravl-backend

Container Labels

All deployed containers include build metadata labels for tracking:

• org.opencontainers.image.revision — Git commit SHA
• org.opencontainers.image.created — Build timestamp

These are used by scripts/build-check.sh to detect stale deployments.

---

Testing

# Run unit tests
npm test

# Run integration tests
npm run test:integration

# Run with coverage
npm run test:coverage

---

Database

Migrations

# Run pending migrations
npm run migrate

# Rollback last migration
npm run migrate:rollback

# Create new migration
npm run migrate:create -- my_migration_name

Connection

Configure via .env:

DATABASE_URL=postgresql://user:password@localhost:5432/gravl

---

Environment Variables

See .env.example for all available variables.

Key variables:

• NODE_ENV — Development/production mode
• PORT — Server port (default: 3001)
• DATABASE_URL — PostgreSQL connection string
• JWT_SECRET — Token signing secret

---

Project Structure

backend/
├── src/
│   ├── api/          # Express route handlers
│   ├── middleware/   # Express middleware
│   ├── models/       # Database models
│   ├── services/     # Business logic
│   └── index.js      # App entry point
├── tests/            # Unit and integration tests
├── migrations/       # Database migrations
├── docker/           # Dockerfile
├── .env.example      # Environment template
└── README.md         # This file

---

Troubleshooting

API Won't Start

Check the logs:

docker compose logs gravl-backend

Common issues:

• Port 3001 already in use: Kill the process or change the port
• Database connection failed: Verify .env DATABASE_URL
• Node modules missing: Run npm install

Health Check Fails

Ensure the /api/health endpoint is implemented:

// backend/src/api/health.js
app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

Database Issues

Check Docker container status:

docker compose ps
docker compose logs gravl-db

---

Contributing

See CODING-CONVENTIONS.md in the project root for code style and standards.

---

Last Updated: 2026-03-03
Phase: 07-03
Related: /docs/DEPLOYMENT.md