Misinfo Dashboard

Getting Started | Firebase Emulator | Firebase | Push to Netlify

This project project bootstrapped with create-next-app of the Next.js framework. To learn more about Next.js features and API, take a look at Next.js Documentation.

See Technical Documentation for Project Structure, Firebase, Components and Git Usage docs.

Already set up?

Simple. Run two commands in separate terminal tabs:

firebase emulators:start --import=./emulator-data

and...

yarn dev

Not set up? Keep reading...

Getting Started

1. Clone repo

First step! Clone this repo into a local directory (ex. ~/username/sites/) on your machine.

From the command line in your project root run:

git clone https://github.com/engagingnewsproject/misinfo-dashboard.git

2. Install Packages

Node Version

At this time of writing (April 26, 2024) the latest working update is at Node v20.12.2. Ensure this is the version by running node -v. If you are not on that Node version check out this article to set the correct Node version: Easily switch between multiple Node versions without using nvm.

Yarn

Install/update yarn package manager on your machine (installation docs)

Enable Corepack, if it isn't already; this will add the yarn binary to your PATH:
```
corepack enable
```
Set the yarn version by running:

yarn set version 1.22.1

From the root of the project install dependencies by running:
```
yarn install
```
Why not npm install? Glad you asked! Netlify, the service that hosts the dashboard, will not allow us to upload updates because npm install creates a package-lock.json file. Netlify doesn't like package-lock.json files.

3. Add Firebase configuration

In order to be authenticated with the Firebase Project you must have the .env file (which contains the Firebase credentials) at the root of your project. To get the contents of the .env file reach out to the project lead (currently Luke).

4. Install and run Firebase Emulator

Firebase Emulator is included in the Firebase Tools package. You can install Firebase Tools by running:

curl -sL firebase.tools | bash

Next, to run the app on the emulator and import the testing db data, in a new terminal tab run:

firebase emulators:start --import=./emulator-data

See Emulator Tips for more info.

5. Start dev server

To boot up the development server run:

yarn dev
# or
npm run dev

If you open http://localhost:3000 and you see the "unhandled error" FirebaseError: Failed to get document because the client is offline. this means you have not started the Firebase Emulator. Return to step #4 to Install and run the Firebase Emulator.

Open http://localhost:3000 with your browser to see the result. If you have the emulator running you will see a banner Running in emulator mode. Do not use with production credentials. at the bottom of your screen as well as Console log messages letting you know that the emulator is running:

emulator-running

NOTE: You will have 2 terminal tabs running while developing:

1 terminal tab for yarn dev (or npm run dev),

1 terminal tab for firebase emulators:start --import=./emulator-data.

NOTE: You will also have 2 browser tabs open while developing:

1 browser tab for localhost:3000 (actual misinfo dashboard),

1 browser tab for "Firebase Emulator Suite"

Develop away! And good luck :)

Emulator Tips:

If you get command not found you might have to be added as a user for the Firebase project. Contact the lead developer to do this for you. Or contact mediaengagement@austin.utexas.edu

The Firebase Emulator should boot up and provide you an emulator link (look for View Emulator UI at in your command line output).

Open that link to view the Emulator UI:

emulator-ui

See Emulator Tips for more info.

Add yourself as a user via the "Emulator Authentication" tab.

Two options:

Option one: Manually add yourself

From the Firebase Emulator UI select the "Emulator Authentication" tab and click "Add user". Only required fields are: name, email and password. Change your role? see Available user roles below.
Option two: Sign up.

You can also signup like a normal user at the Login/Signup page. Once you have signed up:
- Open the link printed out in your Emulator terminal window.
  - **all you need to do is open the link. Once you've opened the link close the tab and...
- Return to your initial Signup tab and login with the credentials you signed up with. Change your role? see Available user roles below.

Available user roles:

General User:

No additional configuration required.
Agency User:

In the "Custom Claims" input enter {"agency":true} & save.
Admin User:

In the "Custom Claims" input enter {"admin":true} & save.

Emulator UI

Database: find the imported database under the Emulator UI / Firestore tab.
Users: view, add, edit & delete users under the Authentication tab.
Files & Uploads: Storage tab in the Emulator UI.

Users

Your user UID that you created will not be associated with any reports or agencies so you can either add reports via the Misinfo Dashboard in your localhost:3000 window or go into the Emulator UI and manually change the userID to your own for some reports. Same idea with assigning your user to an agency: go into the Emulator UI and add your email to an agency's agencyUsers field.

Emulator log files

Emulator creates log files (firebase-debug.log & ui-debug.log) when you boot up the emulator. No need to push those with git.

Export your local emulator data

