Skip to content

docs: add Japanese and Chinese README translations #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Cho-Geer merged 1 commit into from
Jul 31, 2026
Merged

docs: add Japanese and Chinese README translations #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
352 changes: 352 additions & 0 deletions README.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,352 @@
# Booking System Deployment Guide

This document describes the complete deployment process for the Booking system, covering both development and production environments.

## Directory Structure

```
booking-deploy/
├── compose/ # Docker Compose configuration files
│ ├── docker-compose.dev.yml # Development environment orchestration
│ ├── docker-compose.prod.yml # Production environment orchestration
│ ├── dev.compose.env.example # Development environment variables template
│ └── prod.compose.env.example # Production environment variables template
├── env/ # Application environment variables
│ ├── dev/ # Development environment
│ │ ├── backend.env.example
│ │ └── frontend.env.example
│ └── prod/ # Production environment
│ ├── backend.env.example
│ └── frontend.env.example
└── scripts/ # Deployment scripts
├── deploy-dev.sh # Development environment deployment script
├── deploy-prod.sh # Production environment deployment script
└── verify-images.sh # Image verification script
```

## Environment Preparation

### 1. Docker and Docker Compose
- Docker Engine 20.10+ or Docker Desktop
- Docker Compose v2+ (recommended) or docker-compose v1.29+

### 2. Environment Variables Preparation

#### Development Environment
```bash
# Copy template files
cd booking-deploy

# Compose environment variables
cp compose/dev.compose.env.example compose/dev.compose.env
# Edit dev.compose.env to update Docker Hub image addresses if needed

# Application environment variables
cp env/dev/backend.env.example env/dev/backend.env
cp env/dev/frontend.env.example env/dev/frontend.env
# Edit .env files and set actual values (e.g., JWT_SECRET, etc.)
```

#### Production Environment
```bash
cd booking-deploy
cp compose/prod.compose.env.example compose/prod.compose.env
cp env/prod/backend.env.example env/prod/backend.env
cp env/prod/frontend.env.example env/prod/frontend.env

# Important: Production environment requires strong passwords and real secrets
```

## Image Tagging Strategy

The Booking system's CI/CD pipeline automatically generates multiple types of Docker image tags, each with different purposes and reliability characteristics:

### Tag Types

| Tag Type | Format Example | Mutability | Recommended Use | Reliability |
|----------|---------------|------------|----------------|-------------|
| **Branch Tags** | `dev`, `main` | **Mutable** - Updated on every push | Rapid development, integration testing | Low - Not suitable for production |
| **Commit Tags** | `dev-abc123`, `main-def456` | **Immutable** - Tied to specific commits | Reliable deployment, rollback, auditing | High - Recommended for production |
| **Semantic Version** | `v1.0.0`, `v1.2.3` | **Immutable** - Versioned releases | Official releases, version management | Highest - Best practice for production |
| **PR Tags** | `pr-123` | **Mutable** - PR builds | PR verification, code review | Low - For temporary use only |
| **latest** | `latest` | **Mutable** - Latest from main branch | Development convenience | Low - Prohibited for production |

### Selection Guide

1. **Development Environment**:
- Rapid iteration: Use `dev` branch tag
- Reliable testing: Use `dev-<commit-hash>` commit tag

2. **Production Environment**:
- **Must use immutable tags**: Commit tags or semantic version tags
- Emergency fixes: Use `main-<commit-hash>`
- Official releases: Use semantic versions like `v1.0.0`
- **Prohibited: `main` or `latest` tags**

### Image Verification

All images are verified with real deployment topology:
- ✅ Include PostgreSQL and Redis dependencies
- ✅ Run database migrations
- ✅ Verify health endpoint (`/v1/health`)
- ✅ Check database and Redis connection status
- ✅ Verify frontend accessibility

### View Available Tags

Image tags are automatically generated by GitHub Actions workflows:
- Backend images: [booking-backend/.github/workflows/backend-image.yml](../booking-backend/.github/workflows/backend-image.yml)
- Frontend images: [booking-frontend/.github/workflows/frontend-image.yml](../booking-frontend/.github/workflows/frontend-image.yml)
- Migration images: Dedicated `booking-backend-migration` image

### Rollback Operations

To rollback to a previous version:
1. Find the previous commit tag (e.g., `main-abc123def`)
2. Update image tags in `prod.compose.env` file
3. Re-run the deployment script

```bash
# Rollback to specific commit
BACKEND_IMAGE=docker.io/cho-geer/booking-backend:main-previous-commit
BACKEND_MIGRATION_IMAGE=docker.io/cho-geer/booking-backend-migration:main-previous-commit
FRONTEND_IMAGE=docker.io/cho-geer/booking-frontend:main-previous-commit
```

## Deployment Process

### Development Environment Deployment
```bash
# Enter booking-deploy directory
cd booking-deploy

# Run deployment script
./scripts/deploy-dev.sh
```

The deployment script performs the following steps:
1. **Check for environment variable files** existence
2. **Pull latest images** from Docker Hub
3. **Execute database migrations** (independent migration service)
4. **Start all services** (PostgreSQL, Redis, Backend, Frontend)
5. **Health check** to verify all services are available
- Backend health endpoint: `http://localhost:3001/v1/health`
- Backend Swagger: `http://localhost:3001/api/docs`
- Frontend page: `http://localhost:3000`

### Production Environment Deployment
```bash
cd booking-deploy
./scripts/deploy-prod.sh
```

