docs: add details for Firebase projects when deploying

.pre-commit-config.yaml

@@ -84,11 +84,17 @@ repos:
       - id: check-renovate
         args: ["--verbose"]
         additional_dependencies: ['json5']
-      # requires: https://github.com/python-jsonschema/check-jsonschema/issues/341
       # - id: check-jsonschema
       #   name: "Validate devcontainer"
       #   files: ^\.devcontainer/.*\.json$
-      #   args: ["--schemafile", "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json"]
+      #   additional_dependencies: ['json5']
+      #   args: [
+      #     "--schemafile",
+      #     "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json",
+      #     "--force-filetype",
+      #     "json5",
+      #     "--verbose",
+      #   ]
       # waiting for custom YAML tags support: https://github.com/python-jsonschema/check-jsonschema/issues/489
       # - id: check-jsonschema
       #   name: "Validate MkDocs file"

docs/install/index.md

@@ -39,6 +39,92 @@ The database server can also be run on a separate server:
 
 Relationships between components on the same host are left out for brevity (except those making use of third-party components).
 
+### Requirements
+
+You need at least one machine on which to deploy the Opal PIE.
+This machine needs to have the [Docker Engine](https://docs.docker.com/engine/) and [Docker Compose](https://docs.docker.com/compose/) installed.
+A compatible container engine that also has support for compose can also be used.
+
+In addition, you need a Firebase project.
+
+#### Create a new Firebase project
+
+If you don't have a Firebase project yet, [create a Firebase project](../development/local-dev-setup.md#create-a-new-firebase-project), [create a Realtime Database](../development/local-dev-setup.md#create-a-new-realtime-database), and [enable password-based authentication](../development/local-dev-setup.md#enable-email-and-password-authentication).
+
+#### Create a Firebase service account
+
+By default, Firebase creates a service account and API keys with excessive permissions.
+This is fine for development.
+However, it is not recommended for a production environment.
+
+To create a dedicated service account, go to the [Service Accounts in Google Cloud](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) and:
+
+1. Select your Firebase project
+1. Select "Create service account"
+1. Type in a display name and generate a service account ID
+1. Click "Create and continue"
+1. In the "Permissions" section, select the following roles:
+    - *Firebase Authentication Admin*
+    - *Firebase Cloud Messaging Admin*
+    - *Firebase Realtime Database Admin*
+    - *Firebase Rules Admin*
+1. Click "Continue"
+1. Click "Done"
+1. Click on the newly created service account
+1. Select "Keys", select "Add key", and then "Create new key"
+1. Choose key type "JSON" and click "Create"
+1. Store this file in a secure place for later
+
+#### Retrieve the Apple Push Notification certificates
+
+!!! note
+
+    These instructions are specific to *macOS* as they require the *Keychain Access* utility.
+
+While push notifications on Android are delivered via *Firebase Cloud Messaging*, on iOS the *Apple Push Notification Service* is used.
+
+The following instructions assume that your iOS app has already been created in [App Store Connect](https://appstoreconnect.apple.com/apps) and therefore has an *App ID*.
+
+!!! success "Preparation: Generate a *Certificate Signing Request*"
+
+    As a preparation, follow the instructions to [create a certificate signing request](https://developer.apple.com/help/account/certificates/create-a-certificate-signing-request).
+
+Log in to your [Apple Developer Account](https://developer.apple.com/account) and do the following:
+
+1. Under "Program resources" > "Certificates, IDs & Profiles", click "Certificates"
+1. Click the plus icon next to "Certificates"
+1. Under "Services", select "Apple Push Notification service SSL (Sandbox & Production)" and click "Continue"
+1. Select the App ID of your app and click "Continue"
+1. Upload your certificate signing request and click "Continue"
+1. Download your certificate
+
+You now have a `.cer` file which needs to be imported to the keychain so it can be exported as a PKCS #12 archive:
+
+1. Double-click the `.cer` file to add it to your keychain
+1. In *Keychain Access*, select the "login" keychain and look for the "Apple Push Services: `<appID>`" certificate
+1. Expand this certificate to reveal the private key entry
+1. Select both certificate and private key
+1. Right-click and select "Export 2 items..."
+1. Save the `.p12` file somewhere
+    - Leave the password empty
+    - Confirm the export with your password and selecting "Allow"
+
+The `Certificates.p12` file contains both the certificate and private key.
+To separate them, run the following we use `openssl` with the `pkcs12` command:
+
+```console
+# export certificate
+openssl pkcs12 -in Certificates.p12 -clcerts -nokeys -legacy -out apn.crt
+# export private key
+openssl pkcs12 -in Certificates.p12 -nodes -nocerts -legacy -out apn.key
+```
+
+!!! note "Note on OpenSSL version"
+
+    The above commands assume that you are using OpenSSL v3 which requires the `-legacy` flag.
+    This is because older algorithms like the one used by keychain when exporting the certificates are disabled by default.
+    If you are using OpenSSL v1.1, remove the `-legacy` flag from the commands.
+
 ### Automated deployment
 
 We offer a semi-automated deployment via a [`copier`](https://copier.readthedocs.io/en/stable/) template.
@@ -52,3 +138,40 @@ Please follow the instructions in the [`deploy-pie`](https://github.com/opalmeda
 
 ```plantuml source="docs/install/diagrams/deployment_diagram_user.puml"
 ```
+
+### Requirements
+
+#### Create or restrict Firebase API keys
+
+If you already [retrieved Firebase client configurations](../development/local-dev-setup.md#retrieve-the-firebase-project-configurations), then you do not need to create new API keys but can instead restrict the already generated ones.
+In that case, skip the create steps below and edit the exiting keys instead.
+
+Go to the [API Credentials in Google Cloud](https://console.cloud.google.com/apis/) and select the corresponding Firebase project.
+
+##### Browser key
+
+1. Click "Create credentials" and select "API Key"
+1. Give it a name, such as "Browser key"
+1. Under "Application restrictions", choose "Websites"
+1. Add the following websites at a minimum
+    - `app://localhost`
+    - `http://localhost`
+    - `https://<your-firebase-project-id>.firebaseapp.com`
+1. Under "API Restrictions", choose "Restrict key"
+1. Choose the following APIs
+    - *FCM Registration API*
+    - *Firebase Realtime Database Management API*
+    - *Identity Toolkit API*
+1. Click "Create"
+
+##### Android key
+
+1. Click "Create credentials" and select "API Key"
+1. Give it a name, such as "Android key"
+1. Under "API Restrictions", choose "Restrict key"
+1. Choose the following APIs
+    - *FCM Registration API*
+    - *Firebase Realtime Database Management API*
+    - *Identity Toolkit API*
+    - *Firebase Installations API*
+1. Click "Create"