Complete documentation for future sessions
- CLAUDE.md for AI agents to understand the codebase - GITEA-GUIDE.md centralizes all Gitea operations (API, Registry, Auth) - DEVELOPMENT-WORKFLOW.md explains complete dev process - ROADMAP.md, NEXT-SESSION.md for planning - QUICK-REFERENCE.md, TROUBLESHOOTING.md for daily use - 40+ detailed docs in /docs folder - Backend as submodule from Gitea Everything documented for autonomous operation. Co-Authored-By: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hector Ros
313
docs/CONTAINER-REGISTRY.md
Normal file
313
docs/CONTAINER-REGISTRY.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# Gitea Container Registry - Guía de Uso
|
||||
|
||||
El Container Registry de Gitea está habilitado y listo para usar.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Credenciales
|
||||
|
||||
**Registry URL**: `git.fuq.tv`
|
||||
**Usuario**: `admin`
|
||||
**Token**: `7401126cfb56ab2aebba17755bdc968c20768c27`
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Uso con Docker
|
||||
|
||||
### Login
|
||||
|
||||
```bash
|
||||
docker login git.fuq.tv -u admin -p 7401126cfb56ab2aebba17755bdc968c20768c27
|
||||
|
||||
# O de forma segura
|
||||
echo "7401126cfb56ab2aebba17755bdc968c20768c27" | docker login git.fuq.tv -u admin --password-stdin
|
||||
```
|
||||
|
||||
### Formato de Imágenes
|
||||
|
||||
```
|
||||
git.fuq.tv/<owner>/<package-name>:<tag>
|
||||
```
|
||||
|
||||
Ejemplos:
|
||||
- `git.fuq.tv/admin/aiworker-backend:v1.0.0`
|
||||
- `git.fuq.tv/admin/aiworker-frontend:latest`
|
||||
- `git.fuq.tv/aiworker/my-app:v2.1.0`
|
||||
|
||||
### Build y Push
|
||||
|
||||
```bash
|
||||
# 1. Build imagen
|
||||
docker build -t git.fuq.tv/admin/aiworker-backend:v1.0.0 .
|
||||
|
||||
# 2. Push al registry
|
||||
docker push git.fuq.tv/admin/aiworker-backend:v1.0.0
|
||||
|
||||
# 3. También tag como latest
|
||||
docker tag git.fuq.tv/admin/aiworker-backend:v1.0.0 git.fuq.tv/admin/aiworker-backend:latest
|
||||
docker push git.fuq.tv/admin/aiworker-backend:latest
|
||||
```
|
||||
|
||||
### Pull
|
||||
|
||||
```bash
|
||||
docker pull git.fuq.tv/admin/aiworker-backend:v1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ☸️ Uso en Kubernetes
|
||||
|
||||
### Opción 1: Usar ImagePullSecrets (Recomendado)
|
||||
|
||||
El secret ya está creado en los namespaces `control-plane` y `agents`:
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: aiworker-backend
|
||||
namespace: control-plane
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
imagePullSecrets:
|
||||
- name: gitea-registry
|
||||
containers:
|
||||
- name: backend
|
||||
image: git.fuq.tv/admin/aiworker-backend:v1.0.0
|
||||
```
|
||||
|
||||
### Opción 2: Service Account con ImagePullSecrets
|
||||
|
||||
```bash
|
||||
# Patch del service account default
|
||||
kubectl patch serviceaccount default -n control-plane \
|
||||
-p '{"imagePullSecrets": [{"name": "gitea-registry"}]}'
|
||||
|
||||
# Ahora todos los pods usarán automáticamente el secret
|
||||
```
|
||||
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: aiworker-backend
|
||||
namespace: control-plane
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
# No need to specify imagePullSecrets, uses SA default
|
||||
containers:
|
||||
- name: backend
|
||||
image: git.fuq.tv/admin/aiworker-backend:v1.0.0
|
||||
```
|
||||
|
||||
### Crear Secret en Otros Namespaces
|
||||
|
||||
```bash
|
||||
kubectl create secret docker-registry gitea-registry \
|
||||
--docker-server=git.fuq.tv \
|
||||
--docker-username=admin \
|
||||
--docker-password=7401126cfb56ab2aebba17755bdc968c20768c27 \
|
||||
-n <namespace>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Ver Packages en Gitea UI
|
||||
|
||||
1. Ve a https://git.fuq.tv
|
||||
2. Login (admin / admin123)
|
||||
3. Click en tu perfil → **Packages**
|
||||
4. Verás todas las imágenes subidas
|
||||
|
||||
---
|
||||
|
||||
## 🚀 CI/CD con Gitea Actions
|
||||
|
||||
### Ejemplo .gitea/workflows/build.yml
|
||||
|
||||
```yaml
|
||||
name: Build and Push Docker Image
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
tags:
|
||||
- 'v*'
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Login to Gitea Registry
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
registry: git.fuq.tv
|
||||
username: admin
|
||||
password: ${{ secrets.REGISTRY_TOKEN }}
|
||||
|
||||
- name: Extract metadata
|
||||
id: meta
|
||||
uses: docker/metadata-action@v5
|
||||
with:
|
||||
images: git.fuq.tv/admin/aiworker-backend
|
||||
tags: |
|
||||
type=ref,event=branch
|
||||
type=semver,pattern={{version}}
|
||||
type=semver,pattern={{major}}.{{minor}}
|
||||
type=sha,prefix={{branch}}-
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: ${{ steps.meta.outputs.tags }}
|
||||
labels: ${{ steps.meta.outputs.labels }}
|
||||
cache-from: type=registry,ref=git.fuq.tv/admin/aiworker-backend:buildcache
|
||||
cache-to: type=registry,ref=git.fuq.tv/admin/aiworker-backend:buildcache,mode=max
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔨 Build Manual (sin Docker daemon)
|
||||
|
||||
Si no tienes Docker corriendo localmente, puedes usar **buildah** o **podman**:
|
||||
|
||||
```bash
|
||||
# Con buildah
|
||||
buildah bud -t git.fuq.tv/admin/myapp:v1.0.0 .
|
||||
buildah push git.fuq.tv/admin/myapp:v1.0.0
|
||||
|
||||
# Con podman
|
||||
podman build -t git.fuq.tv/admin/myapp:v1.0.0 .
|
||||
podman push git.fuq.tv/admin/myapp:v1.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Ejemplo Completo: Backend de AiWorker
|
||||
|
||||
### Dockerfile
|
||||
```dockerfile
|
||||
FROM oven/bun:1.3.6-alpine
|
||||
WORKDIR /app
|
||||
|
||||
# Dependencies
|
||||
COPY package.json bun.lockb ./
|
||||
RUN bun install --production
|
||||
|
||||
# Source
|
||||
COPY src ./src
|
||||
COPY drizzle ./drizzle
|
||||
|
||||
# Run
|
||||
EXPOSE 3000
|
||||
CMD ["bun", "src/index.ts"]
|
||||
```
|
||||
|
||||
### Build y Push
|
||||
```bash
|
||||
# Build
|
||||
docker build -t git.fuq.tv/admin/aiworker-backend:v1.0.0 .
|
||||
|
||||
# Push
|
||||
docker push git.fuq.tv/admin/aiworker-backend:v1.0.0
|
||||
|
||||
# Tag latest
|
||||
docker tag git.fuq.tv/admin/aiworker-backend:v1.0.0 git.fuq.tv/admin/aiworker-backend:latest
|
||||
docker push git.fuq.tv/admin/aiworker-backend:latest
|
||||
```
|
||||
|
||||
### Deploy en K8s
|
||||
```yaml
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: backend
|
||||
namespace: control-plane
|
||||
spec:
|
||||
replicas: 2
|
||||
selector:
|
||||
matchLabels:
|
||||
app: backend
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app: backend
|
||||
spec:
|
||||
imagePullSecrets:
|
||||
- name: gitea-registry
|
||||
containers:
|
||||
- name: backend
|
||||
image: git.fuq.tv/admin/aiworker-backend:v1.0.0
|
||||
ports:
|
||||
- containerPort: 3000
|
||||
env:
|
||||
- name: DB_HOST
|
||||
value: mariadb.control-plane.svc.cluster.local
|
||||
- name: REDIS_HOST
|
||||
value: redis.control-plane.svc.cluster.local
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Actualizar Deployment con Nueva Imagen
|
||||
|
||||
```bash
|
||||
# Opción 1: Set image
|
||||
kubectl set image deployment/backend backend=git.fuq.tv/admin/aiworker-backend:v1.1.0 -n control-plane
|
||||
|
||||
# Opción 2: Rollout restart (usa :latest)
|
||||
kubectl rollout restart deployment/backend -n control-plane
|
||||
|
||||
# Ver progreso
|
||||
kubectl rollout status deployment/backend -n control-plane
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🗑️ Cleanup de Imágenes Viejas
|
||||
|
||||
Desde la UI de Gitea:
|
||||
1. Packages → Select package
|
||||
2. Versions → Delete old versions
|
||||
|
||||
O vía API:
|
||||
```bash
|
||||
curl -X DELETE "https://git.fuq.tv/api/v1/packages/admin/container/aiworker-backend/v1.0.0" \
|
||||
-H "Authorization: token 7401126cfb56ab2aebba17755bdc968c20768c27"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Ventajas del Registry en Gitea
|
||||
|
||||
✅ **Integrado** - Mismo sistema que Git
|
||||
✅ **Autenticación única** - Mismos usuarios
|
||||
✅ **Sin costos extra** - Ya está incluido
|
||||
✅ **Storage HA** - Longhorn con 3 réplicas
|
||||
✅ **TLS automático** - Cert-Manager
|
||||
✅ **Privado** - No público como Docker Hub
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Resumen
|
||||
|
||||
**Registry**: `git.fuq.tv`
|
||||
**Login**: `admin / 7401126cfb56ab2aebba17755bdc968c20768c27`
|
||||
**Formato**: `git.fuq.tv/<owner>/<image>:<tag>`
|
||||
**K8s Secret**: `gitea-registry` (en control-plane y agents)
|
||||
|
||||
**Próximos pasos:**
|
||||
1. Crear Dockerfile para backend
|
||||
2. Build imagen
|
||||
3. Push a `git.fuq.tv/admin/aiworker-backend:v1.0.0`
|
||||
4. Deploy en K8s
|
||||
Reference in New Issue
Block a user