HUB
Sign inSign up

samue45/client-kosmos

By samue45

•Updated 6 months ago

ClientKosmos · Laravel 12 + React 19 + FrankenPHP · imagen lista para Railway / docker-compose

Image
Web servers
0

2.4K

samue45/client-kosmos repository overview

⁠Inicio rápido con Docker Compose

Ejemplo mínimo de docker-compose.yml. Incluye un servicio init que aplica migraciones y seeders una sola vez por deploy, y un worker que reusa la misma imagen para procesar la cola (sin él, los emails de verificación, recordatorios y transcripciones se quedan encolados sin consumirse).

services:
  init:
    image: samue45/client-kosmos:latest
    restart: "no"
    environment:
      CONTAINER_ROLE: init
      APP_NAME: ClientKosmos
      APP_ENV: production
      APP_KEY: base64:REEMPLAZA_ESTO   # generar con: docker run --rm samue45/client-kosmos:latest php artisan key:generate --show
      APP_URL: https://tu-dominio.example
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: clientkosmos
      DB_USERNAME: clientkosmos
      DB_PASSWORD: changeme
    depends_on:
      db:
        condition: service_healthy

  app:
    image: samue45/client-kosmos:latest
    ports:
      - "8000:8000"
    environment:
      CONTAINER_ROLE: web
      SKIP_DB_BOOTSTRAP: "1"           # el servicio `init` ya migró
      APP_NAME: ClientKosmos
      APP_ENV: production
      APP_DEBUG: "false"
      APP_KEY: base64:REEMPLAZA_ESTO   # MISMO valor en todos los servicios
      APP_URL: https://tu-dominio.example
      ASSET_URL: https://tu-dominio.example
      TRUSTED_PROXIES: "*"
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: clientkosmos
      DB_USERNAME: clientkosmos
      DB_PASSWORD: changeme
      SESSION_DRIVER: database
      CACHE_STORE: database
      QUEUE_CONNECTION: database
      BROADCAST_CONNECTION: "null"
      LOG_CHANNEL: stderr
      MAIL_MAILER: log
    volumes:
      - clientkosmos_storage:/app/storage/app
    depends_on:
      init:
        condition: service_completed_successfully
      db:
        condition: service_healthy

  worker:
    image: samue45/client-kosmos:latest
    restart: on-failure
    environment:
      CONTAINER_ROLE: queue            # arranca `queue:work` en vez de FrankenPHP
      APP_NAME: ClientKosmos
      APP_ENV: production
      APP_KEY: base64:REEMPLAZA_ESTO   # MISMO valor que en `app`
      APP_URL: https://tu-dominio.example
      DB_CONNECTION: mysql
      DB_HOST: db
      DB_PORT: "3306"
      DB_DATABASE: clientkosmos
      DB_USERNAME: clientkosmos
      DB_PASSWORD: changeme
      SESSION_DRIVER: database
      CACHE_STORE: database
      QUEUE_CONNECTION: database
      LOG_CHANNEL: stderr
      MAIL_MAILER: log
    volumes:
      - clientkosmos_storage:/app/storage/app
    depends_on:
      init:
        condition: service_completed_successfully
      db:
        condition: service_healthy

  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: clientkosmos
      MYSQL_USER: clientkosmos
      MYSQL_PASSWORD: changeme
      MYSQL_ROOT_PASSWORD: rootchangeme
    volumes:
      - clientkosmos_dbdata:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 5s
      retries: 10

volumes:
  clientkosmos_storage:
  clientkosmos_dbdata:

Genera primero la APP_KEY y pégala en los tres servicios:

docker run --rm --entrypoint php samue45/client-kosmos:latest artisan key:generate --show
docker compose up -d
docker compose logs -f app

Abre http://localhost:8000⁠.

Variante de un solo servicio: si prefieres no tener init aparte, omítelo y deja que app haga el bootstrap (es el comportamiento por defecto cuando SKIP_DB_BOOTSTRAP no está fijado a 1). El servicio init se recomienda solo para deploys multi-servicio (Railway, K8s) donde quieres aislar migraciones del runtime HTTP.

