De cero a un club nuevo funcionando, con su app compilada

Datos del club definidos

Confirma que el slug, el ID de la app y el dominio son los definitivos. Cambiar el ID de la app o la firma después hace que los teléfonos ya instalados no puedan actualizarse.

Instalar las herramientas

Preparar el proyecto Flutter

En la carpeta del proyecto (donde está pubspec.yaml):

flutter pub get
flutter gen-l10n
flutter analyze

Si usas FVM, antepón fvm a cada comando. flutter analyze puede mostrar avisos de estilo (nivel info); solo importan los que digan error.

Comprobar que el script de builds responde

tool\deploy.bat help
tool\deploy.bat list

El primero muestra los comandos disponibles; el segundo lista los clubes que ya existen en deploy/clients/.

Preparar tu acceso SSH a Bitbucket

Para subir código y builds desde tu PC sin escribir contraseña:

ssh-keygen -t ed25519 -C "tu-correo@ejemplo.com"
type %USERPROFILE%\.ssh\id_ed25519.pub

Pulsa Enter en todas las preguntas para aceptar la ruta y dejar la frase vacía. Copia la línea que imprime el segundo comando (en PowerShell es Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub). En Bitbucket: tu foto de perfil · Personal settings · SSH keys · Add key, y pégala. Comprueba con ssh -T git@bitbucket.org: debe saludarte por tu nombre.

Apuntar los nombres al servidor

En el panel del lugar donde compraste el dominio (o de Cloudflare, si lo usas) abre la sección DNS y crea tres registros:

Si usas Cloudflare, deja las nubes en «Solo DNS» (gris) hasta tener el HTTPS funcionando. Para comprobar la propagación:

nslookup {{apiHost}}
nslookup {{webHost}}
nslookup {{updHost}}

Registrar SPF, DKIM y DMARC en el DNS

Sin estos tres registros, Gmail y Outlook mandan los avisos a spam. Se crean como registros TXT en el mismo panel DNS de la fase anterior.

Crear el proyecto

1. Entra a console.firebase.google.com con una cuenta de Google que el club conserve (no la personal de un miembro).
2. Crear un proyecto, con el nombre del club. Google Analytics es opcional; puedes desactivarlo.
3. Al terminar, pulsa el engranaje · Configuración del proyecto · pestaña General.

Agregar la app Android

En General · Tus apps · icono de Android. Escribe el nombre de paquete exactamente igual. Puedes saltar la descarga de google-services.json: esta app no lo usa, los valores se pasan al compilar.

Cuando exista, entra a la tarjeta de la app y a Configuración del SDK · Config. De ahí copia dos valores a los campos de abajo:

• ID de la aplicación: algo como 1:123456789012:android:0a1b2c3d4e5f
• Clave de API (apiKey, empieza con AIza)

Agregar la app iOS

Tus apps · icono de Apple. ID del paquete: . De la tarjeta de la app copia el ID de la aplicación (1:…:ios:…) y la clave de API. Si descargas GoogleService-Info.plist, esos valores son GOOGLE_APP_ID y API_KEY.

Agregar la app Web

Tus apps · icono web </>. Apodo cualquiera; no marques Hosting. Firebase muestra un bloque firebaseConfig: de ahí salen apiKey y appId de la web, y también messagingSenderId y projectId, que ya tienes.

ID del remitente y clave VAPID

Configuración del proyecto · pestaña Cloud Messaging:

• ID de remitente (Sender ID): número de unos 12 dígitos. «API de Firebase Cloud Messaging (V1)» debe estar Habilitada; si no, actívala con los tres puntos · Administrar API.
• Configuración web · Certificados push web · Generar par de claves. Copia la clave pública, una cadena larga que empieza por B. Es la clave VAPID.

Descargar la cuenta de servicio (la única clave secreta)

Configuración del proyecto · Cuentas de servicio · Generar nueva clave privada. Descarga un .json. Es lo que permite al backend enviar push; guárdalo fuera de git. Más adelante lo subes al servidor en .

Clave APNs para que lleguen avisos en iPhone

