Skip to content

Commit da80bb0

Browse files
mschoettlemschoettle
authored
docs: move firebase project setup into its dedicated page (#402)
1 parent dadc71c commit da80bb0

File tree

4 files changed

+189
-169
lines changed

4 files changed

+189
-169
lines changed

‎docs/development/local-dev-setup.md‎

Lines changed: 2 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -46,96 +46,9 @@ The other components are considered optional.
4646
The user applications [communicate via Firebase](architecture/index.md#communication-between-user-applications-and-the-opal-pie) with the _Opal PIE_.
4747
You need your own Firebase project so that your local app can communicate with the backend components.
4848

49-
!!! note
49+
Follow the [instructions on how to set up a Firebase project](../install/firebase-project-setup.md).
5050

51-
Firebase is a Google product.
52-
Therefore, you need a Google account to be able to use Firebase.
53-
54-
#### Create a new Firebase project
55-
56-
1. Open the [Firebase Console](https://console.firebase.google.com)
57-
1. Click on "Create a new Firebase project"
58-
1. Give it a relevant project name, such as "Opal Local"
59-
1. Uncheck "Enable Google Analytics for this project" and other options that are proposed to you
60-
1. Click "Create project"
61-
62-
The "Authentication" and "Realtime Database" features are needed for communication between the apps and backend components.
63-
Follow the instructions below to enable and configure these features.
64-
65-
#### Create a new Realtime Database
66-
67-
1. In the left panel of your newly created Firebase project, expand "Build" and click on "Realtime Database".
68-
1. Click "Create Database"
69-
1. On the second step of "Set up database" (Security rules), select "Start in test mode".
70-
71-
!!! note Security rules
72-
73-
This configures your Realtime Database to be accessible to anyone for 30 days.
74-
It is also possible to restrict access to authenticated users only by specifying the condition as `auth.uid !== null`.
75-
However, not all features will work.
76-
The rules in use by the Opal solution can be found in the [listener project](https://github.com/opalmedapps/opal-listener/blob/main/firebase/database.rules.json).
77-
See the [instructions on how to deploy them](https://github.com/opalmedapps/opal-listener/blob/main/docs/source/firebase-rules.md) to your project or copy-and-paste them into your project's rules.
78-
79-
See also the Firebase documentation on [Firebase Security Rules](https://firebase.google.com/docs/rules).
80-
81-
#### Enable email and password authentication
82-
83-
1. In the left panel, expand "Build" and click on "Authentication"
84-
1. Click on "Get started"
85-
1. Choose "Email/Password" as the sign-in provider
86-
1. Enable "Email/Password" and click "Save"
87-
88-
See also the Firebase documentation on [Firebase Authentication](https://firebase.google.com/docs/auth).
89-
90-
#### Retrieve the Firebase project configurations
91-
92-
Retrieve the client configuration for browser and Android apps:
93-
94-
##### Browser client configuration
95-
96-
1. Click on the settings icon (gear) next to "Project Overview"
97-
98-
1. Click on "Project Settings"
99-
100-
1. In the "General" tab, under "Your Apps", click the "\</>" icon
101-
102-
1. Choose an app nickname, such as "Opal Local"
103-
104-
You can also enable "Firebase Hosting" at this time if you are planning to use this project for production or intend to test the password reset feature in the app.
105-
106-
1. Click "Register app"
107-
108-
1. Copy the code and save it somewhere for later
109-
110-
##### Mobile app client configuration
111-
112-
1. Go back to the "Project Settings" page
113-
1. In the "General" tab, under "Your Apps", click the Android icon
114-
1. Choose an Android package name
115-
1. Click "Register app"
116-
1. Download the `google-services.json` file and save it somewhere for later
117-
118-
!!! question "Do I also need to add an iOS app?"
119-
120-
You do not need to add it if you are only building the iOS app.
121-
The iOS app is reusing the `google-services.json` file during the build.
122-
123-
However, if you intend to use [Firebase App Distribution](https://firebase.google.com/docs/app-distribution) to distribute your mobile app to testers, you will need to register an iOS app as well.
124-
125-
1. Go back to the "Project Settings" page
126-
1. In the "General" tab, under "Your Apps", click the iOS icon
127-
1. Provide the Apple bundle ID of your app
128-
1. Click "Register app"
129-
130-
##### Service account
131-
132-
Retrieve the private key for the admin SDK:
133-
134-
1. Go back to the "Project Settings" page and click on the "Service accounts" tab
135-
1. Click on "Generate new private key" and then "Generate key"
136-
1. Download the file somewhere safe on your machine for later
137-
138-
See also the Firebase documentation on [Admin SDK Authentication](https://firebase.google.com/docs/database/admin/start).
51+
Note that the instructions on restricting permissions are optional for development.
13952

14053
### Set up the legacy databases
14154

‎docs/install/firebase-project-setup.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
<!--
2+
SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
3+
4+
SPDX-License-Identifier: CC-BY-SA-4.0
5+
-->
6+
7+
# Firebase project setup
8+
9+
The user applications [communicate via Firebase](../development/architecture/index.md#communication-between-user-applications-and-the-opal-pie) with the _Opal PIE_.
10+
You need your own Firebase project so that your app can communicate with the backend components.
11+
12+
!!! note
13+
14+
Firebase is a Google product.
15+
Therefore, you need a Google account to be able to use Firebase.
16+
17+
## Create a new Firebase project
18+
19+
1. Open the [Firebase Console](https://console.firebase.google.com)
20+
1. Click on "Create a new Firebase project"
21+
1. Give it a relevant project name, such as "Opal Local"
22+
1. Uncheck "Enable Google Analytics for this project" and other options that are proposed to you
23+
1. Click "Create project"
24+
25+
The "Authentication" and "Realtime Database" features are needed for communication between the apps and backend components.
26+
Follow the instructions below to enable and configure these features.
27+
28+
## Create a new Realtime Database
29+
30+
1. In the left panel of your newly created Firebase project, expand "Build" and click on "Realtime Database".
31+
1. Click "Create Database"
32+
1. On the second step of "Set up database" (Security rules), select "Start in test mode".
33+
34+
!!! note Security rules
35+
36+
This configures your Realtime Database to be accessible to anyone for 30 days.
37+
It is also possible to restrict access to authenticated users only by specifying the condition as `auth.uid !== null`.
38+
However, not all features will work.
39+
The rules in use by the Opal solution can be found in the [listener project](https://github.com/opalmedapps/opal-listener/blob/main/firebase/database.rules.json).
40+
See the [instructions on how to deploy them](https://github.com/opalmedapps/opal-listener/blob/main/docs/source/firebase-rules.md) to your project or copy-and-paste them into your project's rules.
41+
42+
See also the Firebase documentation on [Firebase Security Rules](https://firebase.google.com/docs/rules).
43+
44+
## Enable email and password authentication
45+
46+
1. In the left panel, expand "Build" and click on "Authentication"
47+
1. Click on "Get started"
48+
1. Choose "Email/Password" as the sign-in provider
49+
1. Enable "Email/Password" and click "Save"
50+
51+
See also the Firebase documentation on [Firebase Authentication](https://firebase.google.com/docs/auth).
52+
53+
## Retrieve the Firebase project configurations
54+
55+
Retrieve the client configuration for browser and Android apps:
56+
57+
### Browser client configuration
58+
59+
1. Click on the settings icon (gear) next to "Project Overview"
60+
61+
1. Click on "Project Settings"
62+
63+
1. In the "General" tab, under "Your Apps", click the "< />" icon
64+
65+
1. Choose an app nickname, such as "Opal Local"
66+
67+
You can also enable "Firebase Hosting" at this time if you are planning to use this project for production or intend to test the password reset feature in the app.
68+
69+
1. Click "Register app"
70+
71+
1. Copy the code and save it somewhere for later
72+
73+
### Mobile app client configuration
74+
75+
1. Go back to the "Project Settings" page
76+
1. In the "General" tab, under "Your Apps", click the Android icon
77+
1. Choose an Android package name
78+
1. Click "Register app"
79+
1. Download the `google-services.json` file and save it somewhere for later
80+
81+
!!! question "Do I also need to add an iOS app?"
82+
83+
You do not need to add it if you are only building the iOS app.
84+
The iOS app is reusing the `google-services.json` file during the build.
85+
86+
However, if you intend to use [Firebase App Distribution](https://firebase.google.com/docs/app-distribution) to distribute your mobile app to testers, you will need to register an iOS app as well.
87+
88+
1. Go back to the "Project Settings" page
89+
1. In the "General" tab, under "Your Apps", click the iOS icon
90+
1. Provide the Apple bundle ID of your app
91+
1. Click "Register app"
92+
93+
### Service account
94+
95+
Retrieve the private key for the admin SDK:
96+
97+
1. Go back to the "Project Settings" page and click on the "Service accounts" tab
98+
1. Click on "Generate new private key" and then "Generate key"
99+
1. Download the file somewhere safe on your machine for later
100+
101+
See also the Firebase documentation on [Admin SDK Authentication](https://firebase.google.com/docs/database/admin/start).
102+
103+
## Restrict permissions
104+
105+
During the above set up, Firebase creates a service account and API keys for you.
106+
By default, these have permissions that are more permissive than what is needed.
107+
Therefore, we strongly recommend to restrict their permissions, especially for production environments.
108+
109+
### Restrict service account permissions
110+
111+
By default, Firebase creates a service account and API keys.
112+
The service account likely has more permissions than are needed.
113+
We recommend to restrict the permissions as much as possible.
114+
115+
Go to the [Service Accounts in Google Cloud](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) and select your Firebase project, then:
116+
117+
1. Click on the name of the service account that was created for you
118+
1. Go to "Permissions" and click on "Manage access"
119+
1. Update the assigned roles to match the following roles:
120+
- _Firebase Authentication Admin_
121+
- _Firebase Cloud Messaging Admin_
122+
- _Firebase Realtime Database Admin_
123+
- _Firebase Rules Admin_
124+
1. Click "Save"
125+
126+
### Restrict API keys
127+
128+
When registering apps on your Firebase project, Firebase automatically creates API keys.
129+
These should be further restricted.
130+
131+
!!! question "Can new API keys be created instead?"
132+
133+
This is generally possible.
134+
However, as part of the set up you will need to get a `google-services.json` file.
135+
When this file is retrieved, Firebase automatically creates corresponding API keys.
136+
137+
Go to the [API Credentials in Google Cloud](https://console.cloud.google.com/apis/credentials) and select the corresponding Firebase project.
138+
139+
#### Browser key
140+
141+
1. The browser key should have a name like "Browser key (auto created by Firebase)"
142+
143+
1. Click on its name to edit it
144+
145+
1. Under "Application restrictions", choose "Websites"
146+
147+
1. Add the following websites at a minimum to allow mobile app users to access this project
148+
149+
- `app://localhost`
150+
- `http://localhost`
151+
- `https://<your-firebase-project-id>.firebaseapp.com`
152+
153+
You should also add the base URL of your registration and web app to this list.
154+
155+
1. Under "API Restrictions", choose "Restrict key"
156+
157+
1. Choose the following APIs
158+
159+
- _FCM Registration API_
160+
- _Firebase Realtime Database Management API_
161+
- _Identity Toolkit API_
162+
163+
1. Click "Save"
164+
165+
#### Android key
166+
167+
1. The Android API key should have a name like "Android key (auto created by Firebase)"
168+
1. Click on its name to edit it
169+
1. Under "API Restrictions", choose "Restrict key"
170+
1. Choose the following APIs
171+
- _FCM Registration API_
172+
- _Firebase Realtime Database Management API_
173+
- _Identity Toolkit API_
174+
- _Firebase Installations API_
175+
1. Click "Save"
176+
177+
It is also possible to restrict the key further to a specific Android app.
178+
179+
#### iOS key
180+
181+
The iOS key gets generated when [registering an iOS app](#mobile-app-client-configuration).
182+
This key, named "iOS key (auto created by Firebase)", is not needed and can be deleted.

‎docs/install/index.md‎

Lines changed: 4 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -49,29 +49,9 @@ In addition, you need a Firebase project.
4949

5050
#### Create and set up a new Firebase project
5151

52-
If you don't have a dedicated Firebase project yet, follow the steps to [create a Firebase project](../development/local-dev-setup.md#create-a-new-firebase-project).
53-
If you already have a dedicated Firebase project, ensure that you have done the following steps:
52+
If you don't have a dedicated Firebase project yet, follow the steps to [set up a Firebase project](./firebase-project-setup.md).
5453

55-
- [create a Realtime Database](../development/local-dev-setup.md#create-a-new-realtime-database)
56-
- [enable email and password authentication](../development/local-dev-setup.md#enable-email-and-password-authentication)
57-
- [retrieve Firebase configurations](../development/local-dev-setup.md#retrieve-the-firebase-project-configurations)
58-
59-
#### Restrict service account permissions
60-
61-
By default, Firebase creates a service account and API keys.
62-
The service account likely has more permissions than are needed.
63-
We recommend to restrict the permissions as much as possible.
64-
65-
Go to the [Service Accounts in Google Cloud](https://console.cloud.google.com/projectselector2/iam-admin/serviceaccounts) and select your Firebase project, then:
66-
67-
1. Click on the name of the service account that was created for you
68-
1. Go to "Permissions" and click on "Manage access"
69-
1. Update the assigned roles to match the following roles:
70-
- *Firebase Authentication Admin*
71-
- *Firebase Cloud Messaging Admin*
72-
- *Firebase Realtime Database Admin*
73-
- *Firebase Rules Admin*
74-
1. Click "Save"
54+
Please also ensure that you restrict the permissions of the Firebase service account and API keys.
7555

7656
#### Retrieve the Apple Push Notification certificates
7757

@@ -139,61 +119,5 @@ Please follow the instructions in the [`deploy-pie`](https://github.com/opalmeda
139119

140120
### Requirements
141121

142-
#### Restrict Firebase API keys
143-
144-
We assume that you already [set up your Firebase project](#create-and-set-up-a-new-firebase-project) and [retrieved Firebase client configurations](../development/local-dev-setup.md#retrieve-the-firebase-project-configurations).
145-
This means that API keys were already created for you.
146-
By default, Firebase creates a service account and API keys with excessive permissions.
147-
148-
!!! question "Can new API keys be created instead?"
149-
150-
This is generally possible.
151-
However, as part of the set up you will need to get a `google-services.json` file.
152-
When this file is retrieved, Firebase automatically creates corresponding API keys.
153-
154-
Go to the [API Credentials in Google Cloud](https://console.cloud.google.com/apis/credentials) and select the corresponding Firebase project.
155-
156-
##### Browser key
157-
158-
1. The browser key should have a name like "Browser key (auto created by Firebase)"
159-
160-
1. Click on its name to edit it
161-
162-
1. Under "Application restrictions", choose "Websites"
163-
164-
1. Add the following websites at a minimum to allow mobile app users to access this project
165-
166-
- `app://localhost`
167-
- `http://localhost`
168-
- `https://<your-firebase-project-id>.firebaseapp.com`
169-
170-
You should also add the base URL of your registration and web app to this list.
171-
172-
1. Under "API Restrictions", choose "Restrict key"
173-
174-
1. Choose the following APIs
175-
176-
- *FCM Registration API*
177-
- *Firebase Realtime Database Management API*
178-
- *Identity Toolkit API*
179-
180-
1. Click "Save"
181-
182-
##### Android key
183-
184-
1. The Android API key should have a name like "Android key (auto created by Firebase)"
185-
1. Click on its name to edit it
186-
1. Under "API Restrictions", choose "Restrict key"
187-
1. Choose the following APIs
188-
- *FCM Registration API*
189-
- *Firebase Realtime Database Management API*
190-
- *Identity Toolkit API*
191-
- *Firebase Installations API*
192-
1. Click "Save"
193-
194-
It is also possible to restrict the key further to a specific Android app.
195-
196-
##### iOS key
197-
198-
The iOS key gets generated when [registering an iOS app](../development/local-dev-setup.md#mobile-app-client-configuration).
199-
This key, named "iOS key (auto created by Firebase)", is not needed and can be deleted.
122+
We assume that you already [set up your Firebase project](./firebase-project-setup.md) and [retrieved Firebase client configurations](./firebase-project-setup.md#retrieve-the-firebase-project-configurations).
123+
This means that API keys were already created for you which you need for the web and mobile apps.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ nav:
4747
- Generate Self Signed Certificates: development/guides/self_signed_certificates.md
4848
- Install:
4949
- Deploying the Opal Solution: install/index.md
50+
- Firebase project setup: install/firebase-project-setup.md
5051
- Hospital Integration: install/integration.md
5152

5253
# Configuration

0 commit comments

Comments
 (0)