https://github.com/jannikhst/backend_template
TypeScript Express backend template with auth, sessions, API keys, RBAC, auto-generated OpenAPI docs, Prisma, Redis. Production-ready & dockerized.
https://github.com/jannikhst/backend_template
express openapi postgres prisma redis typescript zod
Last synced: 6 months ago
JSON representation
TypeScript Express backend template with auth, sessions, API keys, RBAC, auto-generated OpenAPI docs, Prisma, Redis. Production-ready & dockerized.
- Host: GitHub
- URL: https://github.com/jannikhst/backend_template
- Owner: jannikhst
- Created: 2025-10-07T10:57:44.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-10-07T11:41:57.000Z (6 months ago)
- Last Synced: 2025-10-07T13:30:16.097Z (6 months ago)
- Topics: express, openapi, postgres, prisma, redis, typescript, zod
- Language: TypeScript
- Homepage:
- Size: 138 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Backend Starter Template
A production-ready Express.js backend template with comprehensive authentication, session management, API keys, and auto-generated OpenAPI documentation. Built with TypeScript, Prisma, and Redis for scalable, type-safe backend development.
## Overview
This template provides a solid foundation for building backends that require user authentication and session management. It includes everything needed to quickly bootstrap a secure, well-documented API with minimal configuration.
## Key Features
### Authentication & Session Management
- **Multiple Authentication Methods**: Email/Password and OAuth (Google, Slack, GitHub)
- **Redis-Based Sessions**: Scalable session storage with sliding expiration
- **Multi-Session Support**: Users can maintain multiple active sessions across devices
- **Session Management**: List, view, and revoke individual or all sessions
### API Key Management
- **Server-to-Server Authentication**: Generate and manage API keys for programmatic access
- **Key Lifecycle**: Create, list, and revoke API keys with optional expiration dates
- **Usage Tracking**: Monitor last usage timestamps for each key
### User & Role Management
- **Role-Based Access Control (RBAC)**: Built-in support for ADMIN, USER, and GUEST roles
- **User Administration**: Admin endpoints for managing users, roles, and account status
- **Flexible Permissions**: Easily extend with custom roles and permissions
### Logging & Monitoring
- **Structured Logging**: JSON-formatted logs with contextual information
- **Request Tracing**: Unique trace IDs for correlating requests across services
- **Log Management**: Query, filter, and analyze logs via API endpoints
- **Database-Backed**: Persistent log storage in PostgreSQL
### Auto-Generated Documentation
- **OpenAPI 3.1 Specification**: Automatically generated from Zod schemas
- **Interactive UI**: ReDoc interface for exploring and testing endpoints
- **Always Up-to-Date**: Documentation reflects actual API implementation
- **Type-Safe**: Full TypeScript integration ensures schema accuracy
### Security
- **Rate Limiting**: Configurable rate limits per endpoint
- **Cloudflare Integration**: Extract real client IPs when behind Cloudflare
- **Security Headers**: Helmet.js for HTTP security headers
- **CORS Configuration**: Flexible cross-origin resource sharing setup
- **HPP Protection**: HTTP Parameter Pollution prevention
### Type Safety & Validation
- **Full TypeScript**: End-to-end type safety
- **Zod Schemas**: Runtime validation with compile-time type inference
- **Prisma ORM**: Type-safe database queries
- **Input/Output Validation**: Automatic request/response validation
### AI-Ready Development
- **Cline Rules**: Pre-configured `.clinerules/` directory with development guidelines
- **Structured Documentation**: Module structure, OpenAPI patterns, and HTTP handler best practices
- **Consistent Patterns**: Standardized code organization for AI-assisted development
## Technology Stack
- **Runtime**: Node.js 20
- **Framework**: Express.js 5
- **Language**: TypeScript 5
- **Database**: PostgreSQL with Prisma ORM
- **Session Store**: Redis
- **Validation**: Zod
- **Documentation**: OpenAPI 3.1 + ReDoc
- **Authentication**: Arctic (OAuth), bcrypt (passwords)
- **Containerization**: Docker + Docker Compose
## Quick Start
### Prerequisites
- Docker and Docker Compose
- Node.js 20+ (for local development)
### Installation
1. Clone the repository:
```bash
git clone
cd backend_template
```
2. Copy environment configuration:
```bash
cp .env.example .env
```
3. Configure environment variables in `.env`:
- Set `DATABASE_URL` for PostgreSQL connection
- Set `REDIS_URL` for Redis connection
- Configure OAuth providers (optional)
- Adjust session and cookie settings
4. Start services with Docker Compose:
```bash
docker compose up -d
```
5. Run database migrations:
```bash
docker compose exec app npx prisma migrate deploy
```
6. Access the API:
- API: `http://localhost:3000`
- Documentation: `http://localhost:3000/v1/docs`
## Development
### Local Development
```bash
# Install dependencies
npm install
# Generate Prisma client
npm run db:generate
# Run database migrations
npm run db:migrate
# Start development server
npm run dev
```
### Database Management
```bash
# Create a new migration
npm run db:migrate
# Open Prisma Studio
npm run db:studio
# Push schema changes (development only)
npm run db:push
```
### Code Quality
```bash
# Run linter
npm run lint
# Fix linting issues
npm run lint:fix
# Type checking
npm run typecheck
```
## Project Structure
```
├── src/
│ ├── core/ # Core functionality
│ │ ├── config/ # Configuration management
│ │ ├── db/ # Database client and logging
│ │ ├── http/ # HTTP middleware
│ │ ├── logging/ # Logging infrastructure
│ │ ├── openapi/ # OpenAPI generation
│ │ ├── services/ # Core services
│ │ └── types/ # TypeScript types
│ ├── modules/ # Feature modules
│ │ ├── auth/ # Authentication endpoints
│ │ ├── api-keys/ # API key management
│ │ ├── admin/ # Admin endpoints
│ │ ├── logs/ # Log management
│ │ └── docs/ # Documentation generation
│ └── index.ts # Application entry point
├── prisma/
│ ├── schema.prisma # Database schema
│ └── migrate/ # Migration utilities
├── docs/ # API documentation
├── Dockerfile # Container definition
└── compose.yml # Docker Compose configuration
```
## Deployment
### Automated CI/CD
This template includes automated build and deployment via GitHub Actions:
- **Automatic Versioning**: Semantic versioning with auto-incrementing patch versions
- **Docker Builds**: Multi-stage builds pushed to GitHub Container Registry
- **Build Metadata**: Version, commit hash, and build time injected at build time
- **Multi-Platform**: Supports linux/amd64 architecture
See [`.github/VERSIONING.md`](.github/VERSIONING.md) for detailed versioning documentation.
#### GitHub Actions Workflow
On push to `main` branch:
1. Automatically generates next version (e.g., `1.0.0` → `1.0.1`)
2. Creates and pushes Git tag (`backend-template-v1.0.1`)
3. Builds Docker image with version metadata
4. Pushes to GitHub Container Registry with multiple tags
#### Using Pre-Built Images
Pull and run the latest production image:
```bash
# Pull latest image
docker pull ghcr.io/YOUR_USERNAME/backend_template:latest
# Run with production compose file
docker compose -f compose.yml -f compose.prod.yml up -d
```
Update `compose.prod.yml` with your GitHub username before deploying.
### Manual Docker Deployment
For manual builds without CI/CD:
1. Build the image:
```bash
docker build -t backend-template \
--build-arg BUILD_VERSION=1.0.0 \
--build-arg BUILD_COMMIT=$(git rev-parse HEAD) \
--build-arg BUILD_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
.
```
2. Run with Docker Compose:
```bash
docker compose up -d
```
### Behind Reverse Proxy (Traefik/Cloudflare)
When running behind a reverse proxy:
1. Set `BEHIND_CLOUDFLARE=true` in `.env` to extract real client IPs
2. Configure `COOKIE_SECURE=true` for HTTPS
3. Set `COOKIE_SAMESITE=strict` or `lax` based on your requirements
4. Update `DOMAIN` to your production domain
5. Configure `CORS_ORIGIN` to match your frontend URL
### Environment Variables
Key environment variables to configure:
- `DATABASE_URL`: PostgreSQL connection string
- `REDIS_URL`: Redis connection string
- `NODE_ENV`: `development` or `production`
- `PORT`: Server port (default: 3000)
- `SESSION_TTL_SECONDS`: Session lifetime in seconds
- `COOKIE_SECURE`: Enable secure cookies in production
- `BEHIND_CLOUDFLARE`: Extract real IPs from Cloudflare headers
- `AUTH_*_ENABLED`: Enable/disable authentication providers
- OAuth credentials for enabled providers
See `.env.example` for complete configuration options.
## API Documentation
The API automatically generates OpenAPI 3.1 documentation from Zod schemas. Access the interactive documentation at `/v1/docs` when the server is running.
### Key Endpoints
- `POST /v1/auth/register` - Register new user
- `POST /v1/auth/login` - Login with credentials
- `GET /v1/auth/sessions` - List active sessions
- `POST /v1/api-keys` - Create API key
- `GET /v1/api-keys` - List API keys
- `GET /v1/admin/users` - List users (admin only)
- `GET /v1/logs` - Query logs (admin only)
## Authentication
The template supports two authentication methods:
### 1. Session Cookies (Web Applications)
- Cookie-based authentication with HttpOnly, Secure flags
- Sliding session expiration
- Multi-device support
### 2. API Keys (Server-to-Server)
- Bearer token authentication
- Format: `Bearer {username}_{128-character-hex}`
- Passed via `Authorization` header
## Extending the Template
### Adding New Endpoints
1. Create a new module in `src/modules/`
2. Define Zod schemas in `schema.ts`
3. Implement handlers in `handlers/`
4. Register routes in `routes.ts`
5. Register with OpenAPI in `registry.ts`
### Adding Custom Roles
1. Update `UserRole` enum in `prisma/schema.prisma`
2. Run migration: `npm run db:migrate`
3. Update RBAC middleware in `src/core/http/middleware/rbac.ts`
### Adding OAuth Providers
1. Add provider configuration in `.env`
2. Implement OAuth flow in `src/modules/auth/handlers/oauth/`
3. Register routes in `src/modules/auth/routes.ts`
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.