The Firebase emulator allows you to export data from your running emulator instance. If you want to stash a baseline set of data, auth profiles you have set up in your running emulator instance.

firebase emulators:export ./emulator-data

This command will export the running emulator instance's auth profiles, firestore data and storage files to the /emulator-data folder. Recommended to not commit the /emulator-data changed files as to not alter the baseline Emulator data.

Firebase Functions

To deploy Firebase functions:

firebase deploy --only functions

Firebase Creds

With proper permissions access Firebase Console or Firebase Cloud Console.

Firebase project name: Misinfo
Firebase project ID: misinfo-5d004
Firebase project #: 2581605663

Firebase Storage

Firebase storage name: misinfo-5d004.appspot.com

Links: Chrome React Developer Tools || VS Code React-Native snippets || VS Code Tailwind CSS IntelliSense

Deploy to Netlify

Deploy to dev

Link: https://dev-misinfo-dashboard.netlify.app/

To push all changes to the dev site on Netlify using the Engaging News Project's misinfo-dashboard repo's dev branch.

The dev branch is the branch that contains the dev live site code.

Checkout the dev branch

git checkout dev
Merge changes from main to dev

git marge main
Push the merge into dev

git push origin dev
Open the Netlify UI for the dev site and monitor the progress. Make sure the top bar has dev-misinfo-dashboard active. On the left sidebar navigate to the "Deploys" link. Your latest push will be listed at the top.

Deploy to prod

Link: https://misinfo-dashboard.netlify.app/

To push all changes to the live site on Netlify using the Engaging News Project's misinfo-dashboard repo's dev branch.

The prod branch is the branch that contains the live site code.

Checkout the main branch

git checkout main
Merge changes from dev into main

git marge dev
Push the merge into main

git push origin main
Checkout the prod branch

git checkout prod
Merge main into prod

git merge main
Push the merge into prod

git push origin prod
Open the Netlify UI for the prod site and monitor the progress. Make sure the top bar has misinfo-dashboard active. On the left sidebar navigate to the "Deploys" link. Your latest push will be listed at the top.

Deploy issues

If you get the below error you will need to install Git Large File Storage.

remote: error: File firestore-debug.log is 102.65 MB; this exceeds GitHub's file size limit of 100.00 MB

To install:

git lfs install - make sure git large file storage is installed

git lfs track "firestore-debug.log" - to track the large file

git lfs migrate import --include="firestore-debug.log" --everything - convert the file types to LFS

git lfs ls-files - to list files

git lfs checkout - files can be repopulated with their full expected contents lfs docs

Project Lead Links: Firebase CLI Tools || Firebase Console || Firebase Cloud Console || Syncing a fork || Netlify dashboard || ENP Prod Repo

Docs

Integration of AuthContext and Firebase Functions

The AuthContext.jsx file in your React application interacts with the Firebase functions defined in functions/index.js through HTTPS callable functions. This setup allows your front-end application to communicate with the backend Firebase environment in a structured and secure manner.

How It Works:

Firebase Functions (functions/index.js): This file defines various cloud functions that you deploy to Firebase. These functions can perform operations such as user authentication management (e.g., adding roles, fetching user data), interacting with Firebase Firestore, and other tasks that require server-side execution.
React Context (context/AuthContext.jsx): This file creates a React context that holds the user's authentication state and provides various authentication-related functions across your React application. It utilizes the functions defined in functions/index.js through HTTPS callable methods, such as addAdminRole, addAgencyRole, and fetchUserRecord.
- HTTPS Callable Functions: These are Firebase functions that are exposed via an HTTPS endpoint. In your React app, you use httpsCallable from Firebase to invoke these functions. This method sends a POST request to the corresponding function's URL and gets the response.

Example Flow:

Add Role: When you want to add a role to a user, your React component calls addAdminRole or addAgencyRole through the context. This context function then calls the respective HTTPS callable function, which in turn invokes the cloud function in Firebase. The cloud function performs the necessary operations (like setting custom claims) and returns the result.
Fetch User Record: When you need to fetch details about a user, your component accesses fetchUserRecord from the context. This function uses getUserRecord (defined as an HTTPS callable function) to retrieve user details from Firebase Authentication.

Connecting the Dots:

AuthContext Integration: In your React components, you use the context to perform operations that involve authentication or user management. For instance, upon user login, you might call login from the context, which handles the sign-in process using Firebase Authentication.
Security and Accessibility: By managing these operations through cloud functions and context, you ensure that sensitive operations are securely handled on the server side, minimizing exposure to the client side, and you maintain a clean separation of concerns.

engagingnewsproject / misinfo-dashboard

readme