From 6a774dfc317ae230cf31a9b7e83bcac74469f8a6 Mon Sep 17 00:00:00 2001
From: Peter Valdez <ptr.vldz@gmail.com>
Date: Sun, 23 Feb 2025 23:01:20 -0500
Subject: [PATCH] Update README, use repo-local key id file

---
 .gitignore           |  3 ++
 Makefile             |  1 +
 README.md            | 85 ++++++++++++++++++++++++++++++++++----------
 utils/gpg_manager.sh | 11 +++---
 4 files changed, 76 insertions(+), 24 deletions(-)

diff --git a/.gitignore b/.gitignore
index c8e5722..9862a22 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,6 @@ volumes
 # GPG secrets directory - only track .gpg files
 gpg-secrets/*
 !gpg-secrets/*.gpg
+
+# GPG key IDs file
+.localmart-github-key-ids
diff --git a/Makefile b/Makefile
index d5d69f6..15bcd98 100644
--- a/Makefile
+++ b/Makefile
@@ -10,6 +10,7 @@ clean:
 
 clean-data:
 	rm -rf ./volumes
+	rm -rf frontend/.next
 
 deploy-frontend:
 	cd frontend && fly deploy
diff --git a/README.md b/README.md
index 432ca91..3fb0175 100644
--- a/README.md
+++ b/README.md
@@ -2,32 +2,81 @@
 
 localmart is a platform for local businesses to sell their products and services to local customers.
 
-## Prerequisites
 
-Docker, Docker Compose
+## Development
 
-## Usage
+### Prerequisites
+
+For development:
+- Docker
+- Docker Compose
+
+### Usage
 
 To start the next.js frontend, the Python backend, and the database, run:
 ```bash
-docker compose --build up
+make
 ```
 
-To clear the database
+To clear the database and the frontend next.js cache:
 ```bash
-rm -rf ./volumes
+make clean-data
 ```
 
-## Debugging Tips
-If the app is not loading porperly on your machine, try clear the cache and restart.
+### Debugging Tips
+1. If the app is not loading porperly on your machine, try:
+   - clearing the data with `make clean-data`
+   - restarting with `make`
 
-To rebuild the backend:
-```bash
-make
-```
-To rebuild the frontend, if NextJS is giving errors:
-```bash
-cd frontend/
-rm -rf .next
-make
-```
+## Secret Management
+
+We use GPG encryption to securely store sensitive files. The encrypted files are stored in the `gpg-secrets/` directory and can only be decrypted by authorized team members.
+
+### Prerequisites
+
+1. Install GPG on your system:
+   ```bash
+   # macOS
+   brew install gnupg
+
+   # Ubuntu/Debian
+   sudo apt-get install gnupg
+   ```
+
+2. Have your own GPG key pair and upload the public key to your GitHub profile
+   ([GitHub guide on adding GPG keys](https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account))
+
+### Managing Secrets
+
+The following commands are available:
+
+1. Import team members' GPG keys:
+   ```bash
+   # Import team members' GPG keys
+   make import-gpg-keys
+   ```
+
+2. Encrypt a file:
+   ```bash
+   # The file will be encrypted and stored in gpg-secrets/
+   make encrypt-file FILE=path/to/your/file
+
+   # Example: Encrypt staging environment variables
+   make encrypt-file FILE=gpg-secrets/staging.env
+   ```
+
+3. Decrypt a file:
+   ```bash
+   # Only works with files in the gpg-secrets/ directory
+   make decrypt-file FILE=gpg-secrets/your-file.gpg
+
+   # Example: Decrypt staging environment variables
+   make decrypt-file FILE=gpg-secrets/staging.env.gpg
+   ```
+
+### Notes
+
+- Only files in the `gpg-secrets/` directory with the `.gpg` extension are tracked in Git
+- Decrypted files are automatically placed in the `gpg-secrets/` directory
+- You must have your private key to decrypt files
+- The list of team members is maintained in the Makefile's `GITHUB_USERS` variable
\ No newline at end of file
diff --git a/utils/gpg_manager.sh b/utils/gpg_manager.sh
index 1b143a7..1cd2965 100755
--- a/utils/gpg_manager.sh
+++ b/utils/gpg_manager.sh
@@ -49,10 +49,9 @@ import_keys() {
         fi
     done
 
-    # Store the key IDs in a more permanent location for later use
-    mkdir -p ~/.localmart
-    mv "$key_ids_file" ~/.localmart/github_key_ids
-    echo "Imported keys have been stored in ~/.localmart/github_key_ids"
+    # Store the key IDs in the repository
+    mv "$key_ids_file" .localmart-github-key-ids
+    echo "Imported keys have been stored in .localmart-github-key-ids"
 }
 
 # Function to encrypt a file
@@ -64,7 +63,7 @@ encrypt_file() {
     fi
 
     # Check if we have stored key IDs
-    if [ ! -f ~/.localmart/github_key_ids ]; then
+    if [ ! -f .localmart-github-key-ids ]; then
         echo "Error: No GitHub keys found. Please run import-keys first."
         exit 1
     fi
@@ -75,7 +74,7 @@ encrypt_file() {
         if [ -n "$key_id" ]; then
             recipient_args="$recipient_args -r $key_id"
         fi
-    done < ~/.localmart/github_key_ids
+    done < .localmart-github-key-ids
 
     if [ -z "$recipient_args" ]; then
         echo "Error: No valid recipient keys found"