APP_KEY: en APP_ENV=production el entrypoint falla rápido si está vacía (no la autogenera, porque regenerarla invalida sesiones y cookies firmadas). En desarrollo (APP_ENV=local) sí se genera una efímera y se avisa por logs.

Si APP_ENV no es production y la tabla users está vacía, el entrypoint ejecuta los seeders de demo automáticamente. En producción nunca se siembran datos demo, solo RoleSeeder y PermissionSeeder (idempotentes).

Para desarrollo local con email: añade axllent/mailpit:latest exponiendo 1025:1025 (SMTP) y 8025:8025 (UI). Apunta MAIL_MAILER=smtp + MAIL_HOST=mailpit + MAIL_PORT=1025 en app y worker. Lee los emails capturados en http://localhost:8025.

⁠Usuarios demo (no productivos)
EmailPasswordRol
[email protected]passwordadmin
[email protected]passwordprofesional

⁠Variables de entorno

⁠Obligatorias
ClaveDescripción
APP_KEYClave de cifrado de Laravel. Genera con docker run --rm samue45/client-kosmos:latest php artisan key:generate --show y fíjala. En APP_ENV=production el entrypoint falla si está vacía.
APP_URL / ASSET_URLURL pública absoluta (con https://). Wayfinder e Inertia generan URLs a partir de ella.
DB_*DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD. Probado con MySQL 8.0 y 8.4.
⁠Recomendadas
  • APP_ENV=production
  • APP_DEBUG=false
  • TRUSTED_PROXIES=* si hay un reverse proxy delante (Railway, Traefik, Nginx)
  • SESSION_DRIVER=database
  • CACHE_STORE=database
  • QUEUE_CONNECTION=database
  • BROADCAST_CONNECTION=null (por defecto; ver sección Reverb más abajo)
  • LOG_CHANNEL=stderr
  • PORT=8000 si tu plataforma usa esa variable para health checks
⁠Opcionales por funcionalidad
FuncionalidadVariables
Despliegue multi-servicioCONTAINER_ROLE=init|web|queue|scheduler|reverb (default web)
Saltar bootstrap en webSKIP_DB_BOOTSTRAP=1 (usado cuando hay un servicio init separado)
Pagos con Stripe CheckoutSTRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET
Google OAuth + Calendar/MeetGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI
Asistente Kosmo (LLM)GROQ_API_KEY, GROQ_BASE_URL, GROQ_MODEL
Transcripción Whisper / OpenAIOPENAI_API_KEY, OPENAI_ORGANIZATION
Email vía SMTP (Brevo recomendado)MAIL_MAILER=smtp, MAIL_HOST=smtp-relay.brevo.com, MAIL_PORT=587, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION=tls, MAIL_FROM_ADDRESS
Email vía Resend (HTTP API)MAIL_MAILER=resend, RESEND_API_KEY, MAIL_FROM_ADDRESS (requiere dominio verificado en Resend)
Object storage (Cloudflare R2 / S3)FILESYSTEM_DISK=s3, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET, AWS_ENDPOINT (R2), AWS_USE_PATH_STYLE_ENDPOINT=true
WebSockets / live updatesBROADCAST_CONNECTION=reverb, REVERB_APP_ID, REVERB_APP_KEY, REVERB_APP_SECRET, REVERB_HOST, REVERB_PORT, REVERB_SCHEME

Email en producción: la configuración estable es Brevo SMTP (free tier 300 emails/día, basta verificar un sender — no requiere dominio propio). Railway bloquea egreso SMTP por defecto, así que en Railway concretamente el transport activo es Brevo SMTP con sender verificado. Si tienes dominio propio puedes conmutar a Resend con el transport resend. Las notificaciones de verificación y reset de contraseña están encoladas (QueuedVerifyEmail, QueuedResetPassword), así que necesitas el servicio worker arriba para que se envíen.

Runtime inmutable: desde el último refactor, el entrypoint NO vuelca las variables del proceso al .env interno. Laravel resuelve env() leyendo $_SERVER / $_ENV / getenv(), y config:cache captura los valores del proceso correctamente. No intentes editar /app/.env dentro del contenedor — no tiene efecto sobre la config cacheada.


⁠Volúmenes

RutaQué guardaObligatorio
/app/storage/appSubidas de usuario, documentos, transcripciones, evidenciaSí (*)

(*) Solo si no usas object storage. Con FILESYSTEM_DISK=s3 apuntando a Cloudflare R2 o S3, los archivos viven fuera del contenedor y no hace falta montar nada.

No montes /app/storage completo. framework/cache, framework/sessions y framework/views deben regenerarse en cada arranque; persistirlas puede provocar cachés obsoletas.


⁠Healthcheck

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost:8000/up || exit 1

El endpoint /up (Laravel 11+) devuelve 200 cuando providers y contenedor inicializan sin errores. Es una sonda de liveness. Para una sonda de readiness más profunda (con check de BD o servicios externos), engánchate al evento Illuminate\Foundation\Events\DiagnosingHealth en bootstrap/app.php.


⁠Puertos

  • 8000/tcp — HTTP plano (FrankenPHP). TLS lo termina el proxy externo.
  • 8080/tcp — Reverb WebSocket (solo cuando CONTAINER_ROLE=reverb; configurable con PORT).

⁠Roles del contenedor (CONTAINER_ROLE)

La misma imagen sirve para los cinco procesos de un despliegue Laravel típico:

RolComando que arrancaToca la BDNotas
initOne-shot: migraciones + seeders + storage:link, luego exit 0SíPensado para depends_on: service_completed_successfully
webFrankenPHP (default)Sí si SKIP_DB_BOOTSTRAP != "1"Si no hay init separado, se encarga del bootstrap
queuephp artisan queue:work --tries=3 --backoff=10 --timeout=30 --sleep=3NoSin --max-time / --max-jobs (Railway: ON_FAILURE no rearranca exit 0)
schedulerphp artisan schedule:workNo
reverbphp artisan reverb:start --host=0.0.0.0 --port=${PORT:-8080}NoNo espera a MySQL en el boot

Separar init del runtime HTTP evita que un fallo parcial de migración deje al web container en bucle de restart sirviendo 500s.


⁠Entrypoint

docker-entrypoint.sh ejecuta, en orden:

  1. APP_KEY: fail-fast si está vacía y APP_ENV=production; autogenerar efímera solo en desarrollo.
  2. php artisan package:discover (composer install corrió con --no-scripts en el Dockerfile).
  3. Esperar a MySQL vía PDO (30 intentos, 2 s entre cada uno). Saltado en el rol reverb.
  4. Bootstrap de BD (solo init, o web con SKIP_DB_BOOTSTRAP != "1"):
    • php artisan storage:link --force
    • php artisan migrate --force
    • db:seed --class=RoleSeeder y --class=PermissionSeeder (idempotentes, siempre)
    • Si APP_ENV ≠ production y users está vacía → db:seed de demo
  5. Cachear config / route / view si APP_ENV=production (lee env del proceso, no del .env).
  6. exit 0 si rol = init; en cualquier otro caso exec al proceso final (FrankenPHP, queue:work, schedule:work o reverb:start). El exec permite que SIGTERM de Docker/Railway llegue al proceso y haga shutdown limpio.

⁠Plataformas probadas

  • Railway — despliegue desde el repositorio con Dockerfile, multi-servicio vía CONTAINER_ROLE
  • Docker Compose — entorno local y producción self-hosted
  • VPS + Traefik — configuración archivada en deploy/legacy/⁠

Runbooks:


⁠Recursos


⁠Licencia

MIT — ver LICENSE⁠.

La imagen base dunglas/frankenphp⁠ también está bajo licencia MIT.

Tag summary

Content type

Image

Digest

sha256:d4202ffb5…

Size

115.3 MB

Last updated

6 months ago

docker pull samue45/client-kosmos