Passer au contenu

Custom Storage

Ce contenu n'est pas encore disponible dans votre langue.

Capgo supports custom storage solutions for your app bundles, allowing you to host your updates on your own infrastructure or third-party storage services. This is particularly useful for organizations with specific security requirements, compliance needs, or existing storage infrastructure.

Overview

Custom storage in Capgo works by uploading your bundle to an external location and providing Capgo with the URL to access it. The Capgo SDK will then download updates directly from your custom storage location instead of Capgo’s default cloud storage.

External URL Upload

The simplest way to use custom storage is by uploading your bundle to any publicly accessible URL and providing that URL to Capgo.

Basic External URL Upload

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

This command tells Capgo to reference the bundle at the specified URL instead of uploading it to Capgo’s cloud storage.

With Encryption

For secure external storage, you can encrypt your bundle and provide the decryption keys:

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

S3 Integration

Capgo provides built-in support for Amazon S3 and S3-compatible storage services. The CLI can automatically upload your bundle to S3 and configure Capgo to use the S3 URL.

S3 Upload Options

Terminal window
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

Complete S3 Configuration

For S3-compatible services or custom endpoints:

Terminal window
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

S3 Configuration Parameters

ParameterDescriptionRequired
--s3-regionAWS region for your S3 bucketYes
--s3-apikeyS3 access key IDYes
--s3-apisecretS3 secret access keyYes
--s3-bucket-nameName of your S3 bucketYes
--s3-endpointCustom S3 endpoint URLNo
--s3-portPort for S3 endpointNo
--no-s3-sslDisable SSL for S3 uploadNo

Bundle Preparation and Encryption

When using custom storage, especially with encryption, you need to prepare your bundles properly. This involves creating a zip file and optionally encrypting it.

Step 1: Create a Zip Bundle

First, create a zip file of your app bundle:

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

The zip command will return the checksum of the zip file. You can use this checksum to encrypt the zip file if needed. Use the --json option to get structured output including the checksum.

Zip Command Options

Terminal window
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
OptionDescription
--pathPath to the folder to zip (defaults to webDir from capacitor.config)
--bundleBundle version number to name the zip file
--nameCustom name for the zip file
--jsonOutput results in JSON format (includes checksum)
--no-code-checkSkip checking for notifyAppReady() call and index file
--key-v2Use encryption v2
--package-jsonPaths to package.json files for monorepos (comma separated)

Step 2: Encrypt the Bundle (Optional)

For enhanced security, encrypt your zip bundle before uploading:

Terminal window
# 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"

The CHECKSUM parameter is required and should be the checksum of your zip file. You can get the checksum from the zip command output (use --json option for structured output).

By default, the encrypt command will use your local private signing key. You can specify a custom key using the --key or --key-data options.

The encrypt command will return the ivSessionKey needed for upload or decryption.

Encryption Command Options

OptionDescription
zipPathPath to the zip file to encrypt (required)
checksumChecksum of the zip file (required) - get it from zip command
--keyCustom path for private signing key (optional, uses local key by default)
--key-dataPrivate signing key data directly (optional)
--jsonOutput results in JSON format

Complete Workflow Examples

Example 1: External URL with Encryption

  1. Build your app:

    Terminal window
    npm run build
  2. Create a zip bundle:

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

    Note the checksum returned by this command.

  3. Encrypt the bundle:

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

    Note the ivSessionKey from the output.

  4. Upload to your storage: Upload the encrypted zip file to your hosting service.

  5. Register with Capgo:

    Terminal window
    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

Example 2: Direct S3 Upload

  1. Build your app:

    Terminal window
    npm run build
  2. Upload directly to S3:

    Terminal window
    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

Example 3: S3 with Encryption

  1. Build and zip:

    Terminal window
    npm run build
    npx @capgo/cli@latest bundle zip com.example.app --path ./dist --key-v2
  2. Encrypt the bundle:

    Terminal window
    npx @capgo/cli@latest bundle encrypt ./com.example.app.zip CHECKSUM
  3. Upload to S3 with encryption:

    Terminal window
    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

Security Considerations

When using custom storage, consider these security best practices:

Access Control

  • Ensure your storage URLs are accessible to your app users but not publicly discoverable
  • Use signed URLs or token-based authentication when possible
  • Implement proper CORS headers for web-based apps

Encryption

  • Always encrypt sensitive bundles using the Capgo encryption tools
  • Store encryption keys securely and rotate them regularly
  • Use HTTPS for all bundle URLs (required for iOS and Android)

Monitoring

  • Monitor access logs to detect unusual download patterns
  • Set up alerts for failed bundle downloads
  • Regularly audit your storage permissions

Troubleshooting

Common Issues

Bundle not downloading:

  • Verify the URL is publicly accessible and uses HTTPS (required for iOS and Android)
  • Check CORS headers for web apps
  • Ensure the bundle format is correct

Encryption errors:

  • Verify the ivSessionKey matches the encrypted bundle
  • Check that the bundle was encrypted with the correct key
  • Ensure encryption v2 is used for new bundles

S3 upload failures:

  • Verify your S3 credentials and permissions
  • Check bucket policies and CORS configuration
  • Ensure the specified region is correct

Debug Commands

Check bundle status:

Terminal window
npx @capgo/cli@latest app debug

Verify bundle integrity:

Terminal window
npx @capgo/cli@latest bundle list

Next Steps