bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add new infra architecture 11

Browse Source
This commit is contained in:
Urtzi Alfaro
2026-01-20 22:05:10 +01:00
parent 0217ad83be
commit 2512de4173
42 changed files with 1056 additions and 874 deletions
Download Patch File Download Diff File Expand all files Collapse all files

261
docs/PILOT_LAUNCH_GUIDE.md
View File

@@ -2,29 +2,35 @@
**Complete guide for deploying to production for a 10-tenant pilot program**
**Last Updated:** 2026-01-11
**Last Updated:** 2026-01-20
**Target Environment:** clouding.io VPS with MicroK8s
**Estimated Cost:** €41-81/month
**Time to Deploy:** 3-5 hours (first time, including fixes)
**Status:** ⚠️ REQUIRES PRE-DEPLOYMENT FIXES - See [Production VPS Deployment Fixes](../PRODUCTION_VPS_DEPLOYMENT_FIXES.md)
**Version:** 3.0
---
## Table of Contents
1. [Executive Summary](#executive-summary)
2. [⚠️ CRITICAL: Pre-Deployment Fixes](#critical-pre-deployment-fixes)
3. [Pre-Launch Checklist](#pre-launch-checklist)
4. [VPS Provisioning](#vps-provisioning)
5. [Infrastructure Setup](#infrastructure-setup)
6. [Domain & DNS Configuration](#domain--dns-configuration)
7. [TLS/SSL Certificates](#tlsssl-certificates)
8. [Email & Communication Setup](#email--communication-setup)
9. [Kubernetes Deployment](#kubernetes-deployment)
10. [Configuration & Secrets](#configuration--secrets)
11. [Database Migrations](#database-migrations)
12. [Verification & Testing](#verification--testing)
13. [Post-Deployment](#post-deployment)
2. [Infrastructure Architecture Overview](#infrastructure-architecture-overview)
3. [⚠️ CRITICAL: Pre-Deployment Fixes](#critical-pre-deployment-fixes)
4. [Pre-Launch Checklist](#pre-launch-checklist)
5. [VPS Provisioning](#vps-provisioning)
6. [Infrastructure Setup](#infrastructure-setup)
7. [Domain & DNS Configuration](#domain--dns-configuration)
8. [TLS/SSL Certificates](#tlsssl-certificates)
9. [Email & Communication Setup](#email--communication-setup)
10. [Kubernetes Deployment](#kubernetes-deployment)
11. [Configuration & Secrets](#configuration--secrets)
12. [Database Migrations](#database-migrations)
13. [CI/CD Infrastructure Deployment](#cicd-infrastructure-deployment)
14. [Mailu Email Server Deployment](#mailu-email-server-deployment)
15. [Nominatim Geocoding Service](#nominatim-geocoding-service)
16. [SigNoz Monitoring Deployment](#signoz-monitoring-deployment)
17. [Verification & Testing](#verification--testing)
18. [Post-Deployment](#post-deployment)
---
@@ -64,6 +70,107 @@ A complete multi-tenant SaaS platform with:
---
## Infrastructure Architecture Overview
### Component Layers
The Bakery-IA platform is organized into distinct infrastructure layers, each with specific deployment dependencies.
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ LAYER 6: APPLICATION │
│ Frontend │ Gateway │ 18 Microservices │ CronJobs & Workers │
├─────────────────────────────────────────────────────────────────────────────┤
│ LAYER 5: MONITORING │
│ SigNoz (Unified Observability) │ AlertManager │ OTel Collector │
├─────────────────────────────────────────────────────────────────────────────┤
│ LAYER 4: PLATFORM SERVICES (Optional) │
│ Mailu (Email) │ Nominatim (Geocoding) │ CI/CD (Tekton, Flux, Gitea) │
├─────────────────────────────────────────────────────────────────────────────┤
│ LAYER 3: DATA & STORAGE │
│ PostgreSQL (18 DBs) │ Redis │ RabbitMQ │ MinIO │
├─────────────────────────────────────────────────────────────────────────────┤
│ LAYER 2: NETWORK & SECURITY │
│ Unbound DNS │ CoreDNS │ Ingress Controller │ Cert-Manager │ TLS │
├─────────────────────────────────────────────────────────────────────────────┤
│ LAYER 1: FOUNDATION │
│ Namespaces │ Storage Classes │ RBAC │ ConfigMaps │ Secrets │
├─────────────────────────────────────────────────────────────────────────────┤
│ LAYER 0: KUBERNETES CLUSTER │
│ MicroK8s (Production) │ Kind (Local Dev) │ EKS (AWS Alternative) │
└─────────────────────────────────────────────────────────────────────────────┘
```
### Deployment Order & Dependencies
Components must be deployed in a specific order due to dependencies:
```
1. Namespaces (bakery-ia, tekton-pipelines, flux-system)
↓
2. Cert-Manager & ClusterIssuers
↓
3. TLS Certificates (internal + ingress)
↓
4. Unbound DNS Resolver (required for Mailu DNSSEC)
↓
5. CoreDNS Configuration (forward to Unbound)
↓
6. Ingress Controller & Resources
↓
7. Data Layer: PostgreSQL, Redis, RabbitMQ, MinIO
↓
8. Database Migrations
↓
9. Application Services (18 microservices)
↓
10. Gateway & Frontend
↓
11. (Optional) CI/CD: Gitea → Tekton → Flux
↓
12. (Optional) Mailu Email Server
↓
13. (Optional) Nominatim Geocoding
↓
14. (Optional) SigNoz Monitoring
```
### Infrastructure Components Summary
| Component | Purpose | Required | Namespace |
|-----------|---------|----------|-----------|
| **MicroK8s** | Kubernetes cluster | Yes | - |
| **Cert-Manager** | TLS certificate management | Yes | cert-manager |
| **Ingress-Nginx** | External traffic routing | Yes | ingress |
| **PostgreSQL** | 18 service databases | Yes | bakery-ia |
| **Redis** | Caching & sessions | Yes | bakery-ia |
| **RabbitMQ** | Message broker | Yes | bakery-ia |
| **MinIO** | Object storage (ML models) | Yes | bakery-ia |
| **Unbound DNS** | DNSSEC resolver | For Mailu | bakery-ia |
| **Mailu** | Self-hosted email server | Optional | bakery-ia |
| **Nominatim** | Geocoding service | Optional | bakery-ia |
| **Gitea** | Git server + container registry | Optional | gitea |
| **Tekton** | CI/CD pipelines | Optional | tekton-pipelines |
| **Flux CD** | GitOps deployment | Optional | flux-system |
| **SigNoz** | Unified observability | Recommended | bakery-ia |
### Quick Reference: What to Deploy
**Minimal Production Setup:**
- Kubernetes cluster + addons
- Core infrastructure (databases, cache, broker)
- Application services
- External email (Zoho/Gmail)
**Full Production Setup (Recommended):**
- Everything above, plus:
- Mailu (self-hosted email)
- SigNoz (monitoring)
- CI/CD (Gitea + Tekton + Flux)
- Nominatim (if geocoding needed)
---
## ⚠️ CRITICAL: Pre-Deployment Configuration
**READ THIS FIRST:** The Kubernetes configuration requires updates for secure production deployment.
@@ -400,7 +507,7 @@ microk8s status --wait-ready
# Enable core addons
microk8s enable dns # DNS resolution within cluster
microk8s enable hostpath-storage # Provides microk8s-hostpath storage class
microk8s enable ingress # Nginx ingress controller
microk8s enable ingress # Nginx ingress controller (uses class "public")
microk8s enable cert-manager # Let's Encrypt SSL certificates
microk8s enable metrics-server # For HPA autoscaling
microk8s enable rbac # Role-based access control
@@ -417,13 +524,26 @@ kubectl get storageclass
# Should show: microk8s-hostpath (default)
kubectl get pods -A
# Should show pods in: kube-system, ingress-nginx, cert-manager namespaces
# Should show pods in: kube-system, ingress, cert-manager namespaces
# Verify ingress controller is running
kubectl get pods -n ingress
# Should show: nginx-ingress-microk8s-controller-xxx Running
# Verify cert-manager is running
kubectl get pods -n cert-manager
# Should show: cert-manager-xxx, cert-manager-webhook-xxx, cert-manager-cainjector-xxx
# Verify metrics-server is working
kubectl top nodes
# Should return CPU/Memory metrics
```
**Important - MicroK8s Ingress Class:**
- MicroK8s ingress addon uses class name `public` (NOT `nginx`)
- The ClusterIssuers in this repo are already configured with `class: public`
- If you see cert-manager challenges failing, verify the ingress class matches
**Optional but Recommended:**
```bash
# Enable Prometheus for additional monitoring (optional)
@@ -472,23 +592,34 @@ kubectl apply -f https://storage.googleapis.com/tekton-releases/triggers/latest/
# flux install --namespace=flux-system --network-policy=false
```
### Step 3: Configure Firewall
### Step 4: Configure Firewall
**CRITICAL:** Ports 80 and 443 must be open for Let's Encrypt HTTP-01 challenges to work.
```bash
# Allow necessary ports
ufw allow 22/tcp # SSH
ufw allow 80/tcp # HTTP
ufw allow 443/tcp # HTTPS
ufw allow 16443/tcp # Kubernetes API (optional)
ufw allow 80/tcp # HTTP - REQUIRED for Let's Encrypt HTTP-01 challenge
ufw allow 443/tcp # HTTPS - For your application traffic
ufw allow 16443/tcp # Kubernetes API (optional, for remote kubectl access)
# Enable firewall
ufw enable
# Check status
ufw status verbose
# Expected output should include:
# 80/tcp ALLOW Anywhere
# 443/tcp ALLOW Anywhere
```
### Step 4: Create Namespace
**Also check clouding.io firewall:**
- Log in to clouding.io dashboard
- Go to your VPS → Firewall settings
- Ensure ports 80 and 443 are allowed from anywhere (0.0.0.0/0)
### Step 5: Create Namespace
```bash
# Create bakery-ia namespace
@@ -502,14 +633,39 @@ kubectl get namespaces
## Domain & DNS Configuration
### Step 1: Register Domain
### Step 1: Register Domain at Namecheap
1. Go to Namecheap or Cloudflare Registrar
2. Search for your desired domain
1. Go to [Namecheap](https://www.namecheap.com)
2. Search for your desired domain (e.g., `bakewise.ia`)
3. Complete purchase (~€10-15/year)
4. Save domain credentials
### Step 2: Configure Cloudflare DNS (Recommended)
### Step 2: Configure DNS at Namecheap
1. **Access DNS settings:**
```
1. Log in to Namecheap
2. Go to Domain List → Manage → Advanced DNS
```
2. **Add DNS records pointing to your VPS:**
```
Type Host Value TTL
A @ YOUR_VPS_IP Automatic
A * YOUR_VPS_IP Automatic
```
This points both `bakewise.ia` and all subdomains (`*.bakewise.ia`) to your VPS.
3. **Test DNS propagation:**
```bash
# Wait 5-10 minutes, then test
nslookup bakewise.ia
nslookup api.bakewise.ia
nslookup mail.bakewise.ia
```
### Step 3 (Optional): Configure Cloudflare DNS
1. **Add site to Cloudflare:**
```
@@ -605,30 +761,36 @@ kubectl get secrets -n bakery-ia | grep tls
### Step 3: Configure Let's Encrypt (External SSL)
cert-manager is already enabled. Configure the ClusterIssuer:
cert-manager is already enabled via `microk8s enable cert-manager`. The ClusterIssuer is pre-configured in the repository.
**Important:** MicroK8s ingress addon uses ingress class `public` (not `nginx`). This is already configured in:
- `infrastructure/platform/cert-manager/cluster-issuer-production.yaml`
- `infrastructure/platform/cert-manager/cluster-issuer-staging.yaml`
```bash
# On VPS, create ClusterIssuer
cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-production
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: admin@yourdomain.com # CHANGE THIS
privateKeySecretRef:
name: letsencrypt-production
solvers:
- http01:
ingress:
class: public
EOF
# On VPS, apply the pre-configured ClusterIssuers
kubectl apply -k infrastructure/platform/cert-manager/
# Verify ClusterIssuer is ready
# Verify ClusterIssuers are ready
kubectl get clusterissuer
kubectl describe clusterissuer letsencrypt-production
# Expected output:
# NAME READY AGE
# letsencrypt-production True 1m
# letsencrypt-staging True 1m
```
**Configuration details (already set):**
- **Email:** `admin@bakewise.ai` (receives Let's Encrypt expiry notifications)
- **Ingress class:** `public` (MicroK8s default)
- **Challenge type:** HTTP-01 (requires port 80 open)
**If you need to customize the email**, edit before applying:
```bash
# Edit the production issuer
nano infrastructure/platform/cert-manager/cluster-issuer-production.yaml
# Change: email: admin@bakewise.ai → email: your-email@yourdomain.com
```
---
@@ -2230,12 +2392,19 @@ kubectl scale deployment monitoring -n bakery-ia --replicas=0
---
**Document Version:** 2.0
**Last Updated:** 2026-01-11
**Document Version:** 2.1
**Last Updated:** 2026-01-20
**Maintained By:** DevOps Team
**Changes in v2.1:**
- Updated DNS configuration for Namecheap (primary) with Cloudflare as optional
- Clarified MicroK8s ingress class is `public` (not `nginx`)
- Updated Let's Encrypt ClusterIssuer documentation to reference pre-configured files
- Added firewall requirements for clouding.io VPS
- Emphasized port 80/443 requirements for HTTP-01 challenges
**Changes in v2.0:**
- Added critical pre-deployment fixes section
- Updated infrastructure setup for k3s instead of MicroK8s
- Updated infrastructure setup for MicroK8s
- Added required component installation (nginx-ingress, metrics-server, etc.)
- Updated configuration steps with domain replacement
- Added Docker registry secret creation