fix/add: log bug and dockerization/run scripts

.env.example

@@ -1,15 +1,15 @@
 # example of .env file / env variables needed
 
-PERSONAL_GITHUB_USERNAME = "your_github_username"
-PERSONAL_GITHUB_TOKEN = "your_github_token"  # you can create a token from "https://github.com/settings/apps"
+PERSONAL_GITHUB_USERNAME=your_github_username
+PERSONAL_GITHUB_TOKEN=your_github_token  # you can create a token from "https://github.com/settings/apps"
 
 # the person you want to follow
-TARGET_GITHUB_USERNAME = "target_username"
+TARGET_GITHUB_USERNAME=target_username
 
 # email configuration. see here for some help if you use gmail: https://support.google.com/a/answer/176600?hl=fr
-SMTP_SERVER = "smtp.gmail.com"  # for using gmail server
-SMTP_PORT = 465  # for SSL, gmail uses 465
+SMTP_SERVER=smtp.gmail.com  # for using gmail server
+SMTP_PORT=465  # for SSL, gmail uses 465
 
-EMAIL_SENDER = ""	# your email
-EMAIL_RECIPIENT = ""	# the email of the person you want to send the email to
-EMAIL_PASSWORD = ""	# your email password, eventually an app password if you use gmail and have 2FA enabled
+EMAIL_SENDER[email protected]	# your email
+EMAIL_RECIPIENT[email protected]	# the email of the person you want to send the email to
+EMAIL_PASSWORD='XXX XXX'	# your email password, eventually an app password if you use gmail and have 2FA enabled

.gitignore

@@ -5,5 +5,5 @@ run.sh
 # python package
 __pycache__/
 *.pyc
-temp_*.py
+temp_*
 logs/

Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.10-slim
+
+RUN pip install poetry==1.4.0
+
+ENV POETRY_NO_INTERACTION=1 \
+    POETRY_VIRTUALENVS_IN_PROJECT=1 \
+    POETRY_VIRTUALENVS_CREATE=1 \
+    POETRY_CACHE_DIR=/tmp/poetry_cache
+
+WORKDIR /app
+
+COPY pyproject.toml poetry.lock ./
+
+RUN poetry install --without dev --no-root && rm -rf $POETRY_CACHE_DIR
+
+COPY . /app
+
+RUN poetry install --without dev
+
+CMD ["poetry", "run", "python", "-m", "script.panopticron"]

README.md

@@ -1,3 +1,97 @@
 # Panopticron
 
-stalk users on github to learn stuff.
+stalk users on github to learn stuff. Mentorship from afar.
+
+**Panopticron** is a simple Python script designed to monitor GitHub activity for a specific user, ensuring you stay informed about their latest contributions, commits, and events.
+I use it for learning purposes, when I see someone i would like to learn from, or actively working on a project I am interested in.
+
+I run the script with a cron job at regular intervals to keep track of their activities and events.
+
+## Features
+
+- **Daily Activity Monitoring**: Tracks GitHub activity for a specified target user through the Github API.
+- **Email Notifications**: Sends email notifications summarizing the latest events, with links to repos.
+- **Logging**: Records the script's activity in log files for debugging, monitoring and saving latest result to a file (limit email spam to once every 12 hours, might move to once a day).
+- **Internet Connection Detection**: Ensures the script only runs when an active internet connection is available. else retries after a delay.
+
+## Installation and Usage
+
+1. **Clone/Fork the Repository**:
+   ```bash
+   git clone https://github.com/adnene-guessoum/panopticron.git
+	 cd Panopticron
+   ```
+
+2. **Install Dependencies**:
+
+	 for ease of use, i dockerized the project and provided an example run script. see usage below.
+
+   If you want to not use docker/script, I use Poetry to manage dependencies. you can install with the official installer here : https://python-poetry.org/docs/#installing-with-the-official-installer .
+
+3. **Add your environment variables**:
+   Create a `.env` file in the project root directory. an example is provided in the `.env.example` file, with the necessary environment variables and some explanations.
+	 Most importantly, you will need:
+   - A GitHub personal access token. (cf. .env.example)
+   - The GitHub username you want to monitor.
+   - Your email credentials for sending notifications.
+
+	 adhere to the ".env.example" file format and fill in the necessary information, as it is used to load the environment variables in the docker container.
+
+4. **Run using the script/docker**:
+
+	 1) Setup the correct paths in the script example.run.sh file to match your setup,
+	 2) don't forget to modify the environment variables in the `.env.example` file to match your infos and rename it to `.env` (as explained in step 3),
+	 3) then run:
+	 ```bash
+	 mv example.run.sh run.sh
+	 chmod +x run.sh
+	 ./run.sh
+	 ```
+	 you should be good to go for a manual run (docker image build and run).
+
+
+6. **Set Up Daily Execution**:
+   I use a cron job to run the script once every 12 hours.
+
+	to setup a cron job:
+	 ```bash
+	 crontab -e
+	 ```
+	 then add the cron job line at the end of the file:
+	 ```bash
+	 */12 * * *  /path/to/repo/Panopticron/run.sh >> /path/to/repo/Panopticron/logs/cron_logs.log 2>&1
+	 ```
+
+	 This will run the script (docker build then docker run) every 12 hours and log the output of the cron job to the specified file.
+	 Modify the path to the repo to match your setup and the frequency of the cron job to your needs.
+
+Feel free to adjust based on your needs, or to offer contributions to make this more user-friendly.
+You can open an issue if need help setting it up.
+
+## Example Email Notification
+
+```
+Subject: Last 24H GitHub Activity from adnene-guessoum
+
+ =====================
+New activity by adnene-guessoum:
+
+Event Type: PushEvent
+Repository: adnene-guessoum/Panopticron
+Time: 2024-12-22T12:34:42Z
+Repo_URL: https://github.com/adnene-guessoum/Panopticron
+author_URL: https://github.com/adnene-guessoum
+ =====================
+
+etc...
+```
+
+## Contributions
+
+Contributions are obviously welcome. Probably i won't work too much on it as it meets my need as is.
+If you have ideas for additional features or improvements, feel free to submit a pull request or open an issue of course.
+
+## Acknowledgments
+
+- The GitHub API, for providing the necessary data.
+- The devs that don't know they are mentoring me.

example.run.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+cd /home/{path/to/project}/Panopticron || exit
+docker build -t panopticron .
+docker run --rm -v "$(pwd)/logs:/app/logs" --env-file ./.env panopticron

script/panopticron.py

@@ -152,7 +152,7 @@ def send_email(user_activity_last_24_hours):
 
     if not user_activity_last_24_hours:
         logger.warning("No activity found in the last 24 hours. Exiting script...")
-        return
+        return False
 
     content = "".join(user_activity_last_24_hours)
 
@@ -167,6 +167,8 @@ def send_email(user_activity_last_24_hours):
         server.send_message(email)
         logger.info("Email sent successfully: %s", email["Subject"])
 
+    return True
+
 
 def log_successful_run():
     """log successful runs to ensure no runs less than 12 hours apart"""
@@ -199,8 +201,9 @@ def main(username):
     user_activity = get_user_activity(username)
     user_activity_last_24_hours = filter_last_24_hours_activity(user_activity)
     log_last_run_results(user_activity_last_24_hours)
-    send_email(user_activity_last_24_hours)
-    log_successful_run()
+    email_status = send_email(user_activity_last_24_hours)
+    if email_status:
+        log_successful_run()
 
 
 if __name__ == "__main__":