gravl/backend

Gravl Backend

Backend service for the Gravl exercise and fitness tracking platform.

Overview

The Gravl backend is a Node.js/Express application that provides:

• REST API for exercise data management
• User authentication and authorization
• Integration with frontend via HTTP
• Health check endpoint for deployment monitoring

---

Local Development

Prerequisites

• Node.js 18+
• npm or yarn
• Docker & Docker Compose (for local container development)

Installation

cd backend
npm install

Running Locally

Development mode (with hot reload):

npm run dev

The server starts on http://localhost:3001

Production mode:

npm run build
npm start

Environment Variables

Create a .env file in the backend directory:

NODE_ENV=development
PORT=3001
DATABASE_URL=postgresql://user:password@localhost:5432/gravl

See .env.example (if available) for all supported variables.

---

API Endpoints

Health Check (Monitoring & Deployment)

GET /api/health

Used by deployment scripts to verify the backend is running and responsive.

Response:

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

Status Codes:

• 200 OK — Backend is healthy
• 500 Internal Server Error — Backend has errors (check logs)

Other Endpoints

(Document your API endpoints here; placeholder for now)

---

Testing

npm test              # Run all tests
npm run test:watch   # Run tests in watch mode

---

Docker

Building the Image

docker build -t gravl-backend:latest .

Running in Container

docker run -p 3001:3001 \
  -e NODE_ENV=production \
  -e DATABASE_URL=postgresql://... \
  gravl-backend:latest

With Docker Compose

See the root docker-compose.yml for multi-container setup.

---

Deployment

Automated Deployment

The backend is deployed using scripts in the root scripts/ directory:

• scripts/deploy.sh — Pulls latest code, builds fresh Docker image, starts container with health checks
• scripts/build-check.sh — Verifies deployed container matches local git HEAD

How to Deploy

cd /workspace/gravl
scripts/deploy.sh

Checking Deployment Status

cd /workspace/gravl
scripts/build-check.sh

For complete deployment documentation, see: docs/DEPLOYMENT.md

That guide includes:

• Prerequisites and setup
• How to run deploy.sh
• How to check build status
• Troubleshooting (health check failures, stale containers, etc.)
• Recovery procedures (rollbacks, cleanup)

Health Check Configuration

The backend exposes a health check endpoint at GET /api/health. The deployment script (scripts/deploy.sh) waits up to 60 seconds for this endpoint to return HTTP 200.

In your backend code:

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

Deployment timeout: 60 seconds (12 retries × 5 seconds)

• If this endpoint takes >5 seconds to respond, deployment will timeout
• Ensure health check is lightweight (no expensive DB queries)

---

Project Structure

backend/
├── src/
│   ├── index.js           # Server entry point
│   ├── routes/            # API endpoints
│   ├── controllers/       # Business logic
│   ├── models/            # Data models (if using ORM)
│   └── middleware/        # Express middleware
├── test/                  # Test files
├── Dockerfile             # Container image definition
├── package.json           # Dependencies
└── README.md             # This file

---

Logs

Local Development

npm run dev  # Logs to stdout

Docker Container

docker logs gravl-backend       # Current logs
docker logs -f gravl-backend    # Follow logs in real-time
docker logs --tail 50 gravl-backend  # Last 50 lines

In Deployment

All deploy activity is logged to logs/deploy.log at the root:

tail logs/deploy.log

---

Troubleshooting

Health Check Endpoint Not Responding

Symptom: Deployment fails with "Health check failed after 60s"

Causes & Fixes:

1. Port 3001 is already in use

   lsof -i :3001
   # Kill the conflicting process or use a different port
   

2. Backend code has a syntax error

   npm run dev  # Look for error messages
   

3. Health check endpoint is not implemented

   • Ensure app.get('/api/health', ...) is in src/index.js

4. Database connection is failing

   • Backend might be stuck trying to connect to DB
   • Check DATABASE_URL in .env
   • Ensure database is running

See docs/DEPLOYMENT.md for more deployment troubleshooting.

---

Contributing

See the root project README or CONTRIBUTING.md for guidelines on:

• Code style (CODING-CONVENTIONS.md)
• Testing requirements
• Pull request process

---

License

[Specify your license here]

---

Last updated: 2026-03-03