np-dms/lcbp3

Fork 0

Files

admin 0aaa139145 251206:1400 version 1.5.1

2025-12-06 14:42:32 +07:00

11 KiB

Raw Blame History

Quick Start Guide

Project: LCBP3-DMS Version: 1.5.1 Last Updated: 2025-12-02

⚡ 5-Minute Quick Start

This guide will get you up and running with LCBP3-DMS in 5 minutes.

👨‍💻 For Developers

Prerequisites

# Required
- Docker 20.10+
- Docker Compose 2.0+
- Git
- Node.js 18+ (for local development)

# Recommended
- VS Code
- Postman or similar API testing tool

Step 1: Clone Repository

git clone <repository-url>
cd lcbp3

Step 2: Setup Environment

# Backend
cp backend/.env.example backend/.env
# Edit backend/.env and set required values

# Frontend
cp frontend/.env.example frontend/.env.local
# Edit frontend/.env.local

Step 3: Start Services

# Start all services with Docker Compose
docker-compose up -d

# Check status
docker-compose ps

Step 4: Initialize Database

# Run migrations
docker exec lcbp3-backend npm run migration:run

# (Optional) Seed sample data
docker exec lcbp3-backend npm run seed

Step 5: Access Application

# Backend API
http://localhost:3000

# Health check
curl http://localhost:3000/health

# Frontend
http://localhost:3001

# API Documentation (Swagger)
http://localhost:3000/api/docs

Default Admin Account:

Username: admin
Password: Admin@123 (Change immediately!)

🧪 For QA/Testers

Running Tests

# Backend unit tests
docker exec lcbp3-backend npm test

# Backend e2e tests
docker exec lcbp3-backend npm run test:e2e

# Frontend tests
docker exec lcbp3-frontend npm test

Test Data

# Reset database to clean state
docker exec lcbp3-backend npm run migration:revert
docker exec lcbp3-backend npm run migration:run

# Load test data
docker exec lcbp3-backend npm run seed

🚀 For DevOps

Deploy to Staging

# Build images
docker-compose build

# Push to registry
docker-compose push

# Deploy to staging server
ssh staging-server
cd /app/lcbp3
git pull
docker-compose pull
docker-compose up -d

# Run migrations
docker exec lcbp3-backend npm run migration:run

Deploy to Production

# Backup database first!
./scripts/backup-database.sh

# Deploy with zero-downtime
./scripts/zero-downtime-deploy.sh

# Verify deployment
curl -f https://lcbp3-dms.example.com/health

📊 For Project Managers

View Project Status

Documentation:

Requirements: specs/01-requirements
Architecture: specs/02-architecture
Tasks: specs/06-tasks

Metrics:

Check Monitoring Dashboard (if setup)
Review Task Board

🔍 Common Tasks

Create New Module

# Backend
cd backend
nest g module modules/my-module
nest g controller modules/my-module
nest g service modules/my-module

# Follow backend guidelines
# See: specs/03-implementation/backend-guidelines.md

Create New Migration

# Generate migration from entity changes
docker exec lcbp3-backend npm run migration:generate -- -n MigrationName

# Create empty migration
docker exec lcbp3-backend npm run migration:create -- -n MigrationName

# Run migrations
docker exec lcbp3-backend npm run migration:run

# Revert last migration
docker exec lcbp3-backend npm run migration:revert

View Logs

# All services
docker-compose logs -f

# Specific service
docker logs lcbp3-backend -f --tail=100

# Search logs
docker logs lcbp3-backend 2>&1 | grep "ERROR"

Database Access

# MySQL CLI
docker exec -it lcbp3-mariadb mysql -u root -p

# Run SQL file (Linux/Mac)
docker exec -i lcbp3-mariadb mysql -u root -p lcbp3_dms < script.sql

# Run SQL file (Windows PowerShell)
Get-Content script.sql | docker exec -i lcbp3-mariadb mysql -u root -p lcbp3_dms

