Repository navigation
docs: Add an App publishing page for Serverpod Cloud #922
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
8e886d8
docs: Add an App publishing page for Serverpod Cloud
Crazelu d365f4f
docs: Say that app doctor checks for the debug key
Crazelu 5870249
docs: Add the Limits section to the App publishing page
Crazelu 64748aa
docs: Drop the manual first Android build from the App publishing page
Crazelu 939dbb3
docs: Unlist the App publishing page until launch
Crazelu 29e6b61
docs: Apply review wording to the App publishing page
Crazelu 62d78b5
docs: Move the app settings in scloud.yaml under project.app
Crazelu f3a0823
docs: Add app setup to the App publishing page
Crazelu ad1e855
docs: Document dart defines for app publish
Crazelu b2feefc
docs: Count monthly app builds per project
Crazelu 8549a51
docs: Document the app settings in the scloud.yaml schema
Crazelu 7bcb01f
chore: list app publishing in sidebar
Crazelu File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,274 @@ | ||
| --- | ||
| sidebar_position: 11 | ||
| description: Serverpod Cloud builds your Flutter app and uploads it to TestFlight and Google Play. Set up the app with app setup, check it with app doctor, then publish from the CLI. | ||
| --- | ||
|
|
||
| # App publishing | ||
|
|
||
| Getting a Flutter app to testers means signing builds, matching store settings, and uploading to TestFlight and Google Play. With app publishing, you run one command: Serverpod Cloud builds your Flutter app for iOS and Android, signs it, and uploads it to the stores you connected in the console. | ||
|
|
||
| You publish from the Cloud CLI. The `app setup` command prepares your Flutter app for the stores, and the `app doctor` command checks your app's setup before you publish and tells you how to fix each problem it finds. | ||
|
|
||
| ## What app publishing does | ||
|
|
||
| App publishing supports two platforms: | ||
|
|
||
| <div className="full-width-table"> | ||
|
|
||
| | Platform | Store | Where each build lands | | ||
| | -------- | ----------- | --------------------------------------------- | | ||
| | iOS | App Store | TestFlight, ready for your testers | | ||
| | Android | Google Play | A draft release on the internal testing track | | ||
|
|
||
| </div> | ||
|
|
||
| When you publish, the CLI uploads your Flutter app's source code. Serverpod Cloud builds it in release mode on its own build machines, with the Flutter version you choose. It then signs each build and uploads it to the store. You don't need Xcode, Android Studio, or a Mac to publish. | ||
|
|
||
| Releasing a build from TestFlight or the internal testing track to the public store stays in App Store Connect and Play Console. | ||
|
|
||
| ## Connect the stores | ||
|
|
||
| Before you can publish for a platform, connect its store in the [Serverpod Cloud console](https://console.serverpod.dev). Open your project, then open the **App Stores** tab. Each store has a setup guide that walks you through the steps: | ||
|
|
||
| - **App Store:** Join the Apple Developer Program, register your app's bundle ID, create the app in App Store Connect, and add an App Store Connect API key. Only the project owner can add the key. | ||
| - **Google Play:** Sign up for Play Console, create the app with your app's package name, choose an upload key, and invite Serverpod Cloud's service account to your app in Play Console. Serverpod Cloud can create the upload key for you, or you can upload the keystore you already sign the app with. | ||
|
|
||
| The `app doctor` command shows whether each connection is complete, and links to the setup guide when it isn't. | ||
|
|
||
| ## Set up your app | ||
|
|
||
| Run `app setup` from your project's directory to prepare your Flutter app for the stores: | ||
|
|
||
| ```bash | ||
| serverpod cloud app setup | ||
| ``` | ||
|
|
||
| For each platform, the command checks the [app identifier](#app-identifiers). If your app still uses Flutter's `com.example` placeholder, it asks for a new identifier and writes it into your app's files. It then saves the identifier to your Serverpod Cloud project. For Android, it also checks the [release signing](#android-release-signing). | ||
|
|
||
| To set the identifiers without a prompt, such as in CI, pass them as options: | ||
|
|
||
| ```bash | ||
| serverpod cloud app setup --non-interactive --android-package-name com.yourcompany.yourapp --ios-bundle-id com.yourcompany.yourapp | ||
| ``` | ||
|
|
||
| Pass `--platforms ios` or `--platforms android` to set up one platform, and `--app-dir` to set up an app somewhere else. | ||
|
|
||
| ## Check your app with app doctor | ||
|
|
||
| Run `app doctor` from your project's directory before you publish: | ||
|
|
||
| ```bash | ||
| serverpod cloud app doctor | ||
| ``` | ||
|
|
||
| It checks the Flutter version, each store connection, and the setup of your Flutter app: | ||
|
|
||
| ```text | ||
| ! Flutter version: Not pinned, so builds use the latest stable release. | ||
| Request a version with --flutter-version, or pin one in environment.flutter of the app's pubspec.yaml. | ||
|
|
||
| Android | ||
| ✓ Google Play Console connection | ||
| ✓ Package name: com.acme.app | ||
| ✗ Release signing: Release builds do not use the keystore from Serverpod Cloud. | ||
| Learn more: https://docs.serverpod.dev/cloud/concepts/app-publishing#android-release-signing | ||
| ! App icon: The app uses the default Flutter icon. | ||
| Learn more: https://docs.serverpod.dev/cloud/concepts/app-publishing#app-icon | ||
|
|
||
| iOS | ||
| ✓ App Store connection | ||
| ✓ Bundle ID: com.acme.app | ||
| ✓ Export compliance | ||
| ✓ App icon | ||
|
|
||
| 1 check failed. Fix it before you publish the app. | ||
| ``` | ||
|
|
||
| A check marked `✗` makes the build or the upload fail, so fix it before you publish. A check marked `!` is a warning: the app can be published, but the result may not be what you want. | ||
|
|
||
| The command finds your Flutter app from `project.app.dir` in `scloud.yaml`, the current directory, or your server's workspace. Pass `--app-dir` to check an app somewhere else, and `--platforms ios` or `--platforms android` to check one platform. | ||
|
|
||
| ## Publish your app | ||
|
|
||
| Publish your app from your project's directory: | ||
|
|
||
| ```bash | ||
| serverpod cloud app publish | ||
| ``` | ||
|
|
||
| The command builds every platform your app has code for and whose store is connected. It skips a platform whose store isn't connected and prints a link to its setup guide. It shows the progress of each build and ends when the builds are uploaded to the stores. To publish one platform, pass `--platforms`: | ||
|
|
||
| ```bash | ||
| serverpod cloud app publish --platforms ios | ||
| ``` | ||
|
|
||
| To start the builds and return right away, pass `--no-await`. The command then prints the `app show` command that follows the builds. | ||
|
|
||
| If your Flutter app is part of a Dart workspace, the upload includes the workspace packages it depends on. To leave files out of the upload, list them in a [`.scloudignore` file](/cloud/concepts/deployments#configure-whats-included). | ||
|
|
||
| ### Dart defines | ||
|
|
||
| To build your app with compile-time values, pass them as with `flutter build`. Use `--dart-define` for one value, and `--dart-define-from-file` for a file in JSON or `.env` format: | ||
|
|
||
| ```bash | ||
| serverpod cloud app publish --dart-define-from-file .env --dart-define FLAVOR=production | ||
| ``` | ||
|
|
||
| You can repeat both options. A later file replaces the values of an earlier one, and a `--dart-define` value replaces the value of the same key from a file. | ||
|
|
||
| To build every publish with the same files, set `dartDefineFromFile` in `scloud.yaml` to a path or a list of paths, relative to `scloud.yaml`. The `--dart-define-from-file` option replaces this setting: | ||
|
|
||
| ```yaml title="scloud.yaml" | ||
| project: | ||
| projectId: my-project | ||
| app: | ||
| dartDefineFromFile: .env | ||
| ``` | ||
|
|
||
| Serverpod Cloud always sets `SERVER_URL` to the URL of your project's server, so `getServerUrl` from `serverpod_flutter` connects the app to it. A `SERVER_URL` value you pass is ignored. | ||
|
|
||
| ## Follow your builds | ||
|
|
||
| Each publish creates an app upload with one build per platform. The upload ID that `app publish` and `app list` print identifies it. Use these commands to follow the builds: | ||
|
|
||
| <div className="full-width-table"> | ||
|
|
||
| | Command | What it shows | | ||
| | ------------------------------------------- | ------------------------------------------------------------ | | ||
| | `serverpod cloud app list` | Recent publishes, newest first | | ||
| | `serverpod cloud app status` | The latest build of each platform with a connected store | | ||
| | `serverpod cloud app show <upload-id>` | The builds of one upload, followed until they end | | ||
| | `serverpod cloud app log <upload-id>` | The build log of one platform, followed until the build ends | | ||
| | `serverpod cloud app artifacts <upload-id>` | Download links for the built files, valid for ten minutes | | ||
| | `serverpod cloud app cancel <upload-id>` | Cancels the builds of an upload that are still running | | ||
|
|
||
| </div> | ||
|
|
||
| When a build fails, `app show` and `app status` print the `app log` command that shows why. | ||
|
|
||
| ## Setup requirements | ||
|
|
||
| These are the parts of your Flutter app that `app doctor` checks. Each one has a section below. | ||
|
|
||
| ### Flutter version {#flutter-version} | ||
|
|
||
| Serverpod Cloud builds your app with the first Flutter version it finds, in this order: | ||
|
|
||
| 1. The `--flutter-version` option of `app publish`, such as `--flutter-version 3.50.0`. | ||
| 2. A single version in `environment.flutter` of your app's `pubspec.yaml`. | ||
| 3. `project.app.flutterSdk` in `scloud.yaml`. | ||
| 4. The version of the Flutter SDK on your computer. | ||
| 5. The latest stable release. | ||
|
|
||
| If none of the first three sets a version, the build uses the Flutter SDK on the computer you publish from. To build every publish with the same version, set it in your app's `pubspec.yaml`: | ||
|
|
||
| ```yaml title="pubspec.yaml" | ||
| environment: | ||
| sdk: ^3.8.0 | ||
| flutter: 3.50.0 | ||
| ``` | ||
|
|
||
| The version must be a Flutter release version, and it can't be lower than the Flutter version your app's `pubspec.lock` requires. When `app doctor` warns that the version isn't pinned, the builds use the latest stable release, which can change between two publishes. | ||
|
|
||
| ### App identifiers {#app-identifiers} | ||
|
|
||
| The stores identify your app by its bundle ID on iOS and its package name on Android. Serverpod Cloud reads them from your Flutter app: the bundle ID from the Xcode project in `ios/`, and the package name from `applicationId` in `android/app/build.gradle.kts` or `build.gradle`. | ||
|
|
||
| A new Flutter app uses a `com.example` placeholder, which the stores don't accept. Replace it with your own identifier, such as `com.yourcompany.yourapp`, in both places. The [`app setup`](#set-up-your-app) command does this for you. The identifier must match the app you created in App Store Connect and Play Console. | ||
|
|
||
| To publish with a different identifier than the one in your app's files, set it in `scloud.yaml`: | ||
|
|
||
| ```yaml title="scloud.yaml" | ||
| project: | ||
| projectId: my-project | ||
| app: | ||
| identifiers: | ||
| ios: com.yourcompany.yourapp | ||
| android: com.yourcompany.yourapp | ||
| ``` | ||
|
|
||
| ### Android release signing {#android-release-signing} | ||
|
|
||
| Google Play only accepts builds signed with your app's upload key. Serverpod Cloud stores that key and passes it to each Android build through these environment variables: | ||
|
|
||
| <div className="full-width-table"> | ||
|
|
||
| | Variable | Value | | ||
| | --------------------------- | ------------------------------------ | | ||
| | `ANDROID_KEYSTORE_PATH` | The path of the upload keystore file | | ||
| | `ANDROID_KEYSTORE_PASSWORD` | The password of the keystore | | ||
| | `ANDROID_KEY_ALIAS` | The alias of the upload key | | ||
| | `ANDROID_KEY_PASSWORD` | The password of the upload key | | ||
|
|
||
| </div> | ||
|
|
||
| Your app's Gradle build file must read these variables and sign release builds with them. A new Flutter app signs release builds with the debug key instead, which Google Play rejects. | ||
|
|
||
| Add a `release` signing config to `android/app/build.gradle.kts` that reads the variables, and use it for release builds: | ||
|
|
||
| ```kotlin title="android/app/build.gradle.kts" | ||
| android { | ||
| // ... | ||
|
|
||
| val isServerpodCloudBuild = System.getenv("SERVERPOD_APP_BUILD") != null | ||
|
|
||
| signingConfigs { | ||
| if (isServerpodCloudBuild) { | ||
| create("release") { | ||
| storeFile = file(System.getenv("ANDROID_KEYSTORE_PATH")) | ||
| storePassword = System.getenv("ANDROID_KEYSTORE_PASSWORD") | ||
| keyAlias = System.getenv("ANDROID_KEY_ALIAS") | ||
| keyPassword = System.getenv("ANDROID_KEY_PASSWORD") | ||
| } | ||
| } | ||
| } | ||
|
|
||
| buildTypes { | ||
| release { | ||
| signingConfig = if (isServerpodCloudBuild) { | ||
| signingConfigs.getByName("release") | ||
| } else { | ||
| signingConfigs.getByName("debug") | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Serverpod Cloud sets `SERVERPOD_APP_BUILD` on its builds, so release builds on your computer keep using the debug key. Apps created with `serverpod create` in Serverpod 4.1.2 or later already include this setup. | ||
|
|
||
| The `app doctor` command checks that your release build type doesn't sign with the debug key alone, and that your Gradle build file names all four variables. You can read them in any way Gradle supports, such as `providers.environmentVariable("ANDROID_KEY_ALIAS")` or, in a Groovy `build.gradle`, `System.getenv('ANDROID_KEY_ALIAS')`. | ||
|
|
||
| ### iOS export compliance {#ios-export-compliance} | ||
|
|
||
| App Store Connect asks whether each build uses encryption, because apps that use some kinds of encryption need export compliance documentation. Until a build answers it, App Store Connect holds the build and your testers can't install it. | ||
|
|
||
| Answer it once in your app's `ios/Runner/Info.plist`, inside the top-level `<dict>`. If your app uses no encryption, or only encryption that is exempt, such as HTTPS calls to your server, set `ITSAppUsesNonExemptEncryption` to `false`: | ||
|
|
||
| ```xml title="ios/Runner/Info.plist" | ||
| <key>ITSAppUsesNonExemptEncryption</key> | ||
| <false/> | ||
| ``` | ||
|
|
||
| If your app uses encryption that isn't exempt, set it to `<true/>` and provide the documentation in App Store Connect. Apple's [ITSAppUsesNonExemptEncryption reference](https://developer.apple.com/documentation/bundleresources/information-property-list/itsappusesnonexemptencryption) explains which encryption is exempt. | ||
|
|
||
| ### App icon {#app-icon} | ||
|
|
||
| A new Flutter app has the Flutter logo as its icon. Testers see this icon on their home screen, and the stores show it on your app's listing. The `app doctor` command warns while your app still has it. | ||
|
|
||
| Replace the icon files on each platform: | ||
|
|
||
| - **Android:** The `ic_launcher.png` files in the `mipmap-*` folders of `android/app/src/main/res`. | ||
| - **iOS:** The images in `ios/Runner/Assets.xcassets/AppIcon.appiconset`. | ||
|
|
||
| Each platform needs the icon in several sizes. A package such as [flutter_launcher_icons](https://pub.dev/packages/flutter_launcher_icons) creates every size for both platforms from one image. | ||
|
|
||
| ## Limits | ||
|
|
||
| - **Platforms:** App publishing builds for iOS and Android only. | ||
| - **Monthly builds:** Your plan sets how many times you can publish each project per month. A publish counts once one of its builds succeeds, however many platforms it builds for, so a publish where every build fails doesn't count. The count resets on the first of each month, in UTC. | ||
|
|
||
| ## Related | ||
|
|
||
| - [Deployments](/cloud/concepts/deployments): how to deploy the server your app talks to. | ||
| - [scloud.yaml schema](/cloud/reference/scloud-yaml-schema): the project configuration file the `app` commands read. | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.