docs: add comprehensive project documentation

- README.md: project overview, server status, quick start guide, architecture diagram, tech stack, and content inventory - docs/architecture.md: technical architecture, service diagram, component details, and design decisions - docs/game-servers.md: setup and operation guide for OpenFusion, MapleStory 2, and Minecraft FTB Infinity Evolved - docs/cms-content.md: Strapi content model, i18n strategy, documentary structure, and API endpoints - docs/deployment.md: local dev, production deploy, CI/CD, SSL setup, backup procedures, and monitoring Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 12:23:53 +00:00
parent aea2283d8f
commit e4404b209d
5 changed files with 931 additions and 0 deletions
--- a/docs/game-servers.md
+++ b/docs/game-servers.md
@@ -0,0 +1,233 @@
+# Servidores de Juegos
+
+Guia de setup, operacion y troubleshooting de cada servidor de juegos.
+
+## OpenFusion (FusionFall)
+
+### Resumen
+| Dato | Valor |
+|------|-------|
+| Emulador | [OpenFusion](https://github.com/OpenFusionProject/OpenFusion) |
+| Lenguaje | C++ |
+| Puerto | 23000 (login), 23001 (shard) |
+| Base de datos | SQLite (embebida) |
+| RAM | ~254 MB |
+
+### Archivos
+```
+servers/openfusion/
+├── Dockerfile              # Ubuntu 24.04, copia binario + config
+├── docker-entrypoint.sh    # Genera config.ini desde env vars
+├── config.ini              # Configuracion del servidor
+├── fusion                  # Binario compilado (no en git)
+├── sql/                    # Migraciones SQLite
+└── tdata/                  # Datos del juego (NPCs, mobs, drops)
+```
+
+### Configuracion
+Variables de entorno en `docker-compose.dev.yml`:
+- `OPENFUSION_SHARD_IP`: IP publica del servidor (default: 192.168.10.234)
+- `OPENFUSION_MOTD`: Mensaje del dia
+
+### Conexion de cliente
+1. Descargar el cliente FusionFall
+2. Usar el launcher de OpenFusion apuntando a `192.168.10.234:23000`
+
+### Troubleshooting
+- **"Connection refused"**: Verificar que el contenedor esta corriendo y los puertos estan mapeados
+- **Datos de juego**: Los archivos `tdata/` contienen los NPCs, mobs y drops. Si faltan, el mundo estara vacio
+
+---
+
+## MapleStory 2
+
+### Resumen
+| Dato | Valor |
+|------|-------|
+| Emulador | [Maple2](https://github.com/MS2Community/Maple2) |
+| Lenguaje | C# / .NET 8 |
+| Puertos | 20001 (login), 21001 (world), 20002/21002 (game), 4000 (web) |
+| Base de datos | MySQL 8.0 (puerto 3307) |
+| RAM total | ~1.4 GB (5 contenedores) |
+
+### Arquitectura Multi-Servicio
+```
+maple2-mysql (3307)
+    │
+    ├── maple2-world (21001)     ← Coordinador central, gRPC
+    │       │
+    │       ├── maple2-login (20001) ← Autenticacion, seleccion de personaje
+    │       │
+    │       └── maple2-game-ch0 (20002/21002) ← Canal de juego
+    │
+    └── maple2-web (4000)        ← API web auxiliar
+```
+
+Los servidores se comunican entre si via **gRPC** (HTTP/2). El World server actua como coordinador central. Los Game servers se conectan al World al iniciar.
+
+### Setup Inicial (Primera Vez)
+
+#### 1. Clonar el repositorio
+```bash
+cd servers/
+git clone --recurse-submodules https://github.com/MS2Community/Maple2.git maple2
+```
+
+#### 2. Descargar datos del cliente
+Se necesita el cliente de MapleStory 2 (~14 GB). Los archivos se colocan en `servers/maple2/client-data/Data/`.
+
+Fuentes del cliente:
+- [adventure-island-online-2 releases](https://github.com/shuabritze/adventure-island-online-2/releases) (6 partes ZIP)
+- Extraer todo a `servers/maple2/client-data/`
+
+#### 3. Aplicar XML Patches
+Descargar [MapleStory2-XML v1.2.1](https://github.com/MS2Community/MapleStory2-XML/releases/tag/v1.2.1) y copiar los archivos `Server.m2d`, `Server.m2h`, `Xml.m2d`, `Xml.m2h` a `servers/maple2/client-data/Data/` (reemplazar los originales).
+
+#### 4. Configurar .env
+```bash
+cp servers/maple2/.env.example servers/maple2/.env
+# Editar con las IPs correctas:
+# GAME_IP=192.168.10.234
+# LOGIN_IP=192.168.10.234
+```
+
+#### 5. Verificar .dockerignore
+El archivo `servers/maple2/.dockerignore` DEBE incluir:
+```
+client-data
+client-download
+xml-patches
+```
+Sin esto, el build de Docker intentara copiar 14 GB de datos al contexto.
+
+#### 6. Ingestar datos del juego
+```bash
+cd docker/
+docker compose -f docker-compose.maple2.yml up -d maple2-mysql
+# Esperar a que MySQL este healthy
+docker compose -f docker-compose.maple2.yml run --rm maple2-file-ingest \
+  bash -c "cd /app && dotnet restore && cd Maple2.File.Ingest && dotnet run"
+```
+Este proceso importa todos los datos del cliente a MySQL. Toma ~10 minutos.
+
+#### 7. Construir y levantar servidores
+```bash
+docker compose -f docker-compose.maple2.yml build
+docker compose -f docker-compose.maple2.yml up -d
+```
+
+### Conexion de cliente
+1. Tener el cliente de MapleStory 2 instalado
+2. El cliente debe apuntar a `192.168.10.234:20001` (Login Server)
+3. Las IPs se configuran en `servers/maple2/.env` (`GAME_IP`, `LOGIN_IP`)
+
+### Troubleshooting
+
+- **"No space left on device" al buildear**: Verificar `.dockerignore` incluye `client-data`
+- **"Scripting/Scripts not found"**: Ya corregido — se removio la linea COPY del Dockerfile del Game server
+- **"project.assets.json not found" en file-ingest**: Ejecutar `dotnet restore` antes de `dotnet run`
+- **Servidores no se conectan entre si**: Verificar que `GRPC_WORLD_IP=maple2-world` y `GRPC_GAME_IP=maple2-game-ch0` estan configurados en el compose
+
+### Agregar mas canales de juego
+Para agregar un segundo canal, duplicar el servicio `maple2-game-ch0` en el compose cambiando:
+- Nombre: `maple2-game-ch1`
+- Puertos: `20003:20003` y `21003:21003`
+- `GRPC_GAME_IP: maple2-game-ch1`
+
+---
+
+## Minecraft: FTB Infinity Evolved
+
+### Resumen
+| Dato | Valor |
+|------|-------|
+| Imagen Docker | itzg/minecraft-server:java8 |
+| Modpack | FTB Infinity Evolved v3.1.0 |
+| Minecraft | 1.7.10 |
+| Forge | 10.13.4.1614 |
+| Puerto | 25565 |
+| RAM | ~3.5 GB (6 GB JVM heap, 8 GB limite contenedor) |
+| Mods | ~175 |
+
+### Configuracion
+El servidor se configura via variables de entorno en `docker-compose.dev.yml`:
+
+```yaml
+environment:
+  EULA: "TRUE"
+  TYPE: FTBA
+  FTB_MODPACK_ID: 23
+  FTB_MODPACK_VERSION_ID: 99
+  MEMORY: 6G
+  MAX_MEMORY: 6G
+  MOTD: "Project Afterlife - FTB Infinity Evolved"
+  DIFFICULTY: normal
+  MAX_PLAYERS: 20
+  VIEW_DISTANCE: 10
+  JVM_DD_OPTS: "fml.queryResult=confirm"
+  PRE_LAUNCH_CMD: "cp -n /data/minecraft_server.jar /data/minecraft_server.1.7.10.jar 2>/dev/null; true"
+```
+
+### Fix Conocido: Classpath de Forge 1.7.10
+El MANIFEST.MF del jar de Forge 1.7.10 referencia `minecraft_server.1.7.10.jar` en su Class-Path, pero la imagen itzg renombra el archivo a `minecraft_server.jar`. Sin el fix, Forge no encuentra log4j2 y crashea con `NoClassDefFoundError`.
+
+**Solucion**: El `PRE_LAUNCH_CMD` copia el archivo con el nombre correcto antes de cada inicio. Si recreas el volumen, este fix se aplica automaticamente.
+
+### Primer inicio
+El primer inicio toma 5-10 minutos porque:
+1. Descarga el FTB App installer
+2. Descarga los ~175 mods del modpack
+3. Instala Forge 10.13.4.1614
+4. Genera el mundo
+
+### Conexion de cliente
+1. Instalar [FTB App](https://www.feed-the-beast.com/app), MultiMC, ATLauncher, o Prism Launcher
+2. Instalar modpack **FTB Infinity Evolved** version 3.1.0
+3. Multiplayer > Add Server: `192.168.10.234:25565`
+
+### Modo Experto
+Para activar el modo experto (recetas mas complejas):
+```
+/ftb_mode set expert
+```
+Ejecutar desde la consola del servidor o como operador in-game.
+
+### Troubleshooting
+- **"NoClassDefFoundError: org/apache/logging/log4j/Level"**: El fix de classpath no se aplico. Ejecutar manualmente: `docker exec minecraft-ftb cp /data/minecraft_server.jar /data/minecraft_server.1.7.10.jar` y reiniciar
+- **Server lag**: Reducir `VIEW_DISTANCE` de 10 a 8, o aumentar `MEMORY` si hay RAM disponible
+- **Pastebin 403**: Error inocuo — Pastebin bloquea requests automaticos. Solo afecta a los badges de FTB Utilities, no a la funcionalidad del juego
+
+---
+
+## Operaciones Comunes
+
+### Ver logs de un servidor
+```bash
+docker logs -f minecraft-ftb          # Minecraft
+docker logs -f maple2-world           # MapleStory 2 World
+docker logs -f docker-openfusion-1    # OpenFusion
+```
+
+### Reiniciar un servidor
+```bash
+docker restart minecraft-ftb
+docker restart maple2-world maple2-login docker-maple2-game-ch0-1
+docker restart docker-openfusion-1
+```
+
+### Ver uso de recursos
+```bash
+docker stats --no-stream
+```
+
+### Backup de datos
+```bash
+# PostgreSQL (CMS)
+docker exec docker-postgres-1 pg_dump -U afterlife afterlife > backup_cms.sql
+
+# MySQL (MapleStory 2)
+docker exec maple2-db mysqldump -u root -pmaplestory --databases maple-data game-server > backup_ms2.sql
+
+# Minecraft (mundo completo)
+docker cp minecraft-ftb:/data/world ./backup_minecraft_world/
+```