chore(07-03): Stage deployment scripts and documentation updates
This commit is contained in:
+180
-145
@@ -1,155 +1,167 @@
|
||||
# Gravl Backend
|
||||
|
||||
Node.js / Express API server for the Gravl application.
|
||||
Backend service for the Gravl exercise and fitness tracking platform.
|
||||
|
||||
## Development
|
||||
## Overview
|
||||
|
||||
### 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.
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
## Local Development
|
||||
|
||||
### Quick Start
|
||||
### Prerequisites
|
||||
|
||||
See `/docs/DEPLOYMENT.md` for comprehensive deployment documentation.
|
||||
- Node.js 18+
|
||||
- npm or yarn
|
||||
- Docker & Docker Compose (for local container development)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Deploy the application
|
||||
scripts/deploy.sh
|
||||
|
||||
# Check deployment status
|
||||
scripts/build-check.sh
|
||||
cd backend
|
||||
npm install
|
||||
```
|
||||
|
||||
### How It Works
|
||||
### Running Locally
|
||||
|
||||
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
|
||||
**Development mode (with hot reload):**
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Prerequisites for Deployment
|
||||
The server starts on `http://localhost:3001`
|
||||
|
||||
- Docker and Docker Compose installed
|
||||
- Git remote configured and accessible
|
||||
- Backend listening on port 3001
|
||||
- Health endpoint (`/api/health`) responding with 200 OK
|
||||
**Production mode:**
|
||||
```bash
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
### Example Deployment Workflow
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file in the backend directory:
|
||||
|
||||
```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
|
||||
NODE_ENV=development
|
||||
PORT=3001
|
||||
DATABASE_URL=postgresql://user:password@localhost:5432/gravl
|
||||
```
|
||||
|
||||
### Container Labels
|
||||
See `.env.example` (if available) for all supported variables.
|
||||
|
||||
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.
|
||||
## 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
|
||||
# Run unit tests
|
||||
npm test
|
||||
|
||||
# Run integration tests
|
||||
npm run test:integration
|
||||
|
||||
# Run with coverage
|
||||
npm run test:coverage
|
||||
npm test # Run all tests
|
||||
npm run test:watch # Run tests in watch mode
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database
|
||||
## Docker
|
||||
|
||||
### Migrations
|
||||
### Building the Image
|
||||
|
||||
```bash
|
||||
# Run pending migrations
|
||||
npm run migrate
|
||||
|
||||
# Rollback last migration
|
||||
npm run migrate:rollback
|
||||
|
||||
# Create new migration
|
||||
npm run migrate:create -- my_migration_name
|
||||
docker build -t gravl-backend:latest .
|
||||
```
|
||||
|
||||
### Connection
|
||||
### Running in Container
|
||||
|
||||
Configure via `.env`:
|
||||
```
|
||||
DATABASE_URL=postgresql://user:password@localhost:5432/gravl
|
||||
```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.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
## Deployment
|
||||
|
||||
See `.env.example` for all available variables.
|
||||
### Automated Deployment
|
||||
|
||||
Key variables:
|
||||
- `NODE_ENV` — Development/production mode
|
||||
- `PORT` — Server port (default: 3001)
|
||||
- `DATABASE_URL` — PostgreSQL connection string
|
||||
- `JWT_SECRET` — Token signing secret
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
@@ -158,61 +170,84 @@ Key variables:
|
||||
```
|
||||
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
|
||||
│ ├── 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
|
||||
|
||||
### API Won't Start
|
||||
### Health Check Endpoint Not Responding
|
||||
|
||||
Check the logs:
|
||||
```bash
|
||||
docker compose logs gravl-backend
|
||||
```
|
||||
**Symptom:** Deployment fails with "Health check failed after 60s"
|
||||
|
||||
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`
|
||||
**Causes & Fixes:**
|
||||
1. **Port 3001 is already in use**
|
||||
```bash
|
||||
lsof -i :3001
|
||||
# Kill the conflicting process or use a different port
|
||||
```
|
||||
|
||||
### Health Check Fails
|
||||
2. **Backend code has a syntax error**
|
||||
```bash
|
||||
npm run dev # Look for error messages
|
||||
```
|
||||
|
||||
Ensure the `/api/health` endpoint is implemented:
|
||||
3. **Health check endpoint is not implemented**
|
||||
- Ensure `app.get('/api/health', ...)` is in src/index.js
|
||||
|
||||
```javascript
|
||||
// backend/src/api/health.js
|
||||
app.get('/api/health', (req, res) => {
|
||||
res.json({ status: 'ok', timestamp: new Date().toISOString() });
|
||||
});
|
||||
```
|
||||
4. **Database connection is failing**
|
||||
- Backend might be stuck trying to connect to DB
|
||||
- Check `DATABASE_URL` in `.env`
|
||||
- Ensure database is running
|
||||
|
||||
### Database Issues
|
||||
|
||||
Check Docker container status:
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs gravl-db
|
||||
```
|
||||
See **[`docs/DEPLOYMENT.md`](../docs/DEPLOYMENT.md#troubleshooting)** for more deployment troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
See `CODING-CONVENTIONS.md` in the project root for code style and standards.
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-03-03
|
||||
**Phase:** 07-03
|
||||
**Related:** `/docs/DEPLOYMENT.md`
|
||||
## License
|
||||
|
||||
[Specify your license here]
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-03-03*
|
||||
|
||||
Reference in New Issue
Block a user