From 5a3dd86bf9c7e4c0067b77627efec0e6a9ef5e13 Mon Sep 17 00:00:00 2001 From: Blake Ridgway Date: Thu, 3 Apr 2025 13:53:11 -0500 Subject: [PATCH] (docs): Update README for clarity, features, and deployment Rewrite README for clarity, features, architecture, setup, contributing guide --- README.md | 113 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 80 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 3659122..510f3b3 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,87 @@ # RideAware Admin Center -This project provides an Admin Center for managing the RideAware subscriber list. It connects to the same SQLite database (`subscribers.db`) used by the landing page app (running on port 5000) and allows an administrator to: - -- View all currently subscribed email addresses. -- Send overview update emails to all subscribers. -- Unsubscribe emails via the landing page app. - -The Admin Center is protected by a login page, and admin credentials (with a salted/hashed password) are stored in the `admin_users` table within the same database. +This project provides a secure and user-friendly Admin Panel for managing RideAware subscribers and sending update emails. It's designed to work in conjunction with the RideAware landing page application, utilizing a shared database for subscriber management. ## Features -- **Admin Login:** - Secure login using salted and hashed passwords (via Werkzeug security utilities). -- **Subscriber List:** - View all email addresses currently stored in the `subscribers` table. +**Secure Admin Authentication:** -- **Email Updates:** - A form for sending update emails (HTML allowed) to the subscriber list using SMTP. +* Login protected by username/password authentication using Werkzeug's password hashing. +* Default admin credentials configurable via environment variables. -- **Shared Database:** - Both the landing page app (port 5000) and Admin Center (port 5001) connect to the same `subscribers.db`. +**Subscriber Management:** +* View a comprehensive list of all subscribed email addresses. -## Setup & Running +**Email Marketing:** +* Compose and send HTML-rich update emails to all subscribers. +* Supports embedding unsubscribe links in email content for easy opt-out. + +**Shared Database:** +* Utilizes a shared PostgreSQL database with the landing page application for consistent subscriber data. + +**Centralized Newsletter Storage:** +* Storage of newsletter subject and email bodies in the PostgreSQL database + +**Logging:** +* Implemented comprehensive logging throughout the application for better monitoring and debugging. + +## Architecture + +The Admin Panel is built using Python with the Flask web framework, using the following technologies: + +* **Backend:** Python 3.11+, Flask +* **Database:** PostgreSQL +* **Template Engine:** Jinja2 +* **Authentication:** Werkzeug Security +* **Email:** SMTP (using `smtplib`) +* **Containerization:** Docker +* **Configuration:** .env file using `python-dotenv` + +## Setup & Deployment ### Prerequisites -- Docker (for containerized deployment) -- Python 3.11+ (if running locally without Docker) -- An SMTP account (e.g., Spacemail) for sending emails -- A `.env` file with configuration details +* Docker (recommended for containerized deployment) +* Python 3.11+ (if running locally without Docker) +* A PostgreSQL database instance +* An SMTP account (e.g., SendGrid, Mailgun) for sending emails +* A `.env` file with configuration details ### .env Configuration -Create a `.env` file in the project root with the following example variables: +Create a `.env` file in the project root directory with the following environment variables. Make sure to replace the placeholder values with your actual credentials. ```env -# SMTP settings (shared with the landing page app) -SMTP_SERVER= -SMTP_PORT= -SMTP_USER= -SMTP_PASSWORD= +# Flask Application +SECRET_KEY="YourSecretKeyHere" #Used to sign session cookies -# Database file -DATABASE_FILE=subscribers.db +# PostgreSQL Database Configuration +PG_HOST=localhost +PG_PORT=5432 +PG_DATABASE=rideaware_db +PG_USER=rideaware_user +PG_PASSWORD=rideaware_password # Admin credentials for the Admin Center ADMIN_USERNAME=admin ADMIN_PASSWORD="changeme" # Change this to a secure password -ADMIN_SECRET_KEY="your_super_secret_key" + +# SMTP Email Settings +SMTP_SERVER=smtp.example.com +SMTP_PORT=465 #Or another appropriate port +SMTP_USER=your_email@example.com +SMTP_PASSWORD=YourEmailPassword +SENDER_EMAIL=your_email@example.com #Email to send emails from +BASE_URL="your_site_domain.com" # used for unsubscribe links, example.com not https:// + +#Used for debugging +FLASK_DEBUG=1 ``` -### Running with Docker +### Running with Docker (Recommended) + +This is the recommended approach for deploying the RideAware Admin Panel Building the Docker image: ```sh @@ -63,18 +93,35 @@ Running the container mapping port 5001: docker run -p 5001:5001 admin-panel ``` -The app will be accessible at http://ip-address-here:5001 +The application will be accessible at `http://localhost:5001` or `http://:5001` + +*Note: When running locally with Docker, ensure the .env file is located at the project root. Alternatively, you can pass the variables in the CLI.* ### Running locally -Install the dependencies using **requirements.txt**: + +Install Dependencies: ```sh pip install -r requirements.txt ``` +Set Environment Variables: + +Ensure all the environment variables specified in the `.env` configuration section are set in your shell environment. You can source the `.env` file: + + Then run the admin app: ```sh python app.py ``` -The app will be accessible at http://ip-address-here:5001 \ No newline at end of file +The app will be accessible at `http://127.0.0.1:5001` + +### Contributing + +Contributions to the RideAware Admin Panel are welcome! Please follow these steps: + +* Fork the repository. +* Create a new branch for your feature or bug fix. +* Make your changes and commit them with descriptive commit messages. +* Submit a pull request. \ No newline at end of file