1. En developer.apple.com/account (programa de pago, 99 USD al año) · Certificates, Identifiers & Profiles · Keys · «+». Marca Apple Push Notifications service (APNs) y descarga el .p8 (solo se descarga una vez).
2. Anota el Key ID (10 caracteres) y tu Team ID (en la cuenta, sección Membership).
3. En Firebase · Configuración · Cloud Messaging · Configuración de la app de Apple: sube el .p8 con el Key ID y el Team ID.

Generar el keystore

keytool viene con el JDK. Primero averigua dónde está en tu equipo: la ruta cambia según cómo instalaste Android Studio y no siempre es C:\Program Files\Android\Android Studio.

Get-Command keytool -ErrorAction SilentlyContinue
# si no muestra nada, busca en las ubicaciones habituales:
Get-ChildItem "C:\Program Files\Android","C:\Program Files\Java","$env:LOCALAPPDATA\Programs","$env:USERPROFILE\.jdks","C:\Program Files\Eclipse Adoptium" -Recurse -Filter keytool.exe -ErrorAction SilentlyContinue | Select-Object -ExpandProperty FullName

Otra forma: flutter doctor -v muestra «Java binary at:»; keytool.exe está en esa misma carpeta bin. Si no hay ningún JDK instalado: winget install EclipseAdoptium.Temurin.17.JDK, cierra y abre PowerShell.

Con la ruta en la mano, ejecuta cada línea por separado (cambia RUTA_DE_KEYTOOL por la que encontraste):

mkdir C:\claves
& "RUTA_DE_KEYTOOL" -genkey -v -keystore C:\claves\{{slug}}.jks -keyalg RSA -keysize 2048 -validity 10000 -alias {{slug}}

Si el primer comando mostró que keytool ya está en el PATH, escribe simplemente keytool -genkey -v … sin ruta ni &. En CMD tampoco se usa el & inicial. Nunca juntes las dos líneas con &: PowerShell lo rechaza. Te hará preguntas:

• Contraseña del almacén: mínimo 6 caracteres. Anótala.
• Nombre y apellido, unidad, organización, ciudad, estado, país: pon los del club (el país como código de 2 letras, ej. CO). No afectan al funcionamiento.
• ¿Es correcto?: escribe si o yes.
• Contraseña de la clave: pulsa Enter para usar la misma que el almacén (más simple).

Crear su key.properties

Dentro de (la carpeta la crea init-client en la fase de archivos; puedes crearla a mano antes) crea este archivo, que git ignora:

storePassword=LA_CONTRASEÑA_DEL_ALMACÉN
keyPassword=LA_CONTRASEÑA_DE_LA_CLAVE
keyAlias={{slug}}
storeFile=C:/claves/{{slug}}.jks

keyAlias debe ser el valor que pusiste en -alias. storeFile lleva ruta absoluta con barras normales (/), aunque estés en Windows.

Si publicas en Google Play

Play usa Play App Signing: la clave que acabas de crear actúa como clave de subida y Google guarda la definitiva. Aun así, conserva el .jks; la necesitas para cada versión. Si además instalas APK directos, los teléfonos que instalaron por Play y los que instalaron por APK tienen firmas distintas y no pueden actualizarse entre sí: decide por cada persona cuál canal usará.

Crear la carpeta del cliente

tool\deploy.bat init-client {{slug}} --name "{{name}}"

Crea con client.json y secrets.json a partir de la plantilla. En el siguiente paso reemplazas su contenido.

Escribir client.json

Este es el archivo completo con todo lo que escribiste. Los valores que todavía faltan aparecen como PEGA_…; completa los de Firebase en su fase y esta vista se actualiza sola.

