From c3933cc55219e38360f20540ebed98729705f676 Mon Sep 17 00:00:00 2001
From: Chris Jackett <cjackett@users.noreply.github.com>
Date: Sun, 4 Aug 2024 10:19:06 +1000
Subject: [PATCH] Update setup instructions and .env template for clarity

Enhanced README.md with detailed setup steps for Firebase, Supabase, and Mailgun, ensuring better guidance for new users. Standardized the .env.local.TEMPLATE format by removing spaces around equal signs for consistency.
---
 .env.local.TEMPLATE | 31 ++++++++++++++++---------------
 README.md           | 36 +++++++++++++++++++++++++++++++++++-
 2 files changed, 51 insertions(+), 16 deletions(-)

diff --git a/.env.local.TEMPLATE b/.env.local.TEMPLATE
index 43cc6c61..5596226e 100644
--- a/.env.local.TEMPLATE
+++ b/.env.local.TEMPLATE
@@ -2,30 +2,31 @@
 # which will be ignored by git to protect private api credentials.
 
 # To use /admin interface
-JWT_SECRET = ReplaceWithYourOwnBigLongRandomStringHere
-ADMIN_EMAIL =
+JWT_SECRET=ReplaceWithYourOwnBigLongRandomStringHere
+ADMIN_EMAIL=
 
 # Firebase - https://firebase.google.com - database
-FIREBASE_CLIENT_EMAIL =
-FIREBASE_PRIVATE_KEY =
-FIREBASE_PROJECT_ID =
+FIREBASE_CLIENT_EMAIL=
+FIREBASE_PRIVATE_KEY=
+FIREBASE_PROJECT_ID=
 
 # Mailgun — https://mailgun.com - transactional emails
-MAILGUN_API_KEY =
+MAILGUN_API_KEY=
+MAILGUN_DOMAIN=
 
 # Pusher - https://pusher.com - real-time updates via websocket channels
-PUSHER_KEY =
-PUSHER_SECRET =
+PUSHER_KEY=
+PUSHER_SECRET=
 
 # Pushover — https://pushover.net — for admin notifications
-PUSHOVER_APP_TOKEN =
-PUSHOVER_USER_KEY =
+PUSHOVER_APP_TOKEN=
+PUSHOVER_USER_KEY=
 
 # Supabase - https://supabase.com — database for analytics
-SUPABASE_ADMIN_KEY =
-SUPABASE_DB_URL =
-SUPABASE_JWT_SECRET =
+SUPABASE_ADMIN_KEY=
+SUPABASE_DB_URL=
+SUPABASE_JWT_SECRET=
 
 # Other (optional) password-protected admin stats pages
-RECENT_ELECTIONS_PASSWORD =
-NAP_STATS_PASSWORD =
\ No newline at end of file
+RECENT_ELECTIONS_PASSWORD=
+NAP_STATS_PASSWORD=
\ No newline at end of file
diff --git a/README.md b/README.md
index 4c57b4a0..34e5eb3c 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,41 @@ See the [SIV Public License](/LICENSE) for further details.
 ### Initial set up
 
 1. Duplicate the file `.env.local.TEMPLATE` into `.env.local`
-2. Create (free) accounts with the providers listed in that file, adding your new API keys
+
+2. Create (free) accounts with the providers listed in the `.env.local` file and add your new API keys as described below:
+
+   **Firebase**:
+      1. Visit [Firebase](https://firebase.google.com/) and sign in with your Google account
+      2. Click on "Get Started" and create a new project
+      3. Navigate to the project settings (cog icon) and go to "Project setting" -> "Service accounts"
+      4. Generate a new private key for the Firebase Admin SDK and download the JSON file
+      5. Extract the following values from the JSON file and add them to your `.env.local`:
+         * `FIREBASE_CLIENT_EMAIL`: Found in the "client_email" field
+         * `FIREBASE_PRIVATE_KEY`: Found in the "private_key" field
+           * Note: Ensure this key is enclosed in double quotes
+         * `FIREBASE_PROJECT_ID`: Found in the "project_id" field
+
+   **Supabase**:
+      1. Visit [Supabase](https://supabase.com/) and sign up for an account
+      2. Create a new project and note down the project URL and the public API key
+      3. Go to the project settings and add the following values to your `.env.local`:
+         * `SUPABASE_ADMIN_KEY`: Found in "API" -> "Project API keys" under "anon public"
+         * `SUPABASE_DB_URL`: Found in "Database" -> "Connection parameters" under "Host"
+         * `SUPABASE_JWT_SECRET`: Found in "API" -> "JWT Settings" under "JWT Secret"
+
+   **Mailgun**:
+      1. Visit [Mailgun](https://mailgun.com/) and sign up for a free account
+      2. Use the default sandbox domain provided by Mailgun for testing purposes.
+      3. Click on your account menu (top-right)
+         * Go to "Mailgun API keys" and hit "Add new key"
+         * Give the key a description such as "SIV"
+         * Copy the new API key and add it to `.env.local` under `MAILGUN_API_KEY`
+      4. Go back to the Dashboard and click on the sandbox account under "Sending domains"
+         * Note: the domain will look like `sandbox<XXXX>.mailgun.org`
+         * Copy this domain and add it to `.env.local` under `MAILGUN_DOMAIN`
+      5. Add "Authorized Recipients" email addresses on the right that you will test with
+      6. Now test that everything is set up correctly using the appropriate command provided in the API panel
+
 3. Install local dependencies:
 
 ```bash