# Run SQL file (Windows CMD)
type script.sql | docker exec -i lcbp3-mariadb mysql -u root -p lcbp3_dms

Redis Access

# Redis CLI
docker exec -it lcbp3-redis redis-cli -a <password>

# Check keys
docker exec lcbp3-redis redis-cli -a <password> KEYS "*"

# Clear cache
docker exec lcbp3-redis redis-cli -a <password> FLUSHDB

🐛 Troubleshooting

Backend not starting

# Check logs
docker logs lcbp3-backend

# Common issues:
# 1. Database connection - check DB_HOST in .env
# 2. Redis connection - check REDIS_HOST in .env
# 3. Port conflict - check if port 3000 is free

Database connection failed

# Check if MariaDB is running
docker ps | grep mariadb

# Test connection
docker exec lcbp3-mariadb mysqladmin ping -h localhost

# Check credentials
docker exec lcbp3-backend env | grep DB_

Frontend build failed

# Clear cache and rebuild
docker exec lcbp3-frontend rm -rf .next node_modules
docker exec lcbp3-frontend npm install
docker exec lcbp3-frontend npm run build

Port already in use

# Linux/Mac: Find process using port
lsof -i :3000

# Windows: Find process using port
netstat -ano | findstr :3000

# Linux/Mac: Kill process
kill -9 <PID>

# Windows: Kill process
taskkill /PID <PID> /F

# Or change port in docker-compose.yml

⚠️ Common Pitfalls

1. Environment Variables Not Loaded

Problem: Backend fails to start with "config is not defined" or similar errors.

Solution:

# Ensure .env file exists
ls backend/.env  # Linux/Mac
dir backend\.env  # Windows

# Check if Docker container has access to .env
docker exec lcbp3-backend env | grep DB_

# Restart containers after .env changes
docker-compose down
docker-compose up -d

2. Database Migration Issues

Problem: Tables not found or schema mismatch.

Solution:

# Check migration status
docker exec lcbp3-backend npm run migration:show

# Run pending migrations
docker exec lcbp3-backend npm run migration:run

# If migration fails, check logs
docker logs lcbp3-backend --tail=50

# Rollback and retry if needed
docker exec lcbp3-backend npm run migration:revert

3. Redis Connection Timeout

Problem: Queue jobs not processing or "ECONNREFUSED" errors.

Solution:

# Check if Redis is running
docker ps | grep redis

# Test Redis connection
docker exec lcbp3-redis redis-cli ping

# Check Redis logs
docker logs lcbp3-redis

# Verify REDIS_HOST in .env matches docker-compose service name

4. CORS Errors in Frontend

Problem: Browser blocks API requests with CORS policy errors.

Solution:

# Check CORS_ORIGIN in backend/.env
# Should match frontend URL (e.g., http://localhost:3001)

# For development, can use:
CORS_ORIGIN=http://localhost:3001,http://localhost:3000

# Restart backend after changes
docker-compose restart backend

5. File Upload Fails

Problem: File uploads return 413 (Payload Too Large) or timeout.

Solution:

# Check MAX_FILE_SIZE in .env (default 50MB)
MAX_FILE_SIZE=52428800

# Check NGINX upload limits if using reverse proxy
# client_max_body_size should be set appropriately

# Check disk space
docker exec lcbp3-backend df -h  # Linux/Mac

6. Docker Build Fails on Windows

Problem: Line ending issues (CRLF vs LF) cause build failures.

Solution:

# Configure Git to use LF line endings
git config --global core.autocrlf input

# Re-clone or convert existing files
git add --renormalize .
git commit -m "Normalize line endings"

# Or use .gitattributes file (already should be in repo)

7. Permission Denied in Containers

Problem: Cannot write files or execute commands inside containers.

Solution:

# Windows: Ensure Docker Desktop has access to the drive
# Settings → Resources → File Sharing

# Linux: Fix volume permissions
sudo chown -R $USER:$USER .

# Check container user
docker exec lcbp3-backend whoami

8. Hot Reload Not Working

Problem: Code changes don't reflect immediately during development.

