Almacenamiento personalizado

Capgo permite usar soluciones de almacenamiento personalizadas para tus app bundles, permitiéndote alojar tus actualizaciones en tu propia infraestructura o servicios de terceros. Esto es ideal para organizaciones con requisitos de seguridad específicos, necesidades de cumplimiento o infraestructura de almacenamiento existente.

Resumen

El almacenamiento personalizado en Capgo funciona subiendo tu bundle a una ubicación externa y proporcionando a Capgo la URL de acceso. El Capgo SDK descargará las actualizaciones directamente desde tu ubicación personalizada en lugar del almacenamiento cloud por defecto de Capgo.

Consejo

El almacenamiento personalizado es ideal para:

• Organizaciones con requisitos estrictos de residencia de datos
• Equipos con infraestructura de CDN o almacenamiento propia
• Aplicaciones que requieren capas de seguridad adicionales
• Optimización de costes para bundles de gran tamaño

Upload mediante URL externa

La forma más sencilla de usar un almacenamiento personalizado es subiendo tu bundle a cualquier URL pública y proporcionando esa URL a Capgo.

Upload básico mediante URL externa

npx @capgo/cli@latest bundle upload --external https://your-domain.com/bundles/v1.2.3.zip

Este comando indica a Capgo que use el bundle de la URL especificada en lugar de subirlo al almacenamiento en la nube de Capgo.

Con cifrado

Para un almacenamiento externo seguro, puedes cifrar tu bundle y proporcionar las claves de descifrado:

npx @capgo/cli@latest bundle upload --external https://your-domain.com/bundles/v1.2.3.zip --iv-session-key YOUR_IV_SESSION_KEY

Integración con S3

Capgo ofrece soporte nativo para Amazon S3 y servicios de almacenamiento compatibles con S3. El CLI puede subir automáticamente tu bundle a S3 y configurar Capgo para usar la URL de S3.

Opciones de subida a S3

npx @capgo/cli@latest bundle upload \
  --s3-region us-east-1 \
  --s3-apikey YOUR_ACCESS_KEY \
  --s3-apisecret YOUR_SECRET_KEY \
  --s3-bucket-name your-bucket-name

Configuración completa de S3

Para servicios compatibles con S3 o endpoints personalizados:

npx @capgo/cli@latest bundle upload \
  --s3-region us-east-1 \
  --s3-apikey YOUR_ACCESS_KEY \
  --s3-apisecret YOUR_SECRET_KEY \
  --s3-endpoint https://s3.your-provider.com \
  --s3-bucket-name your-bucket-name \
  --s3-port 443 \
  --no-s3-ssl  # Only if your endpoint doesn't support SSL

Parámetros de configuración de S3

Parámetro	Descripción	Obligatorio
--s3-region	Región de AWS para tu bucket de S3	Sí
--s3-apikey	ID de la clave de acceso S3	Sí
--s3-apisecret	Clave de acceso secreta S3	Sí
--s3-bucket-name	Nombre de tu bucket S3	Sí
--s3-endpoint	URL del endpoint S3 personalizado	No
--s3-port	Puerto del endpoint S3	No
--no-s3-ssl	Desactivar SSL para el upload a S3	No

Preparación y cifrado del bundle

Al usar un storage personalizado, especialmente con cifrado, debes preparar tus bundles correctamente. Esto implica crear un archivo zip y, opcionalmente, cifrarlo.

Paso 1: Crear un bundle zip

Primero, crea un archivo zip con el bundle de tu app:

npx @capgo/cli@latest bundle zip com.example.app --path ./dist

El comando zip devolverá el checksum del archivo zip. Puedes usar este checksum para cifrar el zip si es necesario. Usa la --json opción para obtener una salida estructurada que incluya el checksum.

Opciones del comando zip

npx @capgo/cli@latest bundle zip [appId] \
  --path ./dist \
  --bundle 1.2.3 \
  --name myapp-v1.2.3 \
  --json \
  --no-code-check \
  --key-v2 \
  --package-json ../../package.json,./package.json

Opción	Descripción
--path	Ruta de la carpeta a comprimir (por defecto, webDir de capacitor.config)
--bundle	Número de versión del bundle para nombrar el archivo zip
--name	Nombre personalizado para el archivo zip
--json	Resultados en formato JSON (incluye checksum)
--no-code-check	Omitir la comprobación de notifyAppReady() y del archivo index
--key-v2	Usar cifrado v2
--package-json	Rutas a los archivos package.json para monorepos (separadas por comas)

Paso 2: Cifrar el bundle (opcional)

Para mayor seguridad, encripta tu bundle zip antes de subirlo:

# Using default local key
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM

# Using custom key file
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM --key ./path/to/.capgo_key_v2

# Using key data directly
npx @capgo/cli@latest bundle encrypt ./myapp.zip CHECKSUM --key-data "PRIVATE_KEY_CONTENT"

