docs(07-03): Deployment testing plan and documentation

backend/README.md

@@ -0,0 +1,218 @@
+# 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
+
+```bash
+# 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:
+
+```bash
+curl http://localhost:3001/api/health
+```
+
+Expected response:
+```json
+{
+  "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.
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Run unit tests
+npm test
+
+# Run integration tests
+npm run test:integration
+
+# Run with coverage
+npm run test:coverage
+```
+
+---
+
+## Database
+
+### Migrations
+
+```bash
+# 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:
+```bash
+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:
+
+```javascript
+// 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:
+```bash
+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`