Solution:

# Ensure volumes are mounted correctly in docker-compose.yml
# Check for:
volumes:
  - ./backend/src:/app/src

# Windows: May need to enable polling in NestJS
# Add to nest-cli.json:
"watchAssets": true,
"watchOptions": {
  "poll": 1000
}

# Restart dev server
docker-compose restart backend

9. TypeScript Compilation Errors

Problem: "Cannot find module" or type errors.

Solution:

# Clear build cache
docker exec lcbp3-backend rm -rf dist

# Reinstall dependencies
docker exec lcbp3-backend rm -rf node_modules package-lock.json
docker exec lcbp3-backend npm install

# Check TypeScript version matches
docker exec lcbp3-backend npm list typescript

10. Document Numbering Duplicates

Problem: Race condition causes duplicate document numbers.

Solution:

# Ensure Redis is running (required for distributed locks)
docker ps | grep redis

# Check Redis connection in logs
docker logs lcbp3-backend | grep -i redis

# Verify ENABLE_REDIS_LOCK=true in .env

# Check database constraints are in place
docker exec -i lcbp3-mariadb mysql -u root -p lcbp3_dms -e "
SHOW CREATE TABLE document_number_counters;
"

📚 Next Steps

Learn More

Architecture - System Architecture
Development - Backend Guidelines
Deployment - Deployment Guide
Decisions - ADR Index

Join the Team

Read Contributing Guidelines
Pick a task from Backend Tasks
Create a branch: git checkout -b feature/my-feature
Make changes and write tests
Submit Pull Request

💡 Tips & Best Practices

Development

✅ Always write tests for new features
✅ Follow coding guidelines
✅ Use TypeScript strict mode
✅ Add JSDoc for public APIs
✅ Keep Pull Requests small

Git Workflow

# Update main branch
git checkout main
git pull

# Create feature branch
git checkout -b feature/my-feature

# Make commits
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/my-feature

Code Review

Review Backend Guidelines
Check test coverage
Verify documentation updated
Run linter: npm run lint
Run tests: npm test

🆘 Getting Help

Resources

Documentation: /specs directory
API Docs: http://localhost:3000/api/docs
Issue Tracker: [Link to issue tracker]

Contact

Tech Lead: [Email]
DevOps: [Email]
Slack: #lcbp3-dms

✅ Checklist for First Day

Clone repository
Install prerequisites
Setup environment variables
Start Docker services
Run migrations
Access backend (http://localhost:3000/health)
Access frontend (http://localhost:3001)
Login with default credentials
Run tests
Read System Architecture
Read Backend Guidelines
Pick first task from Tasks

Welcome aboard! 🎉

Version: 1.5.1 Last Updated: 2025-12-02

11 KiB Raw Blame History

Quick Start Guide

⚡ 5-Minute Quick Start

👨‍💻 For Developers

Prerequisites

Step 1: Clone Repository

Step 2: Setup Environment

Step 3: Start Services

Step 4: Initialize Database

Step 5: Access Application

Step 6: Login

🧪 For QA/Testers

Running Tests

Test Data

🚀 For DevOps

Deploy to Staging

Deploy to Production

📊 For Project Managers

View Project Status

🔍 Common Tasks

Create New Module

Create New Migration

View Logs

Database Access

Redis Access

🐛 Troubleshooting

Backend not starting

Database connection failed

Frontend build failed

Port already in use

⚠️ Common Pitfalls

1. Environment Variables Not Loaded

2. Database Migration Issues

3. Redis Connection Timeout

4. CORS Errors in Frontend

5. File Upload Fails

6. Docker Build Fails on Windows

7. Permission Denied in Containers

8. Hot Reload Not Working

9. TypeScript Compilation Errors

10. Document Numbering Duplicates

📚 Next Steps

Learn More

Join the Team

💡 Tips & Best Practices

Development

Git Workflow

Code Review

🆘 Getting Help

Resources

Contact

✅ Checklist for First Day

11 KiB

Raw Blame History