El CHECKSUM el parámetro es obligatorio y debe ser el checksum de tu archivo zip. Puedes obtener el checksum con el comando zip (usa --json para obtener una salida estructurada).

Por defecto, el comando encrypt usará tu clave privada local. Puedes especificar una clave personalizada usando las --key o --key-data opciones.

El comando encrypt devolverá el ivSessionKey necesario para la subida o el desencriptado.

Opciones del comando de cifrado

Opción	Descripción
zipPath	Ruta al archivo zip a cifrar (obligatorio)
checksum	Checksum del archivo zip (obligatorio) - obtener con el comando zip
--key	Ruta personalizada para la clave de firma privada (opcional, usa la clave local por defecto)
--key-data	Datos de la clave de firma privada directamente (opcional)
--json	Mostrar resultados en formato JSON

Precaución

El comando encrypt generará un ivSessionKey que deberás proporcionar al hacer upload con la --iv-session-key opción.

Ejemplos de workflow completo

Ejemplo 1: URL externa con cifrado

1. Build de tu app:

   npm run build

2. Crea un bundle zip:

   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --bundle 1.2.3

   Anota el checksum que devuelve este comando.

3. Encripta el bundle:

   npx @capgo/cli@latest bundle encrypt ./com.example.app-1.2.3.zip CHECKSUM_FROM_STEP_2

   Anota el ivSessionKey de la salida.

4. Súbelo a tu storage: Sube el archivo zip encriptado a tu servicio de hosting.

5. Regístralo en Capgo:

   npx @capgo/cli@latest bundle upload \
     --external https://your-cdn.com/bundles/com.example.app-1.2.3.zip \
     --iv-session-key IV_SESSION_KEY_FROM_STEP_3

Ejemplo 2: Upload directo a S3

1. Build de tu app:

   npm run build

2. Upload directo a S3:

   npx @capgo/cli@latest bundle upload \
     --s3-region us-west-2 \
     --s3-apikey YOUR_ACCESS_KEY \
     --s3-apisecret YOUR_SECRET_KEY \
     --s3-bucket-name your-app-bundles \
     --channel Production

Ejemplo 3: S3 con cifrado

1. Build y zip:

   npm run build
   npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2

2. Encriptar el bundle:

   npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM

3. Subir a S3 con encriptación:

   npx @capgo/cli@latest bundle upload \
     --s3-region us-west-2 \
     --s3-apikey YOUR_ACCESS_KEY \
     --s3-apisecret YOUR_SECRET_KEY \
     --s3-bucket-name your-app-bundles \
     --iv-session-key IV_SESSION_KEY_FROM_STEP_2 \
     --channel Production

Consideraciones de seguridad

Al usar un storage personalizado, considera estas buenas prácticas de seguridad:

Control de acceso

• Asegúrate de que las URLs de tu storage sean accesibles para los usuarios de tu app, pero no descubribles públicamente
• Usa URLs firmadas o autenticación por token cuando sea posible
• Implementa los headers CORS adecuados para apps web

Cifrado

• Encripta siempre los bundles sensibles con las herramientas de Capgo
• Guarda las llaves de encriptación de forma segura y rotalas regularmente
• Usa HTTPS para todas las URLs de los bundles (requerido en mobile y Electron)

Monitoreo

• Monitorea los logs de acceso para detectar patrones de descarga inusuales
• Configura alertas para fallos en la descarga de bundles
• Audita regularmente los permisos de tu storage

Solución de problemas

Problemas comunes

El bundle no se descarga:

• Verifica que la URL sea pública y use HTTPS (requerido para apps móviles y Electron)
• Revisa los headers de CORS para web apps
• Asegúrate de que el formato del bundle sea correcto

Errores de cifrado:

• Verifica el ivSessionKey coincide con el bundle cifrado
• Comprueba que el bundle se cifró con la clave correcta
• Asegúrate de usar encryption v2 para nuevos bundles

Errores al subir a S3:

• Verifica tus credenciales y permisos de S3
• Revisa las políticas del bucket y la configuración CORS
• Asegúrate de que la región especificada sea correcta

Comandos de Debug

Verifica el estado del bundle:

npx @capgo/cli@latest app debug

Verifica la integridad del bundle:

npx @capgo/cli@latest bundle list

Próximos pasos

• Aprende sobre Canales para gestionar distintos entornos de despliegue
• Explorar Comportamiento de actualización para personalizar la aplicación de las actualizaciones
• Configura Integración CI/CD para automatizar tu flujo de trabajo de custom storage

Continuar desde Custom Storage

Si estás usando Almacenamiento personalizado para planificar la seguridad y el cumplimiento, conéctalo con Cifrado para los detalles de implementación en Cifrado, Cumplimiento para los detalles de implementación en Cumplimiento, Escáner de seguridad de Capgo para el flujo de trabajo del producto en Capgo Security Scanner, Seguridad de Capgo para el flujo de trabajo del producto en Capgo Security, y Centro de confianza de Capgo para el flujo de trabajo del producto en Capgo Trust Center.