260 lines
6.8 KiB
Markdown
260 lines
6.8 KiB
Markdown
# Getting Started
|
|
|
|
> **Note**: This guide assumes you are setting up the project on macOS or Linux. Windows users should use WSL2.
|
|
|
|
## Table of Contents
|
|
|
|
1. [Prerequisites](#prerequisites)
|
|
2. [Architecture Overview](#architecture-overview)
|
|
3. [Project Structure](#project-structure)
|
|
4. [Installation & Setup](#installation--setup)
|
|
5. [Development Workflow](#development-workflow)
|
|
6. [Common Commands](#common-commands)
|
|
7. [Troubleshooting](#troubleshooting)
|
|
|
|
## Prerequisites
|
|
|
|
Before starting, ensure you have the following installed:
|
|
|
|
* **Node.js**: v20.0.0 or higher (recommended v22+ or v25+)
|
|
```bash
|
|
node -v
|
|
# v25.2.1
|
|
```
|
|
* **PNPM**: v8.15.0 or higher (we use pnpm workspaces)
|
|
```bash
|
|
pnpm -v
|
|
# 8.15.0
|
|
```
|
|
* **Docker & Docker Compose**: v24.0.0 or higher for local infrastructure
|
|
```bash
|
|
docker -v
|
|
# Docker version 29.1.3, build f52814d
|
|
```
|
|
* **Git**: For version control
|
|
* **Neon Account**: Serverless PostgreSQL (https://neon.tech)
|
|
|
|
## Architecture Overview
|
|
|
|
GoodGo Platform uses a microservices architecture with a shared infrastructure layer.
|
|
|
|
```mermaid
|
|
graph TD
|
|
Client[Client Apps] --> Traefik[Traefik Gateway]
|
|
|
|
Traefik --> IAM[IAM Service]
|
|
Traefik --> Template[Template Service]
|
|
|
|
IAM --> DB[(Neon PostgreSQL)]
|
|
IAM --> Redis[(Redis Cache)]
|
|
IAM --> Kafka[Kafka Events]
|
|
|
|
style Client fill:#34495E,stroke:#2C3E50,color:#ECF0F1
|
|
style Traefik fill:#1A5490,stroke:#154360,color:#ECF0F1
|
|
style IAM fill:#1E8449,stroke:#186A3B,color:#ECF0F1
|
|
style Template fill:#BA6610,stroke:#935116,color:#ECF0F1
|
|
style DB fill:#6C3483,stroke:#512E5F,color:#ECF0F1
|
|
style Redis fill:#CA6F1E,stroke:#A04000,color:#ECF0F1
|
|
style Kafka fill:#21618C,stroke:#1B4F72,color:#ECF0F1
|
|
```
|
|
|
|
### Color Palette
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[" Primary<br/>#1A5490"] --> B[" Data/Cache<br/>#CA6F1E"]
|
|
B --> C[" Success<br/>#1E8449"]
|
|
C --> D[" Warning<br/>#BA6610"]
|
|
D --> E[" Error<br/>#922B21"]
|
|
E --> F[" Processing<br/>#6C3483"]
|
|
F --> G[" Info<br/>#21618C"]
|
|
G --> H[" Neutral<br/>#34495E"]
|
|
|
|
style A fill:#1A5490,stroke:#154360,color:#ECF0F1
|
|
style B fill:#CA6F1E,stroke:#A04000,color:#ECF0F1
|
|
style C fill:#1E8449,stroke:#186A3B,color:#ECF0F1
|
|
style D fill:#BA6610,stroke:#935116,color:#ECF0F1
|
|
style E fill:#922B21,stroke:#78281F,color:#ECF0F1
|
|
style F fill:#6C3483,stroke:#512E5F,color:#ECF0F1
|
|
style G fill:#21618C,stroke:#1B4F72,color:#ECF0F1
|
|
style H fill:#34495E,stroke:#2C3E50,color:#ECF0F1
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
The repository follows a monorepo structure:
|
|
|
|
```
|
|
Base/
|
|
apps/ # Frontend applications
|
|
app-admin/ # Admin dashboard application
|
|
app-client/ # Client mobile application (Flutter)
|
|
web-client/ # Next.js web application
|
|
web-docs/ # Documentation website (Next.js)
|
|
services/ # Backend microservices
|
|
iam-service/ # Authentication & Authorization service
|
|
_template/ # Template for new services
|
|
packages/ # Shared libraries
|
|
auth-sdk/ # Authentication SDK
|
|
config/ # Shared configuration utilities
|
|
http-client/ # Internal HTTP client
|
|
logger/ # Structured logging (@goodgo/logger)
|
|
tracing/ # OpenTelemetry tracing
|
|
types/ # Shared TypeScript types
|
|
infra/ # Infrastructure configuration
|
|
databases/ # Database setup scripts
|
|
docker/ # Docker configurations
|
|
observability/ # Prometheus, Grafana, Loki configs
|
|
secrets/ # Secrets management templates
|
|
traefik/ # API Gateway configuration
|
|
deployments/ # Deployment configurations
|
|
local/ # Docker Compose for development
|
|
staging/ # Staging environment configs
|
|
production/ # Production Kubernetes manifests
|
|
scripts/ # Automation scripts
|
|
build/ # Build scripts
|
|
db/ # Database utilities
|
|
deploy/ # Deployment scripts
|
|
dev/ # Development helpers
|
|
observability/ # Monitoring setup scripts
|
|
setup/ # Initial setup scripts
|
|
utils/ # Utility scripts
|
|
docs/ # Documentation
|
|
en/ # English documentation
|
|
vi/ # Vietnamese documentation
|
|
```
|
|
|
|
## Installation & Setup
|
|
|
|
### 1. Clone the Repository
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd Base
|
|
```
|
|
|
|
### 2. Configure Environment
|
|
|
|
Each service and the local infrastructure needs environment variables. We provide templates for these.
|
|
|
|
```bash
|
|
# Initialize project setup (copies .env.example to .env)
|
|
./scripts/setup/init-project.sh
|
|
```
|
|
|
|
### 3. Setup Neon Database
|
|
|
|
We use Neon (Serverless PostgreSQL) for all environments (Dev, Staging, Prod).
|
|
|
|
1. Create a project at [neon.tech](https://neon.tech).
|
|
2. Create a branch named `dev` (or use `main`).
|
|
3. Get the Connection String from the Neon dashboard.
|
|
4. Update `deployments/local/.env.local`:
|
|
|
|
```env
|
|
DATABASE_URL="postgres://user:pass@ep-xyz.region.neon.tech/neondb"
|
|
```
|
|
|
|
### 4. Start Infrastructure
|
|
|
|
Start the supporting infrastructure (Redis, Traefik, Observability) using Docker Compose.
|
|
|
|
```bash
|
|
cd deployments/local
|
|
docker-compose up -d
|
|
# Expected output: Containers for traefik, redis, kafka created
|
|
```
|
|
|
|
### 5. Install Dependencies
|
|
|
|
```bash
|
|
pnpm install
|
|
```
|
|
|
|
### 6. Setup Database Schema
|
|
|
|
Push the Prisma schema to your Neon database.
|
|
|
|
```bash
|
|
# Run migrations for IAM service
|
|
pnpm --filter @goodgo/iam-service prisma migrate dev
|
|
```
|
|
|
|
### 7. Start Services
|
|
|
|
Start all backend services in development mode.
|
|
|
|
```bash
|
|
pnpm dev
|
|
# or start specific service
|
|
pnpm --filter @goodgo/iam-service dev
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Creating a New Service
|
|
|
|
1. Copy the template:
|
|
```bash
|
|
cp -r services/_template services/my-new-service
|
|
```
|
|
2. Update `package.json` name.
|
|
3. Add logic in `src/modules/`.
|
|
4. Register in `deployments/local/docker-compose.yml`.
|
|
|
|
### Making Changes
|
|
|
|
1. Create a new branch: `feature/my-feature`.
|
|
2. Implement changes.
|
|
3. Run tests: `pnpm test`.
|
|
4. Commit with conventional commits: `feat(iam): add login endpoint`.
|
|
|
|
## Common Commands
|
|
|
|
| Command | Description |
|
|
| :--- | :--- |
|
|
| `pnpm install` | Install all dependencies |
|
|
| `pnpm dev` | Start all services in dev mode |
|
|
| `pnpm build` | Build all packages and services |
|
|
| `pnpm test` | Run unit tests |
|
|
| `pnpm lint` | Lint code |
|
|
| `docker-compose up -d` | Start local infra |
|
|
| `docker-compose down` | Stop local infra |
|
|
|
|
## Troubleshooting
|
|
|
|
### Port Conflicts
|
|
|
|
**Error**: `Bind for 0.0.0.0:80 failed: port is already allocated`
|
|
|
|
**Solution**: Check what's using port 80 (likely another web server) and stop it, or change Traefik ports in `docker-compose.yml`.
|
|
|
|
```bash
|
|
lsof -i :80
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### Database Connection Failed
|
|
|
|
**Error**: `P1001: Can't reach database server`
|
|
|
|
**Solution**:
|
|
1. Check your internet connection (Neon is cloud-based).
|
|
2. Verify `DATABASE_URL` in `deployments/local/.env.local`.
|
|
3. Ensure your IP is allowed in Neon dashboard settings.
|
|
|
|
### Service Not Found in Gateway
|
|
|
|
**Error**: `404 Not Found` from api.localhost
|
|
|
|
**Solution**:
|
|
1. Check if service is running.
|
|
2. Check Traefik dashboard at http://localhost:8080.
|
|
3. Verify `PathPrefix` labels in `docker-compose.yml`.
|
|
|
|
## Next Steps
|
|
|
|
* [Development Guide](development.md) - Deep dive into coding standards
|
|
* [API Documentation](../api/openapi/) - Explore the APIs
|
|
* [Architecture](../architecture/system-design.md) - Understand the system design
|