# type-for-learning

**Repository Path**: luyanfei/type-for-learning

## Basic Information

- **Project Name**: type-for-learning
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-23
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).

## Getting Started

First, run the development server:

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.

This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.

## Learn More

To learn more about Next.js, take a look at the following resources:

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.

You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!

## Deploy on Vercel

The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.

Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

---

## Kubernetes Deployment

This application can be deployed to a self-hosted Kubernetes cluster using Gateway API for ingress routing.

### Prerequisites

- **Kubernetes Cluster**: Self-hosted K8s cluster (v1.24+) with kubectl configured
- **Gateway API**: Gateway API CRDs installed (v1.0.0+)
  ```bash
  kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.0.0/standard-install.yaml
  ```
- **Container Registry**: Access to a Docker registry (Docker Hub, GHCR, or private registry)
- **Domain Name**: A domain name with DNS configured to point to your Gateway IP
- **MongoDB**: MongoDB 7+ (deployed as StatefulSet with replica set)

### Quick Start

#### 1. Build and Push Container Image

```bash
# Build the image
docker build -t your-registry/type-for-learning:latest .

# Tag for your registry
docker tag type-for-learning:latest your-registry/type-for-learning:latest

# Push to registry
docker push your-registry/type-for-learning:latest
```

#### 2. Create Kubernetes Secrets

```bash
# Create MongoDB credentials secret
kubectl create secret generic mongodb-credentials \
  --from-literal=username=mongoadmin \
  --from-literal=password=your-strong-password

# Create application secret (MongoDB connection string)
kubectl create secret generic type-for-learning-secret \
  --from-literal=mongodb-uri="mongodb://mongoadmin:your-strong-password@mongodb-0.mongodb-headless.default.svc.cluster.local:27017,type-for-learning-1.mongodb-headless.default.svc.cluster.local:27017,type-for-learning-2.mongodb-headless.default.svc.cluster.local:27017/type-for-learning?replicaSet=rs0&authSource=admin"
```

#### 3. Update Configuration

Edit `k8s/nextjs-app/deployment.yaml`:
- Update `image` to your registry path
- Update `host` in `k8s/gateway/httproute.yaml` to your domain

#### 4. Deploy to Kubernetes

```bash
# Deploy MongoDB StatefulSet (3-node replica set)
kubectl apply -f k8s/mongodb/

# Wait for MongoDB pods to be ready
kubectl wait --for=condition=ready pod -l app=mongodb --timeout=300s

# Deploy the Next.js application
kubectl apply -f k8s/nextjs-app/

# Deploy Gateway API resources
kubectl apply -f k8s/gateway/
```

#### 5. Verify Deployment

```bash
# Check all pods are running
kubectl get pods

# Check Gateway status
kubectl get gateway

# Check HTTPRoute status
kubectl get httproute

# Get Gateway external IP
kubectl get gateway type-for-learning-gateway -o jsonpath='{.status.addresses[0].value}'
```

### Architecture

```
Internet
    |
    v
Gateway API (type-for-learning-gateway)
    |
    v
HTTPRoute (type-for-learning-httproute)
    |
    +---> Next.js App Deployment (2-5 pods, HPA enabled)
    |        - Environment variables from ConfigMap/Secret
    |        - Probes: Liveness (health), Readiness (port 3000)
    |        - Resources: 1-2 CPU, 512Mi-2Gi memory
    |
    +---> MongoDB StatefulSet (3 nodes, replica set)
             - Persistent volumes (10Gi each)
             - Internal service cluster communication
             - Automated replica set initialization
```

**Components:**
- **Next.js App**: 2-5 pods managed by HorizontalPodAutoscaler (target 70% CPU)
- **MongoDB**: 3-node replica set StatefulSet for high availability
- **Gateway API**: Gateway + HTTPRoute for ingress (not Ingress)
- **Services**: ClusterIP services for internal communication
- **Storage**: PersistentVolumeClaim for each MongoDB pod

### Backup & Restore

#### Backup MongoDB Database

```bash
# Port-forward to MongoDB
kubectl port-forward mongodb-0 27017:27017

# Create backup
mongodump --uri="mongodb://mongoadmin:your-password@localhost:27017/type-for-learning?authSource=admin" --out=/backups/$(date +%Y%m%d)

# Clean up port-forward
# Ctrl+C to stop port-forward
```

#### Restore MongoDB Database

```bash
# Port-forward to MongoDB
kubectl port-forward mongodb-0 27017:27017

# Restore from backup
mongorestore --uri="mongodb://mongoadmin:your-password@localhost:27017?authSource=admin" /path/to/backup

# Clean up port-forward
# Ctrl+C to stop port-forward
```

#### Application State

Application state is stored in MongoDB. No additional backup needed for the Next.js application.

### Monitoring & Logs

```bash
# View application logs
kubectl logs -l app=type-for-learning -f

# View MongoDB logs
kubectl logs -l app=mongodb -f

# Check pod resource usage
kubectl top pods
```

### Scaling

The Next.js application automatically scales based on CPU usage (70% target). To manually adjust:

```bash
# Edit HPA min/max replicas
kubectl edit hpa type-for-learning-hpa

# Or scale manually (HPA will take over after)
kubectl scale deployment type-for-learning --replicas=5
```

### Troubleshooting

**Pods not starting:**
```bash
kubectl describe pod <pod-name>
kubectl logs <pod-name>
```

**Gateway not routing:**
```bash
kubectl get gateway
kubectl describe gateway type-for-learning-gateway
kubectl get httproute
```

**MongoDB connection issues:**
```bash
kubectl exec -it mongodb-0 -- mongosh --eval "rs.status()"
kubectl logs mongodb-0
```

### Documentation

- [Kubernetes Design](k8s/DESIGN.md) - Architecture and design decisions
- [Implementation Plan](k8s/IMPLEMENTATION.md) - Detailed implementation steps