The production environment deployment process is the same as development environment but uses different configurations:
- Different Docker Compose file (`docker-compose.prod.yml`)
- Different environment variable files (`prod.compose.env`, `env/prod/`)
- Possibly different network configurations and resource constraints

## Service Architecture

### Development Environment Services
| Service | Image | Port | Description |
|---------|-------|------|-------------|
| PostgreSQL | `postgres:16` | 5432 | Main database |
| Redis | `redis:7-alpine` | 6379 | Cache and session storage |
| Backend | `${BACKEND_IMAGE}` | 3001 | NestJS API service |
| Frontend | `${FRONTEND_IMAGE}` | 3000 | Next.js frontend application |
| Migration | `${BACKEND_MIGRATION_IMAGE}` | - | Database migration service |

### Production Environment Differences
- May use external databases (e.g., RDS) instead of containerized PostgreSQL
- May use external Redis clusters
- May add load balancing and monitoring services
- Different resource constraints and restart policies

## Database Migrations

### Independent Migration Service
The deployment process includes an independent `migration` service to ensure:
1. **Migrations execute before application startup**
2. **Deployment stops on failure** to prevent applications from connecting to inconsistent databases
3. **Idempotency**: `prisma migrate deploy` can be safely executed repeatedly

### Manual Migration Execution
```bash
# Development environment
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env run --rm migration

# Production environment
docker compose -f compose/docker-compose.prod.yml --env-file compose/prod.compose.env run --rm migration
```

## Health Checks and Monitoring

### Built-in Health Checks
- **Backend**: `GET /v1/health` - Returns application, database, and Redis status
- **PostgreSQL**: Docker health check uses `pg_isready`
- **Redis**: Docker health check uses `redis-cli ping`

### Post-Deployment Verification
The deployment script automatically verifies:
1. Backend health endpoint returns `200 OK`
2. Swagger UI is accessible
3. Frontend homepage is accessible

### Manual Verification
```bash
# Check backend health
curl http://localhost:3001/v1/health | jq .

# Check service status
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env ps
```

## Troubleshooting

### Common Issues

#### 1. Missing Environment Variable Files
```
Missing booking-deploy/compose/dev.compose.env
Create it from booking-deploy/compose/dev.compose.env.example
```
**Solution**: Copy the template file and fill in actual values.

#### 2. Migration Failure
```
Error: P3009: migrate found failed migrations in the target database
```
**Solution**:
- Check database connection string
- Manually fix migrations: `docker compose exec postgres psql -U postgres -d booking_system`
- View migration logs

#### 3. Health Check Failure
The deployment script times out after 80 seconds.
**Solution**:
- Check service logs: `docker compose logs backend`
- Verify database connection: `docker compose exec backend npm run prisma:deploy`
- Check for port conflicts

#### 4. Image Pull Failure
```
Error response from daemon: pull access denied for cho-geer/booking-backend
```
**Solution**:
- Confirm the Docker Hub repository exists and is public
- Or update `compose/dev.compose.env` to use locally built images

### Viewing Logs
```bash
# View all service logs
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs

# View specific service logs
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs backend

# Tail logs in real-time
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs -f
```

## Upgrades and Rollbacks

### Version Upgrades
1. **Update image tags** in `compose/dev.compose.env` or `compose/prod.compose.env`
2. **Execute deployment script**
3. **Verify new version** functionality

### Rollback Operations
1. **Restore old image tags** in environment variable files
2. **Execute deployment script**
3. **Database forward compatibility**: Ensure old version applications can work with current database schema

### Zero-Downtime Deployment (Future Extension)
The current deployment strategy uses rolling restarts, future extensions could include:
- Blue-green deployment
- Canary releases
- Using Docker Swarm or Kubernetes

## Security Considerations

### 1. Sensitive Information Management
- **Never commit** `.env` files to version control
- Use secret management services (e.g., AWS Secrets Manager) for production secrets
- Regularly rotate JWT secrets and database passwords

### 2. Network Security
- Use dedicated networks for production environments
- Restrict external access to database and Redis
- Enable firewall rules

### 3. Image Security
- Regularly scan images for vulnerabilities
- Use minimal base images
- Update dependencies promptly

## Automated CI/CD (Future)

Current deployment is manually triggered, future integration with CI/CD pipelines:

### GitHub Actions Workflow
```yaml
name: Deploy to Production
on:
push:
tags:
- 'v*'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Deploy to Server
uses: appleboy/ssh-action@v0.1.5
with:
host: ${{ secrets.PROD_HOST }}
username: ${{ secrets.PROD_USER }}
key: ${{ secrets.PROD_SSH_KEY }}
script: |
cd /opt/booking-system/booking-deploy
./scripts/deploy-prod.sh
```

### Approval Process
Production deployments should include:
1. Code review
2. Automated test passing
3. Manual approval
4. Post-deployment verification

---

## Appendix

### A. Manual Deployment Command Reference
```bash
# Pull images
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env pull

# Execute migrations
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env run --rm migration

# Start services
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env up -d

# Stop services
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env down

# View status
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env ps
```

### B. Environment Variables Description
See comments in each `.env.example` file.

### C. Related Documentation
- [Docker Hub Image Build Configuration](../booking-backend/docs/docker-hub-setup.md)
- [Backend API Documentation](../booking-backend/docs/api-contract.md)
- [Frontend Development Guide](../booking-frontend/README.md)

---

*Last updated: 2026-04-08*
*Maintained by: DevOps Team*
Loading
Loading