Diamond Shop System - Setup Guide

1Welcome

Welcome to the Diamond Shop System setup guide! This interactive guide will walk you through setting up your development environment step by step.

What You'll Learn

How to set up your development environment
Configure Docker services for database management
Set up local development with hot reload
Access and manage your database with pgAdmin
Handle Entity Framework migrations

Prerequisites Check

Before we begin, make sure you have these installed:

✓Docker Desktop (latest version)
✓.NET 8.0 SDK
✓Git
✓Visual Studio Code or Visual Studio

                    ⚠️Important: This guide assumes you have basic knowledge of Docker, .NET, and command line operations.
                

2Clone Repository

Let's start by getting the code on your local machine.

Clone the Repository

git clone <your-repository-url>
cd DiamondShopSystem

Replace <your-repository-url> with the actual GitHub repository URL.

                    ✓Success Check: You should now have a DiamondShopSystem folder with all the project files.
                

3Environment Setup

Now we need to configure your environment variables.

Create .env File

Create a .env file in the root directory:

📄 .env

# Database Configuration
DB_NAME=diamondshop_db
DB_PASSWORD=your_secure_password_here

# Supabase Configuration (if using)
SUPABASECONNECT_USER_ID=your_supabase_user
SUPABASECONNECT_PASSWORD=your_supabase_password
SUPABASECONNECT_SERVER=your_supabase_server
SUPABASECONNECT_PORT=5432
SUPABASECONNECT_DATABASE=your_supabase_db

# JWT Configuration
JWT_AUDIENCE=your_jwt_audience
JWT_ISSUER=your_jwt_issuer
JWT_KEY=your_super_secret_jwt_key_here_make_it_long_and_complex
JWT_REFRESH_TOKEN_VALIDITY_IN_DAYS=7
JWT_TOKEN_VALIDITY_IN_MINUTES=60

                    ⚠️Security Note: Replace all placeholder values with your actual configuration. Never commit this file to version control!
                

4Docker Setup

Let's start the database services using Docker.

Start Database Services

We'll start only PostgreSQL and pgAdmin for now:

docker-compose up postgres pgadmin -d

This command will:

Start PostgreSQL on port 5433
Start pgAdmin on port 5050
Run them in detached mode (-d)

Verify Services

docker-compose ps

✓Success Check: Both services should show as "Up" and healthy.

5pgAdmin Setup

Now let's configure pgAdmin to access your database.

Access pgAdmin

1. Open your browser and go to: http://localhost:5050

2. Login with:

Email: admin@admin.com
Password: admin123

Add Database Server

3. Right-click "Servers" → "Register" → "Server"

4. Fill in the connection details:

Name: Diamond Shop DB
Host name/address: postgres
Port: 5432
Username: postgres
Password: [Your DB_PASSWORD from .env]

✓Success Check: You should now see your database server connected in pgAdmin.

6Development Setup

Now for the best part - setting up your development environment for fast iteration!

Recommended: Local Development

This approach gives you hot reload without Docker rebuilds:

# Navigate to API project
cd DiamondShopSystem.API

# Run with hot reload
dotnet watch run

Your API will be available at: http://localhost:5000

Alternative: Full Docker

If you prefer everything in Docker:

# Build and start all services
docker-compose up --build

API will be available at: http://localhost:8081

7Database Migrations

Let's set up your database schema using Entity Framework migrations.

Option 1: Using Docker EF Tools

# Start EF tools container
docker-compose run --rm ef

# Inside the container, run migrations
dotnet ef database update --project DiamondShopSystem.API

# Exit container
exit

Option 2: Using Local .NET CLI

# Install EF Core tools (if not installed)
dotnet tool install --global dotnet-ef

# Run migrations
dotnet ef database update --project DiamondShopSystem.API

✓Success Check: Check pgAdmin to see your database tables have been created.

8Daily Workflow

Here's your recommended daily development workflow for maximum productivity.

🌅 Start Your Day

# Start database services
docker-compose up postgres pgadmin -d

# Navigate to API project
cd DiamondShopSystem.API

# Start development with hot reload
dotnet watch run

💻 During Development

Edit your code - changes will automatically reload
Use pgAdmin for database queries and management
Create migrations when you change your models

🌙 End Your Day

# Stop development server (Ctrl+C)
# Optionally stop database services
docker-compose down

9Useful Commands

Keep these commands handy for your daily development tasks.

Docker Management

# View running containers
docker-compose ps

# View logs
docker-compose logs diamondshopsystem.api

# Stop all services
docker-compose down

# Rebuild specific service
docker-compose build diamondshopsystem.api

Database Operations

# Connect to PostgreSQL directly
docker-compose exec postgres psql -U postgres -d your_db_name

# Create backup
docker-compose exec postgres pg_dump -U postgres your_db_name > backup.sql

EF Core Migrations

# Create new migration
dotnet ef migrations add MigrationName --project DiamondShopSystem.API

# Update database
dotnet ef database update --project DiamondShopSystem.API

10Troubleshooting

Common issues and their solutions.

🚨 Common Issues

Port Conflicts

If ports 5433, 5050, or 8081 are in use, modify the port mappings in docker-compose.yml

Database Connection Issues

# Check PostgreSQL health
docker-compose exec postgres pg_isready -U postgres

# View container status
docker-compose ps

Permission Issues (Linux/Mac)

Add your user to the docker group or use sudo with Docker commands.

Migration Issues

Verify connection string points to correct database
Check if EF Core tools are installed
Ensure database permissions are correct

                    ✓Pro Tip: Always check Docker logs when something isn't working: docker-compose logs [service-name]
                

🎉Congratulations!

You've successfully set up your Diamond Shop System development environment!

What You've Accomplished

✓Cloned the repository
✓Configured environment variables
✓Set up Docker services
✓Configured pgAdmin for database management
✓Set up local development with hot reload
✓Learned the recommended daily workflow

Next Steps

You're now ready to start developing! Here are some suggestions:

Explore the codebase and understand the project structure
Make a small change and see hot reload in action
Create your first database migration
Set up your preferred debugging tools

                    Happy Coding! 🚀

                    Your development environment is optimized for productivity with fast feedback loops and efficient database management.

💎 Diamond Shop System