From 3e50566105bcf09061b1c87a6f32282082078620 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Mon, 1 Dec 2025 16:06:13 -0500 Subject: [PATCH 1/5] docs: add details for Firebase projects when deploying --- docs/install/index.md | 73 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) diff --git a/docs/install/index.md b/docs/install/index.md index 9d76fe2..5c1e765 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -39,6 +39,42 @@ 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. + +#### Creating 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 + ### Automated deployment We offer a semi-automated deployment via a [`copier`](https://copier.readthedocs.io/en/stable/) template. @@ -52,3 +88,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://.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" From 97663ec3ae9fd0b1651cf816838ac45911a7ec80 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 2 Dec 2025 12:13:37 -0500 Subject: [PATCH 2/5] more details --- .pre-commit-config.yaml | 14 ++++++++----- docs/install/index.md | 46 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 54 insertions(+), 6 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dbd9abf..c928396 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -84,11 +84,15 @@ 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"] + - id: check-jsonschema + name: "Validate devcontainer" + files: ^\.devcontainer/.*\.json$ + args: [ + "--schemafile", + "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json", + "--force-filetype", + "json5", + ] # waiting for custom YAML tags support: https://github.com/python-jsonschema/check-jsonschema/issues/489 # - id: check-jsonschema # name: "Validate MkDocs file" diff --git a/docs/install/index.md b/docs/install/index.md index 5c1e765..e4cad27 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -47,7 +47,7 @@ A compatible container engine that also has support for compose can also be used In addition, you need a Firebase project. -#### Creating a new 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). @@ -75,6 +75,50 @@ To create a dedicated service account, go to the [Service Accounts in Google Clo 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: ``" 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 -out apn.crt +# export private key +openssl pkcs12 -in Certificates.p12 -nodes -nocerts -out apn.key +``` + ### Automated deployment We offer a semi-automated deployment via a [`copier`](https://copier.readthedocs.io/en/stable/) template. From d18c68b797904f7b58dfed42bfc3bc8faabf4d48 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 2 Dec 2025 12:22:44 -0500 Subject: [PATCH 3/5] add missing dependency --- .pre-commit-config.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c928396..a240fd8 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -87,6 +87,7 @@ repos: - id: check-jsonschema name: "Validate devcontainer" files: ^\.devcontainer/.*\.json$ + additional_dependencies: ['json5'] args: [ "--schemafile", "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json", From 6b6fb6bd1a2f01a0714eff9be5f0eef95fe7f8ac Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 2 Dec 2025 12:32:57 -0500 Subject: [PATCH 4/5] disable it again --- .pre-commit-config.yaml | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a240fd8..d5f192c 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -84,16 +84,17 @@ repos: - id: check-renovate args: ["--verbose"] additional_dependencies: ['json5'] - - id: check-jsonschema - name: "Validate devcontainer" - files: ^\.devcontainer/.*\.json$ - additional_dependencies: ['json5'] - args: [ - "--schemafile", - "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.schema.json", - "--force-filetype", - "json5", - ] + # - id: check-jsonschema + # name: "Validate devcontainer" + # files: ^\.devcontainer/.*\.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" From 5bba0f9b9e44705feda1dfc4c3f9042d0547f9d5 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Tue, 2 Dec 2025 12:52:26 -0500 Subject: [PATCH 5/5] add legacy argument --- docs/install/index.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/install/index.md b/docs/install/index.md index e4cad27..0cc1593 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -114,11 +114,17 @@ To separate them, run the following we use `openssl` with the `pkcs12` command: ```console # export certificate -openssl pkcs12 -in Certificates.p12 -clcerts -nokeys -out apn.crt +openssl pkcs12 -in Certificates.p12 -clcerts -nokeys -legacy -out apn.crt # export private key -openssl pkcs12 -in Certificates.p12 -nodes -nocerts -out apn.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.