{
  "slug": "{{slug}}",
  "name": "{{name}}",
  "environment": "prod",
  "android": {
    "applicationId": "{{appId}}",
    "keyProperties": "deploy/clients/{{slug}}/key.properties"
  },
  "ios": { "bundleId": "{{bundleId}}" },
  "urls": {
    "api": "{{api}}",
    "web": "{{web}}",
    "updates": "{{updatesJson}}"
  },
  "update": { "mandatory": false, "minSupportedBuild": 0 },
  "firebase": {
    "projectId": "{{fbProject}}",
    "senderId": "{{senderId}}",
    "android": { "apiKey": "{{fbAndroidKey}}", "appId": "{{fbAndroidApp}}" },
    "ios": { "apiKey": "{{fbIosKey}}", "appId": "{{fbIosApp}}" },
    "web": { "apiKey": "{{fbWebKey}}", "appId": "{{fbWebApp}}", "vapidKey": "{{vapid}}" }
  },
  "backendDir": "{{backendDirJson}}",
  "backend_env": {
    "DB_DATABASE": "{{dbName}}",
    "DB_USERNAME": "{{dbUser}}",
    "MAIL_MAILER": "smtp",
    "MAIL_HOST": "{{mailHost}}",
    "MAIL_PORT": "{{mailPort}}",
    "MAIL_SCHEME": "{{mailScheme}}",
    "MAIL_USERNAME": "{{mailUser}}",
    "MAIL_FROM_ADDRESS": "{{mailUser}}",
    "HR_MAIL_ADDRESS": "{{hrMail}}",
    "SESSION_DOMAIN": ".{{domain}}",
    "NOTIFICATIONS_TIMEZONE": "{{tz}}",
    "HR_DEFAULT_CURRENCY": "{{currency}}"{{s3Json}}
  }
}

Generar APP_KEY y escribir secrets.json

Todo lo secreto va aquí; git lo ignora. Primero genera la clave de cifrado de Laravel desde la carpeta del backend en tu PC:

cd "{{backendDir}}"
php artisan key:generate --show

Imprime una línea que empieza con base64:. Cópiala completa. Después edita el archivo:

{
  "APP_KEY": "base64:PEGA_LA_LINEA_COMPLETA",
  "DB_PASSWORD": "la clave que generaste para MySQL",
  "MAIL_PASSWORD": "la contraseña de aplicación o SMTP",
  "GEMINI_API_KEY": ""
}

Archivos en S3

En la consola de AWS: crea un bucket (S3 · Create bucket, con el acceso público bloqueado), luego en IAM un usuario con permiso solo sobre ese bucket y genera sus claves de acceso. Añade al secrets.json AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY. En el client.json de arriba reemplaza PEGA_NOMBRE_DEL_BUCKET por el nombre del bucket y ajusta la región (la que aparece junto al bucket en S3).

Crear los repositorios y subir el código

En bitbucket.org · Create · Repository. Crea tres, vacíos (sin README): uno para la app, otro para el backend y otro para los builds (por ejemplo kynetic-builds). Para cada uno, el botón Clone · pestaña SSH da su dirección (git@bitbucket.org:espacio/repo.git).

Sube el código que ya tienes (si todavía no tiene repositorio git):

git init -b main
git add .
git commit -m "Primer commit"
git remote add origin git@bitbucket.org:TU-ESPACIO/NOMBRE-DEL-REPO.git
git push -u origin main

Si la carpeta ya era un repositorio, solo hace falta el git remote add y el git push. El repositorio de builds no hace falta crearlo localmente: lo hace tool\deploy.bat la primera vez con --remote.

Activar Pipelines y crear la clave SSH

Hazlo en el repositorio de builds y repite igual en el del backend. En el repositorio · Repository settings:

1. Pipelines · Settings · activa Enable Pipelines.
2. Pipelines · SSH keys · Generate keys. Aparece una clave pública (una sola línea que empieza con ssh-rsa); cópiala completa.
3. Autorízala en el servidor:

   hPanel · Avanzado · Acceso SSH: si tu plan ofrece agregar una clave SSH, pégala ahí. Si no, hazlo por terminal (siguiente bloque).

   Servidor, como el usuario de despliegueCopiar

   mkdir -p ~/.ssh && chmod 700 ~/.ssh
   echo 'PEGA_AQUI_LA_CLAVE_PUBLICA' >> ~/.ssh/authorized_keys
   chmod 600 ~/.ssh/authorized_keys
   cat ~/.ssh/authorized_keys    # cada clave debe ocupar UNA sola línea

   Para entrar al servidor desde tu PC: (en un VPS, entra primero como root y usa ). La clave del otro repositorio se añade en otra línea.

4. Known hosts: no hace falta. Los pipelines aceptan la huella del servidor la primera vez que se conectan. El botón Fetch de Bitbucket solo prueba el puerto 22, así que con SSH en otro puerto (Hostinger usa el 65002) siempre dice «Unable to fetch fingerprints». Es normal: ignóralo.

Variables del repositorio de builds

