254 lines
5.0 KiB
Markdown
254 lines
5.0 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
cd backend
|
||
npm install
|
||
```
|
||
|
||
### Running Locally
|
||
|
||
**Development mode (with hot reload):**
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
The server starts on `http://localhost:3001`
|
||
|
||
**Production mode:**
|
||
```bash
|
||
npm run build
|
||
npm start
|
||
```
|
||
|
||
### Environment Variables
|
||
|
||
Create a `.env` file in the backend directory:
|
||
|
||
```bash
|
||
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:**
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```bash
|
||
npm test # Run all tests
|
||
npm run test:watch # Run tests in watch mode
|
||
```
|
||
|
||
---
|
||
|
||
## Docker
|
||
|
||
### Building the Image
|
||
|
||
```bash
|
||
docker build -t gravl-backend:latest .
|
||
```
|
||
|
||
### Running in Container
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
cd /workspace/gravl
|
||
scripts/deploy.sh
|
||
```
|
||
|
||
### Checking Deployment Status
|
||
|
||
```bash
|
||
cd /workspace/gravl
|
||
scripts/build-check.sh
|
||
```
|
||
|
||
For complete deployment documentation, see: **[`docs/DEPLOYMENT.md`](../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:**
|
||
```javascript
|
||
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
|
||
```bash
|
||
npm run dev # Logs to stdout
|
||
```
|
||
|
||
### Docker Container
|
||
```bash
|
||
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:
|
||
```bash
|
||
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**
|
||
```bash
|
||
lsof -i :3001
|
||
# Kill the conflicting process or use a different port
|
||
```
|
||
|
||
2. **Backend code has a syntax error**
|
||
```bash
|
||
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`](../docs/DEPLOYMENT.md#troubleshooting)** for more deployment troubleshooting.
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
See the root project README or CONTRIBUTING.md for guidelines on:
|
||
- Code style ([CODING-CONVENTIONS.md](../docs/CODING-CONVENTIONS.md))
|
||
- Testing requirements
|
||
- Pull request process
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
[Specify your license here]
|
||
|
||
---
|
||
|
||
*Last updated: 2026-03-03*
|