mirror of
https://github.com/aaronpo97/the-biergarten-app.git
synced 2026-02-16 10:42:08 +00:00
Update README.md
This commit is contained in:
Aaron Po
623
README.md
623
README.md
@@ -1,115 +1,590 @@
|
|||||||
# The Biergarten App
|
# The Biergarten App
|
||||||
|
|
||||||
## Overview
|
A social platform for craft beer enthusiasts to discover breweries, share reviews, and connect with fellow beer lovers.
|
||||||
|
|
||||||
The Biergarten App is evolving from a standalone full‑stack Next.js application into a multi‑project monorepo with a dedicated .NET backend and a SQL‑first approach. Backend data access is being refactored to use stored procedures. The Next.js site remains the frontend and will consume the .NET API.
|
|
||||||
|
|
||||||
Status note (Jan 26, 2026): Migration is in progress; some parts are still being moved from the website into the .NET layers.
|
## Table of Contents
|
||||||
|
|
||||||
### Current Status
|
- [Project Status](#project-status)
|
||||||
|
- [Repository Structure](#repository-structure)
|
||||||
|
- [Technology Stack](#technology-stack)
|
||||||
|
- [Getting Started](#getting-started)
|
||||||
|
- [Prerequisites](#prerequisites)
|
||||||
|
- [Quick Start (Development Environment)](#quick-start-development-environment)
|
||||||
|
- [Manual Setup (Without Docker)](#manual-setup-without-docker)
|
||||||
|
- [Testing](#testing)
|
||||||
|
- [Database Schema](#database-schema)
|
||||||
|
- [Authentication & Security](#authentication--security)
|
||||||
|
- [Architecture Patterns](#architecture-patterns)
|
||||||
|
- [Docker & Containerization](#docker--containerization)
|
||||||
|
- [Container Architecture](#container-architecture)
|
||||||
|
- [Docker Compose Environments](#docker-compose-environments)
|
||||||
|
- [Service Dependencies](#service-dependencies)
|
||||||
|
- [Health Checks](#health-checks)
|
||||||
|
- [Volumes](#volumes)
|
||||||
|
- [Networks](#networks)
|
||||||
|
- [Environment Variables](#environment-variables)
|
||||||
|
- [Container Lifecycle](#container-lifecycle)
|
||||||
|
- [Docker Tips & Troubleshooting](#docker-tips--troubleshooting)
|
||||||
|
- [Roadmap](#roadmap)
|
||||||
|
- [License](#license)
|
||||||
|
- [Contact & Support](#contact--support)
|
||||||
|
|
||||||
- Refactor is not complete; expect mixed responsibilities and evolving APIs.
|
---
|
||||||
- The Next.js app in [Website](Website) currently runs standalone, retaining its serverless API routes, Prisma, and Neon Postgres stack as documented in [Website/README.old.md](Website/README.old.md).
|
|
||||||
- The .NET API and SQL‑first repository are under active development; endpoint parity with the legacy Next.js backend is in progress.
|
|
||||||
- Planned outcome: the Website will call the .NET API and deprecate its internal backend once parity is reached.
|
## Project Status
|
||||||
|
|
||||||
|
This project is in active development, transitioning from a full-stack Next.js application to a **multi-project monorepo** with:
|
||||||
|
- **Backend**: .NET 10 Web API with SQL Server
|
||||||
|
- **Frontend**: Next.js with TypeScript
|
||||||
|
- **Architecture**: SQL-first approach using stored procedures
|
||||||
|
|
||||||
|
**Current State** (February 2025):
|
||||||
|
- Core authentication and user management APIs functional
|
||||||
|
- Database schema and migrations established
|
||||||
|
- Repository and service layers implemented
|
||||||
|
- Frontend integration with .NET API in progress
|
||||||
|
- Migrating remaining features from Next.js serverless functions
|
||||||
|
|
||||||
|
**The Next.js app currently runs standalone with its original Prisma/Neon Postgres backend. It will be fully integrated with the .NET API once feature parity is achieved.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Repository Structure
|
## Repository Structure
|
||||||
|
|
||||||
- [API](API)
|
```
|
||||||
- [API.Core](API/API.Core): ASP.NET Core Web API with controllers and OpenAPI/Swagger enabled.
|
src/Core/
|
||||||
- [Database](Database)
|
├── API/
|
||||||
- [Database.Core](Database/Database.Core): SQL schema and logic deployment via DbUp (scripts embedded in the assembly). SQL‑first with stored procedures.
|
│ ├── API.Core/ # ASP.NET Core Web API with Swagger/OpenAPI
|
||||||
- [Database.Seed](Database/Database.Seed): Seeders for initial data (users, locations) driven by `DB_CONNECTION_STRING`.
|
│ └── API.Specs/ # Integration tests using Reqnroll (BDD)
|
||||||
- [Repository](Repository)
|
├── Database/
|
||||||
- [Repository.Core](Repository/Repository.Core): Data access layer using stored procedures. Includes `DefaultSqlConnectionFactory` that reads `DB_CONNECTION_STRING` or `ConnectionStrings:Default`.
|
│ ├── Database.Migrations/ # DbUp migrations (embedded SQL scripts)
|
||||||
- [Repository.Tests](Repository/Repository.Tests): Tests for repository functionality.
|
│ └── Database.Seed/ # Database seeding for development/testing
|
||||||
- [Service](Service)
|
├── Repository/
|
||||||
- [Service.Core](Service/Service.Core): Business/service layer consumed by the API.
|
│ ├── Repository.Core/ # Data access layer (stored procedure-based)
|
||||||
- [Website](Website): Next.js frontend. Historically included serverless API routes, Prisma, and Neon Postgres; now focuses on UI and calls the .NET backend.
|
│ └── Repository.Tests/ # Unit tests for repositories
|
||||||
- [docker-compose.yml](docker-compose.yml): Local SQL Server service for development.
|
└── Service/
|
||||||
- [LICENSE.md](LICENSE.md): Project license.
|
└── Service.Core/ # Business logic layer
|
||||||
|
|
||||||
## Tech Highlights
|
Website/ # Next.js frontend application
|
||||||
|
```
|
||||||
|
|
||||||
- Backend: ASP.NET Core Web API, SQL Server, stored procedures, DbUp for migrations and deployments.
|
### Key Components
|
||||||
- Data Access: Repository pattern over stored procedures (`Repository.Core`).
|
|
||||||
- Services: Encapsulated business logic (`Service.Core`).
|
|
||||||
- Frontend: Next.js with TailwindCSS, Headless UI, DaisyUI, Mapbox, Cloudinary integrations. See [Website/README.old.md](Website/README.old.md) for prior app details and envs.
|
|
||||||
|
|
||||||
## Local Development
|
**API Layer** (`API.Core`)
|
||||||
|
- RESTful endpoints for authentication, users, and breweries
|
||||||
|
- Controllers: `AuthController`, `UserController`
|
||||||
|
- Configured with Swagger UI for API exploration
|
||||||
|
- Health checks and structured logging
|
||||||
|
|
||||||
|
**Database Layer**
|
||||||
|
- SQL Server with stored procedures for all data operations
|
||||||
|
- DbUp for version-controlled migrations
|
||||||
|
- Comprehensive schema including users, breweries, beers, locations, and social features
|
||||||
|
- Seeders for development data (users, locations across US/Canada/Mexico)
|
||||||
|
|
||||||
|
**Repository Layer** (`Repository.Core`)
|
||||||
|
- Abstraction over SQL Server using ADO.NET
|
||||||
|
- `ISqlConnectionFactory` for connection management
|
||||||
|
- Repositories: `UserAccountRepository`, `UserCredentialRepository`
|
||||||
|
- All data access via stored procedures (no inline SQL)
|
||||||
|
|
||||||
|
**Service Layer** (`Service.Core`)
|
||||||
|
- Business logic and orchestration
|
||||||
|
- Services: `AuthService`, `UserService`, `JwtService`
|
||||||
|
- Password hashing with Argon2id
|
||||||
|
- JWT token generation
|
||||||
|
|
||||||
|
**Frontend** (`Website`)
|
||||||
|
- Next.js 14+ with TypeScript
|
||||||
|
- TailwindCSS, Headless UI, DaisyUI for UI components
|
||||||
|
- Integrations: Mapbox (maps), Cloudinary (image hosting)
|
||||||
|
- Progressive migration from serverless API routes to .NET API
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technology Stack
|
||||||
|
|
||||||
|
### Backend
|
||||||
|
- **.NET 10** - Latest C# and runtime features
|
||||||
|
- **ASP.NET Core** - Web API framework
|
||||||
|
- **SQL Server 2022** - Primary database
|
||||||
|
- **DbUp** - Database migration tool
|
||||||
|
- **Argon2id** - Password hashing
|
||||||
|
- **JWT** - Authentication tokens
|
||||||
|
|
||||||
|
### Frontend
|
||||||
|
- **Next.js 14+** - React framework
|
||||||
|
- **TypeScript** - Type safety
|
||||||
|
- **TailwindCSS** - Utility-first CSS
|
||||||
|
- **Mapbox GL** - Interactive maps
|
||||||
|
- **Cloudinary** - Image management
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- **xUnit** - Unit testing framework
|
||||||
|
- **Reqnroll** - BDD/Gherkin integration testing
|
||||||
|
- **FluentAssertions** - Assertion library
|
||||||
|
- **DbMocker** - Database mocking
|
||||||
|
|
||||||
|
### DevOps & Infrastructure
|
||||||
|
- **Docker** - Containerization for all services
|
||||||
|
- **Docker Compose** - Multi-container orchestration
|
||||||
|
- **Multi-stage builds** - Optimized image sizes
|
||||||
|
- **Health checks** - Container readiness and liveness probes
|
||||||
|
- **Separate environments** - Development, testing, and production configurations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Getting Started
|
||||||
|
|
||||||
### Prerequisites
|
### Prerequisites
|
||||||
|
|
||||||
- .NET SDK 10+ (or compatible with the solution)
|
- **.NET SDK 10+** ([Download](https://dotnet.microsoft.com/download))
|
||||||
- Node.js 18+
|
- **Node.js 18+** ([Download](https://nodejs.org/))
|
||||||
- Docker Desktop (for local SQL Server)
|
- **Docker Desktop** ([Download](https://www.docker.com/products/docker-desktop))
|
||||||
|
|
||||||
### 1) Start SQL Server
|
### Quick Start (Development Environment)
|
||||||
|
|
||||||
Create a `.env` in the repo root with at least:
|
|
||||||
|
|
||||||
|
1. **Clone the repository**
|
||||||
```bash
|
```bash
|
||||||
|
git clone <repository-url>
|
||||||
|
cd biergarten-app
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Configure environment variables**
|
||||||
|
|
||||||
|
Create a `.env` file in the project root:
|
||||||
|
```bash
|
||||||
|
# Database
|
||||||
SA_PASSWORD=YourStrong!Passw0rd
|
SA_PASSWORD=YourStrong!Passw0rd
|
||||||
|
DB_CONNECTION_STRING=Server=localhost,1433;Database=Biergarten;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;
|
||||||
|
MASTER_DB_CONNECTION_STRING=Server=localhost,1433;Database=master;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;
|
||||||
|
|
||||||
|
# JWT Authentication
|
||||||
|
JWT_SECRET=your-secret-key-here-min-32-chars
|
||||||
```
|
```
|
||||||
|
|
||||||
Start the container:
|
3. **Start the development environment**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker compose up -d sqlserver
|
docker compose -f docker-compose.dev.yaml up -d
|
||||||
```
|
```
|
||||||
|
|
||||||
### 2) Configure database connection
|
This will:
|
||||||
|
- Start SQL Server
|
||||||
|
- Run database migrations
|
||||||
|
- Seed initial data
|
||||||
|
- Start the API on http://localhost:8080
|
||||||
|
|
||||||
Most projects read `DB_CONNECTION_STRING`. On macOS/zsh:
|
4. **Access Swagger UI**
|
||||||
|
|
||||||
```bash
|
Navigate to http://localhost:8080/swagger to explore and test API endpoints.
|
||||||
export DB_CONNECTION_STRING="Server=localhost,1433;Database=biergarten;User Id=sa;Password=$SA_PASSWORD;TrustServerCertificate=True;"
|
|
||||||
```
|
|
||||||
|
|
||||||
Alternatively, add `ConnectionStrings:Default` in `API/API.Core/appsettings.json`.
|
|
||||||
|
|
||||||
### 3) Apply schema and stored procedures
|
|
||||||
|
|
||||||
Run DbUp to provision the database (scripts embedded in `Database.Core`):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
dotnet run --project Database/Database.Core
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4) Seed initial data
|
|
||||||
|
|
||||||
```bash
|
|
||||||
dotnet run --project Database/Database.Seed
|
|
||||||
```
|
|
||||||
|
|
||||||
### 5) Run the API
|
|
||||||
|
|
||||||
```bash
|
|
||||||
dotnet run --project API/API.Core
|
|
||||||
```
|
|
||||||
|
|
||||||
Swagger/OpenAPI UI is available when running (e.g., https://localhost:5001/swagger or the port shown on startup). The project also maps an OpenAPI document via `MapOpenApi()`.
|
|
||||||
|
|
||||||
### 6) Run the Website (frontend)
|
|
||||||
|
|
||||||
|
5. **Run the frontend** (optional)
|
||||||
```bash
|
```bash
|
||||||
cd Website
|
cd Website
|
||||||
npm install
|
npm install
|
||||||
npm run dev
|
npm run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
For environment variables (Cloudinary, Mapbox, Prisma/Neon, etc.), see [Website/README.old.md](Website/README.old.md).
|
For Website environment variables, see `Website/README.old.md`.
|
||||||
|
|
||||||
Note: At present, the Website runs standalone and uses its existing serverless backend (Next.js API routes + Prisma/Neon). Integration to the .NET API is planned and will replace those routes once feature parity is achieved.
|
### Manual Setup (Without Docker)
|
||||||
|
|
||||||
|
1. **Start SQL Server locally** or use a hosted instance
|
||||||
|
|
||||||
|
2. **Set environment variable**
|
||||||
|
```bash
|
||||||
|
# macOS/Linux
|
||||||
|
export DB_CONNECTION_STRING="Server=localhost,1433;Database=Biergarten;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;"
|
||||||
|
export JWT_SECRET="your-secret-key-here-min-32-chars"
|
||||||
|
|
||||||
|
# Windows PowerShell
|
||||||
|
$env:DB_CONNECTION_STRING="Server=localhost,1433;Database=Biergarten;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;"
|
||||||
|
$env:JWT_SECRET="your-secret-key-here-min-32-chars"
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Run migrations**
|
||||||
|
```bash
|
||||||
|
cd src/Core
|
||||||
|
dotnet run --project Database/Database.Migrations/Database.Migrations.csproj
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Seed the database**
|
||||||
|
```bash
|
||||||
|
dotnet run --project Database/Database.Seed/Database.Seed.csproj
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Start the API**
|
||||||
|
```bash
|
||||||
|
dotnet run --project API/API.Core/API.Core.csproj
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
### Run All Tests (Docker)
|
||||||
|
```bash
|
||||||
|
docker compose -f docker-compose.test.yaml up --abort-on-container-exit
|
||||||
|
```
|
||||||
|
|
||||||
|
This runs:
|
||||||
|
- **API.Specs** - BDD integration tests
|
||||||
|
- **Repository.Tests** - Unit tests for data access
|
||||||
|
|
||||||
|
Test results are output to `./test-results/`.
|
||||||
|
|
||||||
|
### Run Tests Locally
|
||||||
|
|
||||||
|
**Integration Tests (API.Specs)**
|
||||||
|
```bash
|
||||||
|
cd src/Core
|
||||||
|
dotnet test API/API.Specs/API.Specs.csproj
|
||||||
|
```
|
||||||
|
|
||||||
|
**Unit Tests (Repository.Tests)**
|
||||||
|
```bash
|
||||||
|
cd src/Core
|
||||||
|
dotnet test Repository/Repository.Tests/Repository.Tests.csproj
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Features
|
||||||
|
|
||||||
|
Current test coverage includes:
|
||||||
|
- User authentication (login, registration)
|
||||||
|
- JWT token generation
|
||||||
|
- Password validation
|
||||||
|
- 404 error handling
|
||||||
|
- User repository operations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
The database uses a SQL-first approach with comprehensive normalization and referential integrity.
|
||||||
|
|
||||||
|
### Key Tables
|
||||||
|
|
||||||
|
**User Management**
|
||||||
|
- `UserAccount` - User profiles
|
||||||
|
- `UserCredential` - Password hashes (Argon2id)
|
||||||
|
- `UserVerification` - Account verification status
|
||||||
|
- `UserAvatar` - Profile pictures
|
||||||
|
- `UserFollow` - Social following relationships
|
||||||
|
|
||||||
|
**Location Data**
|
||||||
|
- `Country` - ISO 3166-1 country codes
|
||||||
|
- `StateProvince` - ISO 3166-2 subdivisions
|
||||||
|
- `City` - City/municipality data
|
||||||
|
|
||||||
|
**Content**
|
||||||
|
- `BreweryPost` - Brewery information
|
||||||
|
- `BreweryPostLocation` - Geographic data with `GEOGRAPHY` type
|
||||||
|
- `BeerStyle` - Beer style taxonomy
|
||||||
|
- `BeerPost` - Individual beers with ABV/IBU
|
||||||
|
- `BeerPostComment` - User reviews and ratings
|
||||||
|
- `Photo` - Image metadata
|
||||||
|
|
||||||
|
**Stored Procedures** (examples)
|
||||||
|
- `USP_RegisterUser` - Create user account with credential
|
||||||
|
- `USP_GetUserAccountByUsername` - Retrieve user by username
|
||||||
|
- `USP_RotateUserCredential` - Update password
|
||||||
|
- `USP_CreateCountry/StateProvince/City` - Location management
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Authentication & Security
|
||||||
|
|
||||||
|
- **Password Hashing**: Argon2id with configurable parameters
|
||||||
|
- Salt: 128-bit (16 bytes)
|
||||||
|
- Hash: 256-bit (32 bytes)
|
||||||
|
- Memory: 64MB
|
||||||
|
- Iterations: 4
|
||||||
|
- Parallelism: Based on CPU cores
|
||||||
|
|
||||||
|
- **JWT Tokens**: HS256 signing
|
||||||
|
- Claims: User ID (sub), Username (unique_name), JTI
|
||||||
|
- Configurable expiration (60-120 minutes)
|
||||||
|
- Secret key from environment variable
|
||||||
|
|
||||||
|
- **Credential Management**:
|
||||||
|
- Credential rotation/invalidation supported
|
||||||
|
- Expiry tracking (90-day default)
|
||||||
|
- Revocation timestamps
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture Patterns
|
||||||
|
|
||||||
|
### Layered Architecture
|
||||||
|
```
|
||||||
|
API (Controllers)
|
||||||
|
|
|
||||||
|
Service Layer (Business Logic)
|
||||||
|
|
|
||||||
|
Repository Layer (Data Access)
|
||||||
|
|
|
||||||
|
Database (SQL Server)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Design Patterns
|
||||||
|
- **Repository Pattern**: Abstraction over data access
|
||||||
|
- **Dependency Injection**: Constructor injection throughout
|
||||||
|
- **Factory Pattern**: `ISqlConnectionFactory` for database connections
|
||||||
|
- **Service Pattern**: Encapsulated business logic
|
||||||
|
|
||||||
|
### SQL-First Approach
|
||||||
|
- All CRUD operations via stored procedures
|
||||||
|
- No ORM (Entity Framework, Dapper, etc.)
|
||||||
|
- Direct ADO.NET for maximum control
|
||||||
|
- Version-controlled schema via DbUp
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Docker & Containerization
|
||||||
|
|
||||||
|
|
||||||
|
### Container Architecture
|
||||||
|
|
||||||
|
### Docker Compose Environments
|
||||||
|
|
||||||
|
Three separate compose files manage different environments:
|
||||||
|
|
||||||
|
#### 1. **Development** (`docker-compose.dev.yaml`)
|
||||||
|
- **Purpose**: Local development with live data
|
||||||
|
- **Features**:
|
||||||
|
- SQL Server with persistent volume
|
||||||
|
- Database migrations with `CLEAR_DATABASE=true` (drops/recreates schema)
|
||||||
|
- Seed data for testing
|
||||||
|
- API accessible on `localhost:8080`
|
||||||
|
- Hot reload support via volume mounts
|
||||||
|
|
||||||
|
**Services**:
|
||||||
|
```yaml
|
||||||
|
sqlserver # SQL Server 2022 (port 1433)
|
||||||
|
database.migrations # Runs DbUp migrations
|
||||||
|
database.seed # Seeds initial data
|
||||||
|
api.core # Web API (ports 8080, 8081)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Usage**:
|
||||||
|
```bash
|
||||||
|
docker compose -f docker-compose.dev.yaml up -d
|
||||||
|
docker compose -f docker-compose.dev.yaml logs -f # View logs
|
||||||
|
docker compose -f docker-compose.dev.yaml down # Stop all services
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. **Testing** (`docker-compose.test.yaml`)
|
||||||
|
- **Purpose**: Automated CI/CD testing
|
||||||
|
- **Features**:
|
||||||
|
- Isolated test database
|
||||||
|
- Runs integration and unit tests
|
||||||
|
- Test results exported to `./test-results/`
|
||||||
|
- Containers exit after tests complete
|
||||||
|
|
||||||
|
**Services**:
|
||||||
|
```yaml
|
||||||
|
sqlserver # Test database instance
|
||||||
|
database.migrations # Fresh schema each run
|
||||||
|
database.seed # Test data
|
||||||
|
api.specs # Integration tests (Reqnroll)
|
||||||
|
repository.tests # Unit tests (xUnit)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Usage**:
|
||||||
|
```bash
|
||||||
|
docker compose -f docker-compose.test.yaml up --abort-on-container-exit;
|
||||||
|
docker compose -f docker-compose.test.yaml down -v;
|
||||||
|
# View results in ./test-results/
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. **Production** (`docker-compose.prod.yaml`)
|
||||||
|
- **Purpose**: Production-like deployment
|
||||||
|
- **Features**:
|
||||||
|
- Production logging levels
|
||||||
|
- No database clearing
|
||||||
|
- Optimized builds
|
||||||
|
- Health checks enabled
|
||||||
|
- Restart policies configured
|
||||||
|
|
||||||
|
**Services**:
|
||||||
|
```yaml
|
||||||
|
sqlserver # Production SQL Server
|
||||||
|
database.migrations # Schema updates only (no drops)
|
||||||
|
api.core # Production API
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service Dependencies
|
||||||
|
|
||||||
|
Docker Compose manages service startup order using **health checks** and **depends_on** conditions:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
database.migrations:
|
||||||
|
depends_on:
|
||||||
|
sqlserver:
|
||||||
|
condition: service_healthy # Waits for SQL Server to be ready
|
||||||
|
|
||||||
|
database.seed:
|
||||||
|
depends_on:
|
||||||
|
database.migrations:
|
||||||
|
condition: service_completed_successfully # Waits for migrations
|
||||||
|
```
|
||||||
|
|
||||||
|
**Flow**:
|
||||||
|
1. `sqlserver` starts and runs health check (SQL query)
|
||||||
|
2. `database.migrations` starts when SQL Server is healthy
|
||||||
|
3. `database.seed` starts when migrations complete successfully
|
||||||
|
4. `api.core` starts when seeding completes
|
||||||
|
|
||||||
|
### Health Checks
|
||||||
|
|
||||||
|
SQL Server container includes a health check to ensure it's ready:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
healthcheck:
|
||||||
|
test: ["CMD-SHELL", "/opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P '${SA_PASSWORD}' -C -Q 'SELECT 1' || exit 1"]
|
||||||
|
interval: 10s
|
||||||
|
timeout: 5s
|
||||||
|
retries: 12
|
||||||
|
start_period: 30s
|
||||||
|
```
|
||||||
|
|
||||||
|
This prevents downstream services from attempting connections before SQL Server is ready.
|
||||||
|
|
||||||
|
### Volumes
|
||||||
|
|
||||||
|
**Persistent Storage**:
|
||||||
|
- `sqlserverdata-dev` - Development database data
|
||||||
|
- `sqlserverdata-test` - Test database data
|
||||||
|
- `sqlserverdata-prod` - Production database data
|
||||||
|
- `nuget-cache-dev/prod` - NuGet package cache (speeds up builds)
|
||||||
|
|
||||||
|
**Mounted Volumes**:
|
||||||
|
```yaml
|
||||||
|
volumes:
|
||||||
|
- ./test-results:/app/test-results # Export test results to host
|
||||||
|
- nuget-cache-dev:/root/.nuget/packages # Cache dependencies
|
||||||
|
```
|
||||||
|
|
||||||
|
### Networks
|
||||||
|
|
||||||
|
Each environment uses isolated bridge networks:
|
||||||
|
- `devnet` - Development network
|
||||||
|
- `testnet` - Testing network (fully isolated)
|
||||||
|
- `prodnet` - Production network
|
||||||
|
|
||||||
|
This prevents cross-environment communication and enhances security.
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
All containers receive configuration via environment variables:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
environment:
|
||||||
|
ASPNETCORE_ENVIRONMENT: "Development"
|
||||||
|
DOTNET_RUNNING_IN_CONTAINER: "true"
|
||||||
|
DB_CONNECTION_STRING: "${DB_CONNECTION_STRING}"
|
||||||
|
JWT_SECRET: "${JWT_SECRET}"
|
||||||
|
```
|
||||||
|
|
||||||
|
Values are populated from the `.env` file in the project root.
|
||||||
|
|
||||||
|
### Container Lifecycle
|
||||||
|
|
||||||
|
**Development Workflow**:
|
||||||
|
```bash
|
||||||
|
# Start environment
|
||||||
|
docker compose -f docker-compose.dev.yaml up -d
|
||||||
|
|
||||||
|
# View logs
|
||||||
|
docker compose -f docker-compose.dev.yaml logs -f api.core
|
||||||
|
|
||||||
|
# Restart a service
|
||||||
|
docker compose -f docker-compose.dev.yaml restart api.core
|
||||||
|
|
||||||
|
# Rebuild after code changes
|
||||||
|
docker compose -f docker-compose.dev.yaml up -d --build api.core
|
||||||
|
|
||||||
|
# Clean shutdown
|
||||||
|
docker compose -f docker-compose.dev.yaml down
|
||||||
|
|
||||||
|
# Remove volumes (fresh start)
|
||||||
|
docker compose -f docker-compose.dev.yaml down -v
|
||||||
|
```
|
||||||
|
|
||||||
|
**Testing Workflow**:
|
||||||
|
```bash
|
||||||
|
# Run tests (containers auto-exit)
|
||||||
|
docker compose -f docker-compose.test.yaml up --abort-on-container-exit
|
||||||
|
|
||||||
|
# Check test results
|
||||||
|
cat test-results/test-results.trx
|
||||||
|
cat test-results/repository-tests.trx
|
||||||
|
|
||||||
|
# Clean up
|
||||||
|
docker compose -f docker-compose.test.yaml down -v
|
||||||
|
```
|
||||||
|
|
||||||
|
## Docker Tips & Troubleshooting
|
||||||
|
|
||||||
|
### Common Commands
|
||||||
|
|
||||||
|
**View running containers**:
|
||||||
|
```bash
|
||||||
|
docker ps
|
||||||
|
```
|
||||||
|
|
||||||
|
**View all containers (including stopped)**:
|
||||||
|
```bash
|
||||||
|
docker ps -a
|
||||||
|
```
|
||||||
|
|
||||||
|
**View logs for a specific service**:
|
||||||
|
```bash
|
||||||
|
docker compose -f docker-compose.dev.yaml logs -f api.core
|
||||||
|
```
|
||||||
|
|
||||||
|
**Execute commands in a running container**:
|
||||||
|
```bash
|
||||||
|
docker exec -it dev-env-api-core bash
|
||||||
|
```
|
||||||
|
|
||||||
|
**Connect to SQL Server from host**:
|
||||||
|
```bash
|
||||||
|
# Using sqlcmd (if installed)
|
||||||
|
sqlcmd -S localhost,1433 -U sa -P 'YourStrong!Passw0rd' -C
|
||||||
|
|
||||||
|
# Config
|
||||||
|
Server: localhost,1433
|
||||||
|
Authentication: SQL Login
|
||||||
|
Username: sa
|
||||||
|
Password: (from .env)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Roadmap
|
## Roadmap
|
||||||
|
|
||||||
- Complete migration of backend logic from Next.js to .NET.
|
### Near-term
|
||||||
- Expand stored procedure coverage for CRUD and domain operations.
|
- [ ] Complete API endpoints for breweries and beers
|
||||||
- Introduce microservices for image upload and mapping; evaluate auth as a separate service.
|
- [ ] Integrate frontend with .NET API
|
||||||
- Harden CI/CD, testing, and observability across API, repository, and services.
|
- [ ] Implement image upload service
|
||||||
|
- [ ] Add comprehensive API documentation
|
||||||
|
|
||||||
|
### Medium-term
|
||||||
|
- [ ] Geospatial queries for nearby breweries
|
||||||
|
- [ ] Advanced authentication (OAuth, 2FA)
|
||||||
|
---
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
See [LICENSE.md](LICENSE.md).
|
See [LICENSE.md](LICENSE.md) for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contact & Support
|
||||||
|
|
||||||
|
For questions about this project, please open an issue in the repository.
|
||||||
|
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user