Repository settings · Pipelines · Repository variables. Agrega estas cuatro (sin marcar como secured; no son secretas). Los nombres no llevan el prefijo del club:

Variables del repositorio del backend

A diferencia del repositorio de builds, aquí los nombres sí llevan el slug en mayúsculas y con guion bajo en lugar de guion: así un mismo repositorio puede desplegar varios clubes (el club se elige al lanzar el pipeline). _APP_PATH es la carpeta del backend (la que contiene artisan), nunca la carpeta public. Usa la ruta absoluta.

Decidir quién será el súper administrador

La primera cuenta con todos los permisos se crea desde database/seeders/SuperAdminSeeder.php. Ese archivo trae los datos de una cuenta (nombre, apodo, correo, cumpleaños, NIT) y una contraseña inicial. Antes del primer despliegue:

1. Edita la constante SUPER_ADMIN con los datos de la persona que será dueña del club.
2. Revisa la contraseña inicial (en run() con Hash::make('…'), o en SUPER_ADMIN_PASSWORD_HASH si tu versión usa un hash). Para generar un hash: php artisan tinker y echo bcrypt('LA_CONTRASEÑA');.
3. Haz commit y push al repositorio del backend antes del primer despliegue.

El seeder nunca crea un segundo súper admin ni cambia una contraseña existente. Las pruebas automáticas leen estos datos del propio seeder, así que no hace falta tocarlas.

Generar el .env del club

tool\deploy.bat backend-env --client {{slug}} --backend "{{backendDir}}"

Combina el .env.example del backend con client.json y secrets.json y lo deja en (ignorado por git). Ábrelo y busca líneas vacías que necesiten valor: deben tener contenido APP_KEY, DB_PASSWORD y MAIL_PASSWORD.

Subir el .env y la cuenta de servicio de Firebase

ssh -p {{sshPort}} {{sshUser}}@{{sshHost}} "mkdir -p {{appPath}}/storage/app"
scp -P {{sshPort}} deploy\private\{{slug}}\backend.env {{sshUser}}@{{sshHost}}:{{appPath}}/.env
ssh -p {{sshPort}} {{sshUser}}@{{sshHost}} "chmod 640 {{appPath}}/.env"
scp -P {{sshPort}} RUTA\DEL\ARCHIVO-DE-FIREBASE.json {{sshUser}}@{{sshHost}}:{{appPath}}/storage/app/firebase-service-account.json

La cuarta línea sube el JSON de cuenta de servicio de la fase de Firebase; ajusta la ruta de origen. Fíjate en la mayúscula: ssh usa -p y scp usa -P. El pipeline no toca .env ni storage/, así que estos archivos sobreviven a los despliegues.

Primer despliegue del código

Primero haz commit y push de todo el backend (incluidos los cambios del seeder). En el repositorio del backend: Pipelines · Run pipeline · rama main · pipeline Custom: deploy-client · variable . Corre las pruebas, sube el código al servidor, crea las carpetas de storage, instala dependencias (composer install --no-dev --no-scripts, luego package:discover), migra la base y arma las cachés.

Comandos de una sola vez: datos mínimos

Conéctate con y ejecuta. Es lo mínimo para que el súper admin entre y cree miembros, ramas y todo lo demás desde la app: estados de usuario, roles, módulos y permisos, la cuenta del súper admin y el tema del club. El orden importa.

cd {{appPath}}
php artisan db:seed --class=UserStatusSeeder --force
php artisan db:seed --class=RolesSeeder --force
php artisan db:seed --class=PermissionSeeder --force
php artisan db:seed --class=SuperAdminSeeder --force
php artisan db:seed --class=ThemeSeeder --force
php artisan config:cache

El último seeder imprime Super admin creado: …. Con eso ya puedes entrar y operar.

RolesSeeder también crea los roles admin, coach y player; si no los quieres, bórralos del archivo antes de desplegar. Cada seeder se puede repetir sin duplicar datos.

cd {{appPath}}
ln -s "$(pwd)/storage/app/public" public/storage
ls -l public/storage

Comprobar la API

Abre en el navegador . Debe devolver un JSON con colores. Si ves un error 500, mira el registro: .

Cola de trabajos (solo si la usas)

