Setup Guide

The PRISM Research Portal is how researchers can configure and run studies. This guide provides instructions on how to set up the PRISM Research Portal locally for development or deployment. The PRISM Research Portal is split into two main components:

Backend Server (FastAPI): A Python-based REST API that communicates with Firebase Auth, Firestore, and handles data storage/exports.
Frontend (Flutter): A web-based user interface used by researchers to manage experiments and view participant session data.

Both components connect to the same Firebase project for authentication and database storage, which must be created before starting the setup.

Additionally, an Android mobile and WearOS app exists to collect data from participants. Documentation on building the PRISM Android mobile and WearOS app can be found in the GitHub Repo, documentation on using the app can be found in the Researcher Guide.

flowchart TD
    n1@{ label: "Firebase" }
    
    subgraph s1["Research Portal"]
        n2@{ label: "Backend" }
    n3@{ label: "Frontend" }
    n2 <--> n3
    end

    subgraph s2["App"]
        n4@{ label: "Android" }
    n5@{ label: "WearOS" }
    n4 --> n5
    end
    
    n1 <--> s1
  n1 <--> s2
  
  style n1 fill:#D2E3FC
  style s1 fill:#CEEAD6
  style s2 fill:#CEEAD6
  style n2 fill:#FEEFC3
  style n3 fill:#FEEFC3
  style n4 fill:#FEEFC3
  style n5 fill:#FEEFC3

For most users we recommend using the Unified Setup via Docker. It is the most reliable way to run the PRISM Research Portal (both frontend and backend) without manually configuring installation options.

You likely want to use the Manual Setup only if:

You are a developer planning to modify the backend code or the Flutter frontend web app code directly.
You need to run and debug a specific service locally outside of a Docker container environment.

Unified Setup via Docker

The easiest way to install and run both the PRISM Research Portal Backend and Frontend is via the prism-setup repository which uses Docker Compose. These instructions are detailed here.

1. Prerequisites

Ensure the following are installed and running:

Docker Desktop - must be installed and running!
Git for Windows, or for Mac and Linux git is pre-installed.
A Mailgun account or a Gmail account for sending emails.
A Firebase project with paid usage enabled.

2.Clone the repository

Execute the following commands in your terminal to download the repository and move into the folder:

git clone https://github.com/Australian-Future-Hearing-Initiative/prism-setup.git
cd prism-setup

3. Gather your credentials

Before running the installer, have the following ready — the script will prompt you for each one.

Firebase Web API Key

From the Firebase Console in your project (e.g. PrismData): Settings → General

Scroll down to Your apps → Web apps → prism (web) → Config → apiKey and save it.

Firebase Service Account Key

From the Firebase Console in your project (e.g. PrismData): Settings → Service accounts

Select the Firebase Admin SDK section and click Generate new private key.

Rename the downloaded file to serviceAccountKey.json and place it in the root of the prism-setup folder.

Email Settings

Option 1: Mailgun

Sign up for a free account at https://www.mailgun.com/
Follow the instructions to add a domain and verify your email address.
Save the API key and domain name — the setup prompt will ask for them.

The free-tier is capable of sending 100 emails per day, reasonably priced paid-tiers increase this substantially. Note: You must have a web domain hosted somewhere to use this service.

Option 2: Gmail SMTP

Enable 2-Step Verification, then generate an App Password:

Google Account → Security → 2-Step Verification → ON
App passwords → create a new app (PRISM) → copy the 16-char code

Save your Gmail address and the 16-char App Password — the setup prompt will ask for them.

Gmail allows up to 100 emails per day, but can’t easily be changed.

4. Run the installer

Execute the install script from the prism-setup directory. Follow the prompts to enter your credentials. The script will build the Docker containers and start the PRISM Research Portal automatically:

bash install.sh

5. Deploy to production

Your Firebase project houses the experiment. The front and backend allow you to interface with that project. So the most likely deployment scenario is building this on a local machine and spinning up/down the docker containers when you need to access the experiment.

To stop the services:

cd prism-setup
docker compose down

To start them again (without rebuilding):

cd prism-setup
docker compose up

Then navigate your browser to http://127.0.0.1:8000 (assuming default ports) to access the PRISM Research Portal.

Manual Setup

If you prefer to run and develop the services independently without Docker, follow the manual instructions documented at prism-flutter-backend repo and the prism-flutter-web-frontend repo.