mirror of
https://github.com/aaronpo97/the-biergarten-app.git
synced 2026-10-14 17:54:42 +00:00
Refactor documentation and diagrams for web/pipeline. (#272)
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> for assistance with diagram creation and documentation prose updates.
This commit is contained in:
Aaron Po
166
docs/web/getting-started.md
Normal file
166
docs/web/getting-started.md
Normal file
@@ -0,0 +1,166 @@
|
||||
---
|
||||
title: Getting started — local setup for backend and frontend
|
||||
last-updated: 2026-08-31
|
||||
tags:
|
||||
- getting-started
|
||||
- setup
|
||||
- onboarding
|
||||
---
|
||||
|
||||
This guide covers local setup for the Biergarten stack: the .NET backend in
|
||||
`web/backend` and the React Router frontend in `web/frontend`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **.NET SDK 10+**
|
||||
- **Node.js 22+**
|
||||
- **Docker Desktop** or equivalent Docker Engine setup
|
||||
- **Java 8+** if you want to regenerate PlantUML diagrams
|
||||
|
||||
## Recommended path: Docker for backend, Node for frontend
|
||||
|
||||
### 1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/aaronpo97/the-biergarten-app
|
||||
cd the-biergarten-app
|
||||
```
|
||||
|
||||
### 2. Configure backend environment variables
|
||||
|
||||
Generate `.env.dev` with freshly randomized secrets:
|
||||
|
||||
```bash
|
||||
cd web
|
||||
./generate-env.sh .env.dev
|
||||
cd ..
|
||||
```
|
||||
|
||||
Or copy the template and fill in values manually:
|
||||
|
||||
```bash
|
||||
cp web/.env.example web/.env.dev
|
||||
```
|
||||
|
||||
At minimum, ensure `.env.dev` includes valid database and token values:
|
||||
|
||||
```bash
|
||||
DB_SERVER=sqlserver,1433
|
||||
DB_NAME=Biergarten
|
||||
DB_USER=sa
|
||||
DB_PASSWORD=YourStrong!Passw0rd
|
||||
ACCESS_TOKEN_SECRET=<generated>
|
||||
REFRESH_TOKEN_SECRET=<generated>
|
||||
CONFIRMATION_TOKEN_SECRET=<generated>
|
||||
WEBSITE_BASE_URL=http://localhost:3000
|
||||
```
|
||||
|
||||
See [Environment Variables](environment-variables.md) for the full list, and its
|
||||
[Generating an env file](environment-variables.md#generating-an-env-file)
|
||||
section for details on `generate-env.sh`.
|
||||
|
||||
### 3. Start the backend stack
|
||||
|
||||
```bash
|
||||
docker compose --env-file web/.env.dev -f web/docker-compose.dev.yaml up -d
|
||||
```
|
||||
|
||||
This starts SQL Server, migrations, seeding, the API, Mailpit (local dev SMTP),
|
||||
and SeaweedFS (local dev S3-compatible object storage for photo uploads).
|
||||
|
||||
Available endpoints:
|
||||
|
||||
| Service | URL |
|
||||
| ---------------- | ----------------------------- |
|
||||
| API Swagger | http://localhost:8080/swagger |
|
||||
| Health Check | http://localhost:8080/health |
|
||||
| Mailpit UI | http://localhost:8025 |
|
||||
| SeaweedFS S3 API | http://localhost:8333 |
|
||||
|
||||
### 4. Start the frontend
|
||||
|
||||
```bash
|
||||
cd web/frontend
|
||||
npm install
|
||||
API_BASE_URL=http://localhost:8080 SESSION_SECRET=dev-secret-change-me npm run dev
|
||||
```
|
||||
|
||||
The website will be available at the local address printed by React Router dev.
|
||||
|
||||
Required frontend runtime variables for local work:
|
||||
|
||||
- `API_BASE_URL` - Base URL for the .NET API
|
||||
- `SESSION_SECRET` - Cookie session signing secret for the website server
|
||||
|
||||
### 5. Optional: run Storybook
|
||||
|
||||
```bash
|
||||
cd web/frontend
|
||||
npm run storybook
|
||||
```
|
||||
|
||||
Storybook runs at http://localhost:6006 by default.
|
||||
|
||||
## Useful commands
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
docker compose --env-file web/.env.dev -f web/docker-compose.dev.yaml logs -f
|
||||
docker compose --env-file web/.env.dev -f web/docker-compose.dev.yaml down
|
||||
docker compose --env-file web/.env.dev -f web/docker-compose.dev.yaml down -v
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd web/frontend
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
npm run format:check
|
||||
npm run test:storybook
|
||||
npm run test:storybook:playwright
|
||||
```
|
||||
|
||||
## Manual backend setup
|
||||
|
||||
If you do not want to use Docker, you can run the backend locally.
|
||||
|
||||
### 1. Set environment variables
|
||||
|
||||
```bash
|
||||
export DB_CONNECTION_STRING="Server=localhost,1433;Database=Biergarten;User Id=sa;Password=YourStrong!Passw0rd;TrustServerCertificate=True;"
|
||||
export ACCESS_TOKEN_SECRET="<generated>"
|
||||
export REFRESH_TOKEN_SECRET="<generated>"
|
||||
export CONFIRMATION_TOKEN_SECRET="<generated>"
|
||||
export WEBSITE_BASE_URL="http://localhost:3000"
|
||||
export SEAWEEDFS_SERVICE_URL="http://localhost:8333"
|
||||
export SEAWEEDFS_ACCESS_KEY_ID="<generated>"
|
||||
export SEAWEEDFS_SECRET_ACCESS_KEY="<generated>"
|
||||
export SEAWEEDFS_BUCKET="my-bucket"
|
||||
```
|
||||
|
||||
### 2. Run migrations and seed
|
||||
|
||||
```bash
|
||||
cd web/backend
|
||||
dotnet run --project Database/Database.Migrations/Database.Migrations.csproj
|
||||
dotnet run --project Database/Database.Seed/Database.Seed.csproj
|
||||
```
|
||||
|
||||
### 3. Start the API
|
||||
|
||||
```bash
|
||||
dotnet run --project API/API.Core/API.Core.csproj
|
||||
```
|
||||
|
||||
## Archived frontend
|
||||
|
||||
`archive/next-js-web-app/` contains an archived Next.js frontend, kept for
|
||||
reference; it is not part of the running stack.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Review [Architecture](architecture.md)
|
||||
- Run backend and frontend checks from [Testing](testing.md)
|
||||
- Use [Docker Guide](docker.md) for container troubleshooting
|
||||
Reference in New Issue
Block a user