219 lines
4.2 KiB
Markdown
219 lines
4.2 KiB
Markdown
# 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`
|