feat: enhance README and TODO documentation, implement mobile menu functionality in Header component
- Updated README.md with project details, quick start instructions, and tech stack. - Expanded TODO.md to reflect current project status and backlog items, including Linear ticket synchronization. - Added mobile menu toggle functionality in Header component with corresponding tests for user interactions. - Configured Next.js for Docker deployment and optimized build settings.
This commit is contained in:
Do Siki
@@ -0,0 +1,377 @@
|
||||
# GitHub CI/CD Guide - Code & Deployment
|
||||
|
||||
## 🎯 **Cél: GitHub-specifikus CI/CD Pipeline**
|
||||
|
||||
Ez a dokumentum a **GitHub Actions** rendszerét írja le, amely **csak** a CI/CD és deployment-re fókuszál.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **GitHub CI/CD Architektúra**
|
||||
|
||||
### **Pipeline Folyamat:**
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Code Push] --> B[GitHub Actions]
|
||||
B --> C[Run Tests]
|
||||
B --> D[Build Docker Image]
|
||||
B --> E[Push to Registry]
|
||||
B --> F[Deploy to Dokploy]
|
||||
|
||||
G[PR Creation] --> H[Test Validation]
|
||||
H --> I[Staging Deploy]
|
||||
|
||||
J[Manual Trigger] --> B
|
||||
```
|
||||
|
||||
### **Mit kezel a GitHub CI/CD:**
|
||||
- ✅ **Source Code** versioning és tracking
|
||||
- ✅ **Test Execution** (unit, integration, e2e)
|
||||
- ✅ **Docker Image** build és registry push
|
||||
- ✅ **Deployment** staging és production környezetekre
|
||||
- ✅ **PR Validation** és code review support
|
||||
- ✅ **Build Artifacts** és reporting
|
||||
|
||||
---
|
||||
|
||||
## 🔄 **GitHub Actions Workflows**
|
||||
|
||||
### **1. Main CI/CD Pipeline (`.github/workflows/ci.yml`)**
|
||||
|
||||
#### **Trigger Events:**
|
||||
```yaml
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
```
|
||||
|
||||
#### **Job Sequence:**
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Test Phase] --> B[Docker Tests]
|
||||
B --> C[Build Phase]
|
||||
C --> D[Test Summary]
|
||||
D --> E[Deploy Staging]
|
||||
D --> F[Deploy Production]
|
||||
```
|
||||
|
||||
#### **Jobs Detail:**
|
||||
|
||||
##### **🧪 Test Phase**
|
||||
- **Unit Tests**: Component és API tesztek
|
||||
- **Browser Integration**: jsdom + mocked APIs
|
||||
- **Test Artifacts**: JSON results export
|
||||
|
||||
##### **🐳 Docker Integration Tests**
|
||||
- **Docker Services**: Next.js + MongoDB + monitoring
|
||||
- **Integration Tests**: Real HTTP calls
|
||||
- **E2E Tests**: Complete user workflows
|
||||
|
||||
##### **🏗️ Build Phase**
|
||||
- **Docker Image**: Multi-stage production build
|
||||
- **Registry Push**: GitHub Container Registry
|
||||
- **Image Tagging**: Branch és commit alapján
|
||||
|
||||
##### **📊 Test Summary**
|
||||
- **PR Comments**: Test results summary
|
||||
- **Build Status**: Success/failure reporting
|
||||
- **Artifact Upload**: Test results és reports
|
||||
|
||||
##### **🚀 Deployment**
|
||||
- **Staging**: `develop` branch → Dokploy staging
|
||||
- **Production**: `main` branch → Dokploy production
|
||||
|
||||
---
|
||||
|
||||
## 🐳 **Docker Integration**
|
||||
|
||||
### **Docker Image Build:**
|
||||
```dockerfile
|
||||
# Multi-stage build
|
||||
FROM node:20-alpine AS builder
|
||||
# ... build steps
|
||||
|
||||
FROM node:20-alpine AS runner
|
||||
# ... production setup
|
||||
```
|
||||
|
||||
### **Container Registry:**
|
||||
```yaml
|
||||
# GitHub Container Registry
|
||||
registry: ghcr.io
|
||||
image: ghcr.io/your-username/websitedev
|
||||
tags: |
|
||||
type=ref,event=branch
|
||||
type=sha,prefix={{branch}}-
|
||||
type=raw,value=latest,enable={{is_default_branch}}
|
||||
```
|
||||
|
||||
### **Docker Services (Testing):**
|
||||
```yaml
|
||||
# docker-compose.dev.yml
|
||||
services:
|
||||
app: # Next.js application
|
||||
mongodb: # Database
|
||||
mongo-express: # Database UI
|
||||
loki: # Logging
|
||||
grafana: # Monitoring
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **Deployment Integration**
|
||||
|
||||
### **Dokploy Integration:**
|
||||
```yaml
|
||||
# Staging Deployment
|
||||
deploy-staging:
|
||||
if: github.ref == 'refs/heads/develop'
|
||||
environment: staging
|
||||
steps:
|
||||
- name: Deploy to Dokploy Staging
|
||||
run: |
|
||||
curl -X POST "${{ secrets.DOKPLOY_STAGING_WEBHOOK }}" \
|
||||
-H "Authorization: Bearer ${{ secrets.DOKPLOY_TOKEN }}" \
|
||||
-d '{"image": "${{ needs.build.outputs.image-tag }}"}'
|
||||
|
||||
# Production Deployment
|
||||
deploy-production:
|
||||
if: github.ref == 'refs/heads/main'
|
||||
environment: production
|
||||
steps:
|
||||
- name: Deploy to Dokploy Production
|
||||
run: |
|
||||
curl -X POST "${{ secrets.DOKPLOY_PROD_WEBHOOK }}" \
|
||||
-H "Authorization: Bearer ${{ secrets.DOKPLOY_TOKEN }}" \
|
||||
-d '{"image": "${{ needs.build.outputs.image-tag }}"}'
|
||||
```
|
||||
|
||||
### **Environment Configuration:**
|
||||
```yaml
|
||||
# Staging Environment
|
||||
environment:
|
||||
name: staging
|
||||
url: https://staging.mozdit.hu
|
||||
|
||||
# Production Environment
|
||||
environment:
|
||||
name: production
|
||||
url: https://mozdit.hu
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **GitHub Configuration**
|
||||
|
||||
### **Required Secrets:**
|
||||
```bash
|
||||
# GitHub Repository Secrets
|
||||
DOKPLOY_STAGING_WEBHOOK=https://staging.webhook.url
|
||||
DOKPLOY_PROD_WEBHOOK=https://prod.webhook.url
|
||||
DOKPLOY_TOKEN=your_dokploy_token
|
||||
|
||||
# Optional (for advanced features)
|
||||
GITHUB_TOKEN=auto_provided
|
||||
```
|
||||
|
||||
### **Environment Variables:**
|
||||
```yaml
|
||||
env:
|
||||
NODE_VERSION: '20'
|
||||
REGISTRY: ghcr.io
|
||||
IMAGE_NAME: ${{ github.repository }}
|
||||
```
|
||||
|
||||
### **Branch Protection Rules:**
|
||||
```yaml
|
||||
# Recommended branch protection for main
|
||||
required_status_checks:
|
||||
- test
|
||||
- docker-tests
|
||||
- build
|
||||
required_reviews: 1
|
||||
enforce_admins: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 **Monitoring & Reporting**
|
||||
|
||||
### **GitHub Actions Status:**
|
||||
```markdown
|
||||
[]
|
||||
[]
|
||||
[]
|
||||
```
|
||||
|
||||
### **PR Comments:**
|
||||
```markdown
|
||||
## 🧪 Test Results Summary
|
||||
|
||||
### ✅ Unit Tests
|
||||
- All unit tests passed
|
||||
- Component tests: ✅
|
||||
- API tests: ✅
|
||||
|
||||
### 🐳 Integration Tests
|
||||
- Docker services tested
|
||||
- API endpoints: ✅
|
||||
- Database connectivity: ✅
|
||||
|
||||
### 📊 Build Status
|
||||
- Tests: ✅ All passing
|
||||
- Docker build: ✅ Ready
|
||||
- Deployment: ✅ Ready
|
||||
```
|
||||
|
||||
### **Build Artifacts:**
|
||||
- **Test Results**: `unit-results.json`, `integration-results.json`
|
||||
- **Docker Images**: `ghcr.io/user/repo:tag`
|
||||
- **Build Logs**: GitHub Actions logs
|
||||
- **Deployment Status**: Dokploy integration
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ **Local Development Integration**
|
||||
|
||||
### **Pre-commit Hooks:**
|
||||
```bash
|
||||
# Install pre-commit hooks
|
||||
npm install --save-dev husky lint-staged
|
||||
|
||||
# package.json
|
||||
{
|
||||
"husky": {
|
||||
"hooks": {
|
||||
"pre-commit": "lint-staged"
|
||||
}
|
||||
},
|
||||
"lint-staged": {
|
||||
"*.{js,ts,tsx}": ["eslint --fix", "git add"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### **Local Testing:**
|
||||
```bash
|
||||
# Run same tests as CI
|
||||
npm run test:all
|
||||
|
||||
# Test Docker build locally
|
||||
npm run docker:build
|
||||
|
||||
# Test deployment locally
|
||||
npm run docker:run
|
||||
```
|
||||
|
||||
### **Git Workflow:**
|
||||
```bash
|
||||
# Feature development
|
||||
git checkout -b feature/new-feature
|
||||
# ... development
|
||||
git add .
|
||||
git commit -m "feat: add new feature"
|
||||
git push origin feature/new-feature
|
||||
|
||||
# Create PR
|
||||
gh pr create --title "Add new feature" --body "Description"
|
||||
|
||||
# After review and merge
|
||||
git checkout main
|
||||
git pull origin main
|
||||
# Automatic deployment triggers
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **Troubleshooting**
|
||||
|
||||
### **Gyakori Problémák:**
|
||||
|
||||
#### **1. Docker Build Fails**
|
||||
```bash
|
||||
Error: Docker build failed
|
||||
```
|
||||
**Megoldás:**
|
||||
- Ellenőrizd a `Dockerfile` syntax-át
|
||||
- Ellenőrizd a `package.json` dependencies-ét
|
||||
- Ellenőrizd a build context-et
|
||||
|
||||
#### **2. Test Failures**
|
||||
```bash
|
||||
Error: Tests failed in CI
|
||||
```
|
||||
**Megoldás:**
|
||||
- Futtasd a teszteket helyileg: `npm run test:all`
|
||||
- Ellenőrizd a test environment változókat
|
||||
- Ellenőrizd a Docker services állapotát
|
||||
|
||||
#### **3. Deployment Fails**
|
||||
```bash
|
||||
Error: Dokploy deployment failed
|
||||
```
|
||||
**Megoldás:**
|
||||
- Ellenőrizd a `DOKPLOY_*` secrets-eket
|
||||
- Ellenőrizd a webhook URL-eket
|
||||
- Ellenőrizd a Dokploy service állapotát
|
||||
|
||||
### **Debug Commands:**
|
||||
```bash
|
||||
# Local Docker testing
|
||||
docker-compose -f docker-compose.dev.yml up -d
|
||||
docker-compose -f docker-compose.dev.yml logs -f
|
||||
|
||||
# GitHub Actions debugging
|
||||
gh run list --workflow=ci.yml
|
||||
gh run view <run-id> --log
|
||||
|
||||
# Docker image testing
|
||||
docker run -p 3000:3000 ghcr.io/user/repo:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 **Best Practices**
|
||||
|
||||
### **1. Branch Strategy:**
|
||||
- `main` → Production deployment
|
||||
- `develop` → Staging deployment
|
||||
- `feature/*` → Development branches
|
||||
- `hotfix/*` → Critical fixes
|
||||
|
||||
### **2. Commit Messages:**
|
||||
```bash
|
||||
feat: add new feature
|
||||
fix: resolve bug
|
||||
docs: update documentation
|
||||
test: add tests
|
||||
refactor: code refactoring
|
||||
```
|
||||
|
||||
### **3. PR Guidelines:**
|
||||
- Minden PR-nek kell test coverage
|
||||
- Minden PR-nek kell review
|
||||
- Breaking changes dokumentálása
|
||||
- Changelog frissítése
|
||||
|
||||
### **4. Deployment Strategy:**
|
||||
- Staging deployment minden `develop` push után
|
||||
- Production deployment csak `main` merge után
|
||||
- Rollback strategy kész
|
||||
- Health checks minden deployment után
|
||||
|
||||
---
|
||||
|
||||
## 🔗 **Kapcsolódó Dokumentumok**
|
||||
|
||||
- [Linear Sync Guide](./LINEAR-SYNC-GUIDE.md)
|
||||
- [Docker Setup](./DOCKER.md)
|
||||
- [Testing Guide](./proto/TESTING.md)
|
||||
- [Sync Status Analysis](./SYNC-STATUS-ANALYSIS.md)
|
||||
|
||||
---
|
||||
|
||||
**Utolsó frissítés:** 2025-09-05
|
||||
**Státusz:** GitHub CI/CD szétválasztva Linear sync-től
|
||||
**Következő lépés:** Dokploy konfiguráció és secrets beállítása
|
||||
Reference in New Issue
Block a user