5.6 KiB
Getting Started
This guide will help you set up and run The Biergarten App in your development environment.
Prerequisites
Before you begin, ensure you have the following installed:
- .NET SDK 10+ - Download
- Node.js 18+ - Download
- Docker Desktop - Download (recommended)
- Java 8+ - Required for generating diagrams from PlantUML (optional)
Quick Start with Docker (Recommended)
1. Clone the Repository
git clone <repository-url>
cd the-biergarten-app
2. Configure Environment Variables
Copy the example environment file:
cp .env.example .env.dev
Edit .env.dev with your configuration:
# Database (component-based for Docker)
DB_SERVER=sqlserver,1433
DB_NAME=Biergarten
DB_USER=sa
DB_PASSWORD=YourStrong!Passw0rd
# JWT Authentication
JWT_SECRET=your-secret-key-minimum-32-characters-required
For a complete list of environment variables, see Environment Variables.
3. Start the Development Environment
docker compose -f docker-compose.dev.yaml up -d
This command will:
- Start SQL Server container
- Run database migrations
- Seed initial data
- Start the API on http://localhost:8080
4. Access the API
- Swagger UI: http://localhost:8080/swagger
- Health Check: http://localhost:8080/health
5. View Logs
# All services
docker compose -f docker-compose.dev.yaml logs -f
# Specific service
docker compose -f docker-compose.dev.yaml logs -f api.core
6. Stop the Environment
docker compose -f docker-compose.dev.yaml down
# Remove volumes (fresh start)
docker compose -f docker-compose.dev.yaml down -v
Manual Setup (Without Docker)
If you prefer to run services locally without Docker:
Backend Setup
1. Start SQL Server
You can use a local SQL Server instance or a cloud-hosted one. Ensure it's accessible and you have the connection details.
2. Set Environment Variables
# 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-minimum-32-characters-required"
# 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-minimum-32-characters-required"
3. Run Database Migrations
cd src/Core
dotnet run --project Database/Database.Migrations/Database.Migrations.csproj
4. Seed the Database
dotnet run --project Database/Database.Seed/Database.Seed.csproj
5. Start the API
dotnet run --project API/API.Core/API.Core.csproj
The API will be available at http://localhost:5000 (or the port specified in launchSettings.json).
Frontend Setup
Note
: The frontend is currently transitioning from its standalone Prisma/Postgres backend to the .NET API. Some features may still use the old backend.
1. Navigate to Website Directory
cd Website
2. Create Environment File
Create .env.local with frontend variables. See Environment Variables - Frontend for the complete list.
BASE_URL=http://localhost:3000
NODE_ENV=development
# Generate secrets
CONFIRMATION_TOKEN_SECRET=$(openssl rand -base64 127)
RESET_PASSWORD_TOKEN_SECRET=$(openssl rand -base64 127)
SESSION_SECRET=$(openssl rand -base64 127)
# External services (you'll need to register for these)
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_KEY=your-api-key
CLOUDINARY_SECRET=your-api-secret
NEXT_PUBLIC_MAPBOX_KEY=your-mapbox-token
# Database URL (current Prisma setup)
DATABASE_URL=your-postgres-connection-string
3. Install Dependencies
npm install
4. Run Prisma Migrations
npx prisma generate
npx prisma migrate dev
5. Start Development Server
npm run dev
The frontend will be available at http://localhost:3000.
Generate Diagrams (Optional)
The project includes PlantUML diagrams that can be converted to PDF or PNG:
Install Java
Make sure Java 8+ is installed:
# Check Java version
java -version
Generate Diagrams
# Generate all PDFs
make
# Generate PNGs
make pngs
# Generate both
make diagrams
# View help
make help
Generated diagrams will be in docs/diagrams/pdf/.
Next Steps
- Test the API: Visit http://localhost:8080/swagger and try the endpoints
- Run Tests: See Testing Guide
- Learn the Architecture: Read Architecture Overview
- Understand Docker Setup: See Docker Guide
- Database Details: Check Database Schema
Troubleshooting
Port Already in Use
If port 8080 or 1433 is already in use, you can either:
- Stop the service using that port
- Change the port mapping in
docker-compose.dev.yaml
Database Connection Issues
Check that:
- SQL Server container is running:
docker ps - Connection string is correct in
.env.dev - Health check is passing:
docker compose -f docker-compose.dev.yaml ps
Container Won't Start
View container logs:
docker compose -f docker-compose.dev.yaml logs <service-name>
Fresh Start
Remove all containers and volumes:
docker compose -f docker-compose.dev.yaml down -v
docker system prune -f
For more troubleshooting, see the Docker Guide.