Microservice Starter

Production-ready full-stack microservice template with Docker, Kubernetes, and CI/CD baked in.

Overview

A hybrid DevOps + full-stack reference architecture demonstrating how to ship a real service from local dev to Kubernetes.

Layer	Stack
API	FastAPI (Python 3.12)
Frontend	Next.js 15 (TypeScript)
Database	PostgreSQL 16
Cache	Redis 7
Containers	Docker multi-stage builds
Orchestration	Kubernetes manifests + Helm chart
CI/CD	GitHub Actions (lint, test, build, push)

Architecture

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│   Next.js   │────▶│   FastAPI   │────▶│  PostgreSQL  │
│  (port 3000)│     │  (port 8000)│     │  (port 5432) │
└─────────────┘     └──────┬──────┘     └──────────────┘
                           │
                    ┌──────▼──────┐
                    │    Redis    │
                    │ (port 6379) │
                    └─────────────┘

Quick Start

Prerequisites

• Docker & Docker Compose
• Node.js 20+
• Python 3.12+

Local Development

# Start infrastructure
docker compose up -d postgres redis

# API
cd api && pip install -r requirements.txt && uvicorn app.main:app --reload

# Frontend
cd web && npm install && npm run dev

Open http://localhost:3000 — API docs at http://localhost:8000/docs

Full Stack with Docker

docker compose up --build

Deploy to Kubernetes

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/
# Or use Helm
helm install microservice ./helm/microservice-starter

API Endpoints

Method	Path	Description
GET	/health	Liveness probe
GET	/ready	Readiness probe (checks DB + Redis)
GET	/api/v1/items	List items
POST	/api/v1/items	Create item

Project Structure

microservice-starter/
├── api/                 # FastAPI backend
├── web/                 # Next.js frontend
├── k8s/                 # Kubernetes manifests
├── helm/                # Helm chart
├── .github/workflows/   # CI/CD pipelines
├── docker-compose.yml
└── README.md

CI/CD Pipeline

1. Lint — Ruff (Python), ESLint (TypeScript)
2. Test — pytest, Vitest
3. Build — Docker images with layer caching
4. Scan — Trivy vulnerability scan
5. Deploy — Optional K8s rollout (on tag)

Environment Variables

Variable	Default	Description
DATABASE_URL	postgresql://app:app@localhost:5432/app	Postgres connection
REDIS_URL	redis://localhost:6379/0	Redis connection
API_URL	http://localhost:8000	Backend URL (frontend)

License

MIT © almightymoon