215 lines
5.5 KiB
Markdown
215 lines
5.5 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
|
|
```bash
|
|
node -v
|
|
# v20.10.0
|
|
```
|
|
* **PNPM**: v8.0.0 or higher (we use pnpm workspaces)
|
|
```bash
|
|
pnpm -v
|
|
# 8.12.0
|
|
```
|
|
* **Docker & Docker Compose**: For local infrastructure
|
|
```bash
|
|
docker -v
|
|
# Docker version 24.0.0
|
|
```
|
|
* **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 Traefik fill:#e1f5ff
|
|
style DB fill:#f0e1ff
|
|
style Redis fill:#fff4e1
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
The repository follows a monorepo structure:
|
|
|
|
```
|
|
Base/
|
|
├── apps/ # Frontend applications
|
|
│ ├── web-client/ # Next.js web application
|
|
│ └── mobile-client/ # Flutter mobile application
|
|
├── services/ # Backend microservices
|
|
│ ├── iam-service/ # Authentication & Authorization
|
|
│ └── _template/ # Template for new services
|
|
├── packages/ # Shared libraries
|
|
│ ├── logger/ # Structured logging
|
|
│ ├── types/ # Shared TypeScript types
|
|
│ └── http-client/ # Internal HTTP client
|
|
├── infra/ # Infrastructure configuration
|
|
│ ├── traefik/ # API Gateway config
|
|
│ └── databases/ # Database setup scripts
|
|
├── deployments/ # Deployment configurations
|
|
│ ├── local/ # Docker Compose for dev
|
|
│ └── k8s/ # Kubernetes manifests
|
|
└── docs/ # 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
|