diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dbd9abf..d5f192c 100644 --- a/.pre-commit-config.yaml +++ b/.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" diff --git a/docs/install/index.md b/docs/install/index.md index 9d76fe2..0cc1593 100644 --- a/docs/install/index.md +++ b/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: ``" 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://.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"