From 8651b86b5b5c3dde24a17728cd4658491e66f7aa Mon Sep 17 00:00:00 2001 From: Martin Donadieu Date: Sun, 19 Jan 2025 05:10:54 +0000 Subject: [PATCH] fix: add better quickstart --- _redirects | 1 + astro.config.mjs | 41 +++--- src/content/docs/docs/cli/overview.mdx | 6 + .../docs/docs/getting-started/add-an-app.mdx | 42 ++++++ .../docs/docs/getting-started/deploy.mdx | 83 ++++++++++++ .../docs/docs/getting-started/quickstart.mdx | 47 +++++++ .../docs/getting-started/troubleshooting.mdx | 124 ++++++++++++++++++ .../docs/docs/getting-started/wrapping-up.mdx | 52 ++++++++ src/content/docs/docs/how-to.mdx | 2 +- src/content/docs/docs/index.mdx | 4 +- .../docs/docs/live-updates/channels.mdx | 80 +++++++++++ .../docs/docs/live-updates/differentials.mdx | 4 + src/content/docs/docs/live-updates/index.mdx | 77 +++++++++++ .../docs/docs/live-updates/rollbacks.mdx | 6 + .../docs/live-updates/update-behavior.mdx | 7 + src/css/global.css | 5 - 16 files changed, 558 insertions(+), 23 deletions(-) create mode 100644 src/content/docs/docs/cli/overview.mdx create mode 100644 src/content/docs/docs/getting-started/add-an-app.mdx create mode 100644 src/content/docs/docs/getting-started/deploy.mdx create mode 100644 src/content/docs/docs/getting-started/quickstart.mdx create mode 100644 src/content/docs/docs/getting-started/troubleshooting.mdx create mode 100644 src/content/docs/docs/getting-started/wrapping-up.mdx create mode 100644 src/content/docs/docs/live-updates/channels.mdx create mode 100644 src/content/docs/docs/live-updates/differentials.mdx create mode 100644 src/content/docs/docs/live-updates/index.mdx create mode 100644 src/content/docs/docs/live-updates/rollbacks.mdx create mode 100644 src/content/docs/docs/live-updates/update-behavior.mdx diff --git a/_redirects b/_redirects index 63b13d27..1b6f60df 100644 --- a/_redirects +++ b/_redirects @@ -10,3 +10,4 @@ docs/plugin/know-issues docs/plugin/known-issues/ 200 /sitemap.xml /sitemap-index.xml 301 /sitemap-index.xml/ /sitemap-index.xml 301 /sitemap-0.xml/ /sitemap-0.xml 301 +/docs/plugin/cloud-mode/getting-started/ /docs/getting-started/quickstart 302 diff --git a/astro.config.mjs b/astro.config.mjs index 3a9e19c5..cd34843a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -22,6 +22,10 @@ export default defineConfig({ status: 302, destination: '/docs/plugin/cloud-mode/getting-started/', }, + '/docs/plugin/cloud-mode/getting-started/': { + status: 302, + destination: '/docs/getting-started/quickstart', + }, }, i18n: { locales, @@ -82,12 +86,30 @@ export default defineConfig({ }, sidebar: [ { - label: 'Home', + label: 'Welcome to Capgo', link: '/docs/', }, { - label: 'Getting Started', - link: '/docs/plugin/cloud-mode/getting-started/', + label: 'Quickstart', + collapsed: false, + autogenerate: { directory: 'docs/getting-started' }, + }, + { + label: 'Capgo CLI', + collapsed: true, + items: [ + { label: 'Commands', link: '/docs/cli/commands' }, + { + label: 'Migrations', + collapsed: true, + autogenerate: { directory: 'docs/cli/migrations' }, + }, + ], + }, + { + label: 'Live Updates', + collapsed: true, + autogenerate: { directory: 'docs/live-updates' }, }, { label: 'General Information', @@ -95,6 +117,7 @@ export default defineConfig({ }, { label: 'Plugin', + collapsed: true, items: [ { label: 'Overview', link: '/docs/plugin/overview' }, { @@ -135,18 +158,6 @@ export default defineConfig({ }, ], }, - { - label: 'CLI', - collapsed: true, - items: [ - { label: 'Commands', link: '/docs/cli/commands' }, - { - label: 'Migrations', - collapsed: true, - autogenerate: { directory: 'docs/cli/migrations' }, - }, - ], - }, { label: 'Public API', collapsed: true, diff --git a/src/content/docs/docs/cli/overview.mdx b/src/content/docs/docs/cli/overview.mdx new file mode 100644 index 00000000..a543d905 --- /dev/null +++ b/src/content/docs/docs/cli/overview.mdx @@ -0,0 +1,6 @@ +--- +title: Overview +draft: true +--- + +Overview diff --git a/src/content/docs/docs/getting-started/add-an-app.mdx b/src/content/docs/docs/getting-started/add-an-app.mdx new file mode 100644 index 00000000..b7d94623 --- /dev/null +++ b/src/content/docs/docs/getting-started/add-an-app.mdx @@ -0,0 +1,42 @@ +--- +title: "Add an App" +description: "Add an app to your Capgo account, and install the plugin in your app" +sidebar: + order: 2 +--- + +import { YouTube } from 'astro-embed'; +import { Aside } from '@astrojs/starlight/components'; + +## Introduction to Capgo + + +## Live updates are 3 step away + +### Create your account + +Visit our registration page at [https://web.capgo.app/register](https://web.capgo.app/register). + +![onboarding screenshot](/onboard.webp "onboarding screenshot") + +### Install capgo with the CLI + +Use the Magic commands to get started + +```bash +npx @capgo/cli@latest init [APIKEY] +``` + +This command will guide you through the setup process. + +### Simply follow the prompts + +In the CLI, you will be presented with a series of questions. Provide the necessary answers to complete the automated setup. + + + +### Enjoy the magic of Capgo! + +Test your app and learn later on how to use power features of Capgo. diff --git a/src/content/docs/docs/getting-started/deploy.mdx b/src/content/docs/docs/getting-started/deploy.mdx new file mode 100644 index 00000000..3ffbffd1 --- /dev/null +++ b/src/content/docs/docs/getting-started/deploy.mdx @@ -0,0 +1,83 @@ +--- +title: Deploy a Live Update +sidebar: + order: 3 +--- +import { Steps } from '@astrojs/starlight/components'; + +Use Capgo's Live Updates feature to update the UI and business logic of your app remotely, in real-time. Push JS bundle updates directly to your users without going through the app store to instantly fix bugs and ship new features. + +This guide assumes you've completed the [Capgo Quickstart](/docs/getting-started/quickstart) and have already: + + + +1. Installed the `@capgo/capacitor-updater` SDK in your Capacitor app + +2. Configured your app ID and update channel in `capacitor.config.ts` + +3. Added in your code the `CapacitorUpdater.notifyAppReady()` method + + + +If you haven't done those steps yet, please go back and complete the quickstart first. + +## Uploading a Bundle + +With the Capgo SDK installed and configured, you're ready to upload your first live update bundle: + +1. Build your web assets: + ```shell + npm run build + ``` + +2. Upload the bundle to Capgo: + ```shell + npx @capgo/cli@latest upload --channel=Production + ``` + This will upload a new bundle version to the channel specified in the command. + +### Troubleshooting Uploads + +If your upload fails, double check: +- Your app ID in `capacitor.config.ts` matches your app in the Capgo dashboard +- You're running the upload command from the root of your Capacitor project +- Your web assets are built and up to date + +If you're still having trouble, try running with the `--tus` flag if you have low internet connection or big bundles, or reach out to Capgo support. + +## Receiving an Update on a Device + +Once your bundle is uploaded, you can test the live update on a device: + +1. Sync your app to the device: + ```shell + npx cap sync ios + ``` + +2. Open another terminal and run the following command to check the update status: + ```shell + npx @capgo/cli@latest app debug + ``` + +3. Run your app locally: + ```shell + npx cap run ios + ``` + Or open the iOS/Android project in Xcode/Android Studio and do a native run. + +4. Keep the app open for about 30 seconds to allow the update to download in the background. + +5. The logs will take a few seconds to update and show the update status. + +6. Close and reopen the app. You should see your live update applied! + +Refer back to the [Capgo Quickstart](/docs/getting-started/quickstart#receiving-a-live-update-on-a-device) for more details on testing live updates. + +## Next Steps + +Congrats on deploying your first live update with Capgo! 🎉 + +To learn more, review the rest of the [Capgo Live Updates documentation](/docs/live-updates). Some key topics to check out next: +- [Targeting Updates with Channels](/docs/live-updates/channels) +- [Customizing Update Behavior](/docs/live-updates/update-behavior) +- [Live Update Rollbacks](/docs/live-updates/rollbacks) diff --git a/src/content/docs/docs/getting-started/quickstart.mdx b/src/content/docs/docs/getting-started/quickstart.mdx new file mode 100644 index 00000000..e206bcc4 --- /dev/null +++ b/src/content/docs/docs/getting-started/quickstart.mdx @@ -0,0 +1,47 @@ +--- +title: Overview +sidebar: + order: 1 +next: false +prev: false +--- + +import { Card, CardGrid, Steps } from '@astrojs/starlight/components'; + + +The quickstart tutorial will walk you through the key concepts of Capgo! Concepts that will be explored include: + + + +1. Adding an app to your Capgo account + +2. Integrating Capgo with your CI/CD + +3. Triggering bundle upload on Capgo by pushing commits + +4. Configuring and customizing the Capgo bundle publishing + +5. Setting up your app to enable live updates via Capgo + +6. Deploying live updates to your app from Capgo + + + +Simply follow the guide step-by-step, or navigate directly to the documentation for the component that interests you. + + + + + Follow the quickstart tutorial and get up and running with Capgo in no time! + + + Integrate Capgo with your CI/CD and trigger bundle uploads on Capgo by pushing commits. + + + Update your app remotely in real-time without app store delays. + + + Common issues and how to solve them. + + + diff --git a/src/content/docs/docs/getting-started/troubleshooting.mdx b/src/content/docs/docs/getting-started/troubleshooting.mdx new file mode 100644 index 00000000..23b4ff09 --- /dev/null +++ b/src/content/docs/docs/getting-started/troubleshooting.mdx @@ -0,0 +1,124 @@ +--- +title: Troubleshooting +sidebar: + order: 5 +next: false +prev: false +--- + +Here are some common issues you might encounter while using Capgo and how to resolve them. + +## Live Updates + +### Debugging Updates + +If you're encountering issues with live updates, the Capgo debug command is a helpful tool for troubleshooting. To use it: + +1. Run the following command in your project directory: + ```shell + npx @capgo/cli@latest app debug + ``` + +2. Launch your app on a device or emulator and perform the action that should trigger an update (e.g. reopening the app after uploading a new bundle). + +3. Watch the output of the debug command. It will log information about the update process, including: + - When the app checks for an update + - If an update is found and what version it is + - Download and installation progress for the update + - Any errors that occur during the update process + +4. Use the debug logs to identify where the issue is occurring. For example: + - If no update is found, double check that your bundle was uploaded successfully and the app is configured to use the correct channel. + - If the update downloads but doesn't install, make sure you've called `CapacitorUpdater.notifyAppReady()` and that the app was fully closed and reopened. + - If you see an error message, look up that specific error in the Capgo docs or reach out to support for help. + +The debug command is especially useful for identifying issues with the update download and installation process. If the logs show the expected update version was found but not ultimately applied, focus your troubleshooting on the steps after the download. + +### Debugging with Native Logs + +In addition to the Capgo debug command, the native logs on Android and iOS can provide valuable troubleshooting information, especially for issues on the native side of the update process. + +#### Android Logs + +To access the Android logs: + +1. Connect your device or start your emulator +2. Open Android Studio and select "View > Tool Windows > Logcat" +3. In the Logcat window, filter the logs to just your app's process by selecting it from the dropdown at the top +4. Look for any lines that include `Capgo` to find the SDK logs + +Alternatively, you can use the `adb logcat` command and grep for `Capgo` to filter the logs. + +The Capgo SDK will log key events during the update process, such as: +- When an update check is initiated +- If an update is found and what version it is +- When the update download starts and completes +- When the update installation is triggered +- Any errors that occur during the native update steps + +Common Android-specific issues you might see in the logs include: +- Network connectivity problems preventing the update download +- File permissions errors when saving or reading the update bundle +- Out of storage space for the update bundle +- Failure to restart the app after the update is installed + +#### iOS Logs + +To access the iOS logs: + +1. Connect your device or start your simulator +2. Open Xcode and go to "Window > Devices and Simulators" +3. Select your device and click on "Open Console" +4. In the console output, look for any lines that include `Capgo` to find the SDK logs + +You can also use the `log stream` command in the terminal and grep for `Capgo` to filter the logs. + +Similar to Android, the Capgo SDK will log key iOS-side events: +- Update check initiation and result +- Download start, progress, and completion +- Installation trigger and result +- Any errors during the native update process + +iOS-specific issues you might identify in the logs include: +- SSL certificate problems when downloading the update +- App transport security blocking the update download +- Insufficient storage space for the update bundle +- Failure to properly extract or apply the update bundle + +On both platforms, the native logs provide a lower-level view into the update process, with more details on the native implementation. They are especially useful for identifying issues that occur outside of the Capgo JavaScript layer. + +When troubleshooting a tricky live update problem, it's a good idea to capture both the Capgo debug logs and the native logs for a comprehensive picture of what's happening. The two logs together will give you the best chance of identifying and resolving the issue. + +### Upload failures + +If your bundle upload fails, double check: +- Your app ID in `capacitor.config.ts` matches your app in the Capgo dashboard +- You're running the upload command from the root of your Capacitor project +- Your web assets are built and up to date + +If you're still having trouble, try running with the `--tus` flag if you have low internet connection or big bundles, or reach out to Capgo support. + +### Updates not applying + +If you've uploaded a bundle but aren't seeing the changes on your device: +- Make sure you've called `CapacitorUpdater.notifyAppReady()` in your app code as shown in the [quickstart](/docs/getting-started/quickstart) +- Check that your device is connected to the internet and the Capgo debug logs show the update was downloaded +- Try fully closing and reopening the app, as updates are only applied on a fresh launch +- Look for any errors in the native logs that might indicate a problem applying the update + +Refer to the [deploying live updates](/docs/getting-started/deploy) guide for more details on the update process. If you're still stuck, use the `npx @capgo/cli@latest app debug` command and native logs to get more visibility into what's happening. + +## SDK Installation + +If you're having trouble installing the Capgo SDK, make sure: +- Your app is using a supported version of Capacitor (4.0 or newer) +- You've followed the [quickstart](/docs/getting-started/quickstart) steps in order, including syncing your app after installing the SDK + +## CI/CD Integration + +For issues with triggering Capgo uploads from your CI/CD pipeline: +- Double check your Capgo authentication token is set up correctly +- Make sure you're running the upload command after your web assets are built +- Check that the upload command is using the correct channel name for your target environment + +See the [CI/CD integration](/docs/cicd-integration) docs for more troubleshooting tips. You can also use the `npx @capgo/cli@latest app debug` command to confirm if your CI/CD-triggered updates are being received by the app. diff --git a/src/content/docs/docs/getting-started/wrapping-up.mdx b/src/content/docs/docs/getting-started/wrapping-up.mdx new file mode 100644 index 00000000..4d3116d7 --- /dev/null +++ b/src/content/docs/docs/getting-started/wrapping-up.mdx @@ -0,0 +1,52 @@ +--- +title: Wrapping up +sidebar: + order: 4 +next: false +prev: false +draft: true +--- + +import { Card, CardGrid, Steps } from '@astrojs/starlight/components'; + +Now that you have completed the quickstart guide, you should have a basic understanding of the key concepts of Capgo! The key concepts you have learned in this guide are: + + +1. Adding an app to your Capgo account + +2. Integrating Capgo with your CI/CD pipeline + +3. Triggering bundle uploads to Capgo on new commits + +4. Configuring your app to enable live updates with the Capgo SDK + +5. Deploying live updates to your app from the Capgo dashboard + + +But there's still more to learn about Capgo! Continue exploring the docs or check out some of these key topics: + + + + + Already have a CI/CD pipeline? Learn how to incorporate Capgo into your existing workflow. + + + + + + Dive deeper into Capgo's live update features and best practices. + + + + + + Find answers to common questions about Capgo. + + + + + + Get help with common issues that can come up while using Capgo. + + + diff --git a/src/content/docs/docs/how-to.mdx b/src/content/docs/docs/how-to.mdx index 8a0005cf..ff928ee0 100644 --- a/src/content/docs/docs/how-to.mdx +++ b/src/content/docs/docs/how-to.mdx @@ -1,6 +1,6 @@ --- title: "How to" -description: "How to use Capgo, turotials, tips and tricks" +description: "How to use Capgo, tutorials, tips and tricks" sidebar: order: 1 --- diff --git a/src/content/docs/docs/index.mdx b/src/content/docs/docs/index.mdx index af78cdb6..51aff815 100644 --- a/src/content/docs/docs/index.mdx +++ b/src/content/docs/docs/index.mdx @@ -9,11 +9,11 @@ hero: file: /logo.svg actions: - text: Get started - link: /docs/plugin/cloud-mode/getting-started/ + link: /docs/getting-started/quickstart/ icon: right-arrow variant: primary - text: Github - link: https://github.com/Cap-go/Capgo + link: https://github.com/Cap-go/Capgo/ icon: external variant: minimal --- diff --git a/src/content/docs/docs/live-updates/channels.mdx b/src/content/docs/docs/live-updates/channels.mdx new file mode 100644 index 00000000..7a2d1322 --- /dev/null +++ b/src/content/docs/docs/live-updates/channels.mdx @@ -0,0 +1,80 @@ +--- +title: Channels +draft: true +--- + +A Live Update channel points to a specific JS bundle build of your app that will be shared with any devices configured to listen to that channel for updates. When you [install the Capgo Live Updates SDK](/docs/getting-started/quickstart) in your app, any native binary configured to that channel will check for available updates whenever the app is launched. You can change the build a channel points to at any time and can also roll back to previous builds if needed. + +## Setting up a Channel + +Every app comes with a default channel called "Production" that cannot be deleted. To add new channels: + +1. Go to the "Channels" section of the Capgo dashboard +2. Click the "New Channel" button +3. Enter a name for the channel and click "Create" + +Channel names can be anything you'd like. A common strategy is to match channels to your development stages, such as: + +- `Development` - for testing live updates on local devices or emulators +- `QA` - for your QA team to verify updates before wider release +- `Staging` - for final testing in a production-like environment +- `Production` - for the version of your app that end users receive from the app stores + +## Configuring the Channel in Your App + +With your channels created, you need to configure your app to listen to the appropriate channel. In this example, we'll use the `Development` channel. + +Open your `capacitor.config.ts` (or `capacitor.config.json`) file. Under the `plugins` section, set the `channel` property of the `CapacitorUpdater` plugin to the name of your desired channel: + +```ts +import { CapacitorConfig } from '@capacitor/cli'; + +const config: CapacitorConfig = { + plugins: { + CapacitorUpdater: { + channel: 'Development', + }, + }, +}; +``` + +Next, build your web app and run `npx cap sync` to copy the updated config file to your iOS and Android projects. If you skip this sync step, your native projects will continue to use whichever channel they were previously configured for. + +## Assigning a Build to a Channel + +To deploy a live update, you need to upload a new JS bundle build and assign it to a channel. You can do this in one step with the Capgo CLI: + +```shell +npx @capgo/cli@latest upload --channel=Development +``` + +This will upload your built web assets and set the new bundle as the active build for the `Development` channel. Any apps configured to listen to that channel will receive the update the next time they check for one. + +You can also assign builds to channels from the "Builds" section of the Capgo dashboard. Click the menu icon next to a build and select "Assign to Channel" to choose the channel for that build. + +## Rolling Back a Live Update + +If you deploy a live update that introduces a bug or otherwise needs to be reverted, you can easily roll back to a previous build. From the "Channels" section of the dashboard: + +1. Click the name of the channel you want to roll back +2. Find the build you want to revert to and click "Roll Back to Here" +3. Confirm the action + +The selected build will immediately become the active build for that channel again. Apps will receive the rolled back version the next time they check for an update. + +## Automating Deployments + +For more advanced workflows, you can automate your live update deployments as part of your CI/CD pipeline. By integrating Capgo into your build process, you can automatically upload new bundles and assign them to channels whenever you push to certain branches or create new releases. + +Check out the [CI/CD Integration](/docs/cicd-integration) docs to learn more about automating Capgo live updates. + +## Deploying to a Device + +Now that you understand channels, you're ready to start deploying live updates to real devices. The basic process is: + +1. Install the Capgo SDK in your app +2. Configure the app to listen to your desired channel +3. Upload a build and assign it to that channel +4. Launch the app and wait for the update! + +For a more detailed walkthrough, see the [Deploying Live Updates](/docs/getting-started/deploy) guide. Happy updating! diff --git a/src/content/docs/docs/live-updates/differentials.mdx b/src/content/docs/docs/live-updates/differentials.mdx new file mode 100644 index 00000000..bef07b33 --- /dev/null +++ b/src/content/docs/docs/live-updates/differentials.mdx @@ -0,0 +1,4 @@ +--- +title: Differentials +draft: true +--- diff --git a/src/content/docs/docs/live-updates/index.mdx b/src/content/docs/docs/live-updates/index.mdx new file mode 100644 index 00000000..3d4d7b01 --- /dev/null +++ b/src/content/docs/docs/live-updates/index.mdx @@ -0,0 +1,77 @@ +--- +title: Overview +sidebar: + order: 1 +prev: false +draft: true +--- + +import { Steps, CardGrid, Card, Aside } from '@astrojs/starlight/components'; + +Use Capgo's Live Updates feature to update the JavaScript bundles of your app remotely, in real-time. Push JS updates directly to your users without going through the app store review process to instantly fix bugs and ship new features. + + + +## How Live Updates Work + +Capgo's Live Update system has two key components: + +1. The Capgo SDK, which you install in your app. The SDK checks for available updates and downloads them in the background. + +2. Channels, which let you target updates to specific groups of users. You can use channels to manage different release tracks, such as `Production`, `Staging`, and `Dev`. + +When you upload a new JS bundle to Capgo and assign it to a channel, the Capgo SDK in apps configured for that channel will detect the update and download it. The next time the app restarts, the new bundle will be loaded. + +## Getting Started + +To start using Live Updates, follow these steps: + + + +1. Complete the [Capgo Quickstart](/docs/getting-started/quickstart) to set up your app in Capgo and install the Capgo SDK. + +2. In your app code, call `CapacitorUpdater.notifyAppReady()` after your app has finished initializing. This tells the Capgo SDK that your app is ready to receive updates. + +3. Build your JS bundle and upload it to Capgo: + ```shell + npm run build + npx @capgo/cli@latest upload --channel=Production + ``` + +4. Open your app and wait for the update to download. You can check the status with: + ```shell + npx @capgo/cli@latest app debug + ``` + +5. Once the update is downloaded, close and reopen your app to load the new bundle. + + + +See the [Deploying Live Updates](/docs/getting-started/deploy) guide for more details. + + +## Next Steps + + + + + Learn how to use channels to manage different release tracks and target updates to specific users. + + + + + + Discover how to roll back to a previous JS bundle version if an update causes issues. + + + + + + Customize how and when updates are downloaded and applied in your app. + + + diff --git a/src/content/docs/docs/live-updates/rollbacks.mdx b/src/content/docs/docs/live-updates/rollbacks.mdx new file mode 100644 index 00000000..de946352 --- /dev/null +++ b/src/content/docs/docs/live-updates/rollbacks.mdx @@ -0,0 +1,6 @@ +--- +title: Rollbacks +draft: true +--- + +Rollbacks diff --git a/src/content/docs/docs/live-updates/update-behavior.mdx b/src/content/docs/docs/live-updates/update-behavior.mdx new file mode 100644 index 00000000..80cb138b --- /dev/null +++ b/src/content/docs/docs/live-updates/update-behavior.mdx @@ -0,0 +1,7 @@ +--- +title: Update Behavior +draft: true +--- + +Update Behavior + diff --git a/src/css/global.css b/src/css/global.css index 4c321e86..66f0b539 100644 --- a/src/css/global.css +++ b/src/css/global.css @@ -33,8 +33,3 @@ html.dark { .calc-label { @apply mt-0 mt-5 text-sm font-bold uppercase tracking-widest; } - -.content-panel ul, -.content-panel ol { - list-style: unset !important; -}