Los correos y el push no la necesitan. Solo hace falta un proceso de cola si en tu .env tienes RATING_AI_DISPATCH=queue (Evaluar con IA en segundo plano). En un VPS, Supervisor lo mantiene vivo: crea /etc/supervisor/conf.d/queue.conf con un programa que ejecute con user= el usuario de despliegue, y corre supervisorctl reread && supervisorctl update. Si dejas RATING_AI_DISPATCH en su valor por defecto, sáltate este paso.

Comprobar que el servidor puede recibir archivos

Conéctate como el usuario de despliegue y verifica tres cosas:

which rsync                         # debe mostrar una ruta
ls -ld {{updRoot}}                   # el dueño debe ser este usuario
touch {{updRoot}}/prueba && rm {{updRoot}}/prueba && echo "escritura ok"

Qué lee el teléfono

La app compilada para este club consulta . Estructura del archivo, que genera el script y no se edita a mano:

{
  "version_name": "1.4.0",
  "version_code": 17,
  "apk_url": "nexora-1.4.0-b17.apk",
  "sha256": "9f2c…",
  "size": 48213377,
  "notes": "Corrige el calendario",
  "mandatory": false,
  "min_supported_code": 0
}

La app compara version_code con el número de compilación instalado (lo que va después del + en pubspec.yaml). Si es mayor, ofrece la actualización.

Preparar la imagen

• Un PNG o JPG cuadrado de 1024 × 1024 px o más. Si no es cuadrado se recorta desde el centro.
• Deja un margen de alrededor del 10 %: los teléfonos redondean las esquinas.
• iPhone no admite transparencia: los fondos transparentes se rellenan con el color de fondo del club (blanco si no defines otro, ver el paso de colores).
• Opcionales: una versión simplificada para el favicon (se ve a 16 a 48 px: mejor un símbolo sin letras pequeñas), otra para Windows, y una maskable (el logo ocupa el 80 % central, para íconos redondos). Si no las das, se generan solas desde la principal.

Guardar los íconos del club

La primera vez, descarga las dos dependencias nuevas del script:

flutter pub get

Después ejecuta el comando del constructor. Copia tus imágenes a (icon.png, favicon.png, windows.png, maskable.png). Esa carpeta sí se sube a git: no tiene nada secreto. Para cambiar un ícono más adelante, repite el comando con la imagen nueva.

Qué se genera al compilar

Los íconos se aplican solo durante la compilación de ese club y al terminar el proyecto queda como estaba: no se ensucian los archivos de git ni se mezclan los clubes. Si un build se interrumpe, el siguiente restaura los originales antes de empezar.

Nombre y colores del club (opcional)

En puedes añadir un bloque branding. Todos los campos son opcionales:

"branding": {
  "accent": "#ff6a2b",
  "background": "#ffffff",
  "themeColor": "#120E0B",
  "shortName": "{{name}}"
},

El título de la pestaña, el nombre de la PWA y el nombre bajo el ícono de iPhone salen del name del club en cada build; ya no se queda el de la plantilla.

La página de descargas

Cada build genera y se publica sola con el pipeline. Es la dirección que compartes:

{{updates}}/

• Android: botón «Descargar APK» con la versión, el peso y cómo instalarlo.
• iPhone y iPad: la guía para instalar la app web desde Safari (Compartir · Añadir a pantalla de inicio; iOS 16.4 o superior).
• Windows: botón para descargar el .zip y cómo abrirlo (aparece cuando publicas un build de Windows).
• Navegador: botón para abrir la versión web.
• Código QR de la página, para que alguien la abra escaneándolo, y el aviso «Recomendado para tu dispositivo» según el teléfono o computador desde el que se abre.

Al compilar solo la web, los botones de Android y Windows no desaparecen: la página lee los datos de los últimos builds publicados.

La app de Windows

• Solo se compila en un computador con Windows, con Visual Studio 2022 y la carga de trabajo «Desarrollo para el escritorio con C++». flutter doctor debe marcar visto bueno en «Visual Studio».
• Se compila con --targets windows (el constructor de la fase siguiente ya tiene la casilla). Si tienes Inno Setup instalado (winget install JRSoftware.InnoSetup), sale un instalador -setup.exe: se instala por usuario en %LOCALAPPDATA%\Programs sin pedir administrador, crea acceso en el menú Inicio y el escritorio, y se desinstala desde Configuración. Además se publica un .zip portátil. Sin Inno Setup solo sale el .zip.
• Actualización automática: la app instalada lee windows/latest.json, descarga el instalador nuevo, comprueba el SHA-256 y lo ejecuta en silencio; la app se cierra y se vuelve a abrir actualizada. Para probarla, compila otra versión con un número de build mayor.
• Ruta corta: mantén el proyecto en una ruta corta (por ejemplo C:\dev\kynetic); con rutas largas MSBuild falla al compilar plugins de Windows.
• El instalador y el ejecutable no están firmados con certificado de editor: Windows mostrará «SmartScreen protegió su PC» y hay que pulsar Más información · Ejecutar de todas formas (la página de descargas lo explica).
• El título de la ventana, las propiedades del archivo y el nombre del .exe salen del club al compilar: el título y las propiedades usan el name de client.json, y el ejecutable usa el slug con guiones bajos (por ejemplo con guiones bajos) o el branding.exeName que definas. Los archivos de Windows del proyecto se modifican solo durante la compilación y luego se restauran.

Lista previa al primer build

• sin ningún PEGA_… (la vista de la fase de archivos lo marca).
• y el .jks en su sitio.
• flutter pub get ejecutado al menos una vez.
• urls.updates apuntando a un servidor con HTTPS que responda.
• Si quieres los íconos del club, haber hecho la fase anterior (set-icons). Sin ellos se usan los íconos por defecto.
• Un Mac con Xcode y la cuenta de Apple (ver la fase de tiendas) para el IPA.

Primer build con publicación

Marca «Primera vez» arriba para que el script cree dist/builds, copie el pipeline, haga git init y suba al repositorio de builds. La primera compilación de Android descarga Gradle y tarda varios minutos; las siguientes, menos.

Qué sale de cada destino

Comprobar la publicación en el servidor

Abre en el navegador: debe mostrar el JSON con la versión y el build que acabas de compilar. Abre : debe cargar la app. Y abre : debe aparecer la página de descargas del club.

Primer ingreso y marca del club

Abre e inicia sesión con la cuenta de súper administrador (la del seeder; ver la fase de backend). Cambia la contraseña en Ajustes. Luego abre Club · Identidad: sube el logo (PNG cuadrado, fondo transparente, 512 px o más) y guarda la paleta. De ahí salen los colores de la app, de los correos y el logo de las notificaciones.

Instalar el primer APK

Abre en el teléfono el enlace (el nombre exacto aparece en latest.json) o muéstrales un QR. Android pedirá permitir «instalar apps desconocidas» para el navegador. Esta primera instalación es manual para todas las personas.

Probar la actualización de punta a punta

1. Con la versión instalada, compila y publica otra con las opciones por defecto (sube el número de build).
2. Abre la app en el teléfono. Debe aparecer la tarjeta «Hay una versión nueva» con tus notas (la consulta se repite como máximo cada 6 horas, salvo al abrir la app).
3. Pulsa Actualizar, espera la descarga y confirma en el instalador de Android.

Android la acepta solo con el mismo ID de app, la misma firma y un build mayor.

Probar un aviso push en cada dispositivo

Asígnale una tarea a otra persona. Debe llegar el aviso en un Android real, en un iPhone (PWA instalada con Compartir · Añadir a pantalla de inicio, iOS 16.4 o superior) y en Chrome de escritorio, y al tocarlo debe abrir /tareas. Cada persona activa los avisos desde la campana.

Comprobar correos y recordatorios

php artisan tinker
>>> \App\Models\User::first()->notify(new \App\Notifications\AccountActivatedNotification);
>>> exit
php artisan notifications:daily
php artisan notifications:event-reminders

El correo debe llegar a la bandeja principal con el logo y los colores del club. Si no, revisa SPF, DKIM y DMARC (fase de correo) y el registro del backend.

Abrir el club al equipo

Crea una rama por juego, revisa los roles, genera invitaciones KYN-XXXX-XXXX y cada persona se registra con su código. Prueba también la subida de un archivo grande y activa la copia de seguridad de la base de datos y de storage/app.

Club terminado

Todas las fases están cerradas. Guarda en un lugar seguro el .jks, sus contraseñas, secrets.json y backend.env.