This repository has no description
1# Bluesky Avatar Updater
2
3***This repository is available on [GitHub](https://github.com/ewanc26/bluesky-avatar-updater) and [Tangled](https://tangled.sh/@ewancroft.uk/bluesky-avatar-updater). GitHub is the primary version, and the Tangled version is a mirror.***
4
5## Overview
6
7This repository contains a Python script that automatically updates your Bluesky avatar (and, optionally, your banner) based on the current hour. The script utilises environment variables for configuration and reads a JSON file mapping blob CIDs to specific hours. In addition to updating your avatar, the script performs several supportive functions including a health check of the API endpoint, comprehensive logging (both to console and to a rotating file system that deletes logs older than 30 days), and the automatic setup of a cron job to ensure regular updates. This project was inspired by [@dame.is](https://bsky.app/profile/dame.is)'s blog post ['How I made an automated dynamic avatar for my Bluesky profile'](https://dame.is/blog/how-i-made-an-automated-dynamic-avatar-for-my-bluesky-profile).
8
9Developed primarily on macOS and intended for Linux deployment, this tool is designed to run within a virtual environment to isolate dependencies and ensure smooth operation.
10
11## Prerequisites
12
13Before running the script, please ensure you have the following:
14
15- Python 3.6 or later installed. For Ubuntu, run:
16
17 ```bash
18 sudo apt update && sudo apt install -y python3 python3-pip python3-dev
19 ```
20
21- The following Python packages (automatically installed if missing):
22 - `python-dotenv`
23 - `atproto`
24 - `requests`
25 - `python-magic`
26 - `python-crontab`
27- A valid Bluesky account with the necessary API credentials.
28- The script must be executed within a virtual environment.
29
30## Installation
31
321. **Clone the Repository:**
33
34 ```bash
35 git clone https://github.com/ewanc26/bluesky-avatar-updater.git
36 cd bluesky-avatar-updater
37 ```
38
392. **Ensure Virtual Environment Support:**
40 On Debian/Ubuntu systems, ensure that the `python3-venv` package is installed:
41
42 ```bash
43 sudo apt install python3-venv # Adjust the version if necessary (e.g., python3.10-venv)
44 ```
45
463. **Create and Activate a Virtual Environment:**
47
48 ```bash
49 python3 -m venv .venv
50 source .venv/bin/activate # On Windows use: .venv\Scripts\activate
51 ```
52
534. **Install Dependencies:**
54 With the virtual environment activated, install the required packages:
55
56 ```bash
57 pip install -r requirements.txt
58 ```
59
605. **Configure Environment Variables:**
61 - Place your `.env` file in the `assets` directory.
62 - The `.env` file should contain the following entries:
63
64 ```env
65 ENDPOINT=your_endpoint
66 HANDLE=your_handle
67 PASSWORD=your_password # App passwords are recommended
68 DID=your_did
69 UPDATE_BANNER=true # Set to 'true' to update the banner, or 'false' otherwise
70 ```
71
726. **Prepare the JSON File:**
73 Ensure that a `cids.json` file is located in the `assets` directory. This file should map each hour (in two-digit format) to the corresponding blob CIDs for the avatar (and optionally, the banner). For example:
74
75 ```json
76 {
77 "00": { "avatar": "cid_for_midnight", "banner": "banner_cid_for_midnight" },
78 "01": { "avatar": "cid_for_1am", "banner": "banner_cid_for_1am" }
79 }
80 ```
81
82## Usage
83
84To run the script, execute:
85
86```bash
87python -u ./src/main.py
88```
89
90Upon execution, the script will:
91
92- Verify that it is running within a virtual environment.
93- Load environment variables from the `.env` file located in the `assets` directory.
94- Read the blob CIDs from the `cids.json` file.
95- Determine the current hour and select the appropriate blob CIDs.
96- Perform a health check on the provided API endpoint.
97- Authenticate using the AT Protocol and update your Bluesky profile with the new avatar (and banner, if enabled).
98- Automatically set up a cron job to run the script every hour.
99- Log activity to both the console and a rotating log file in the `logs` directory. The log file rotates every 14 days (with up to 5 backups) and automatically deletes files older than 30 days.
100
101## Automating with Cron (Linux)
102
103The script is designed to automatically configure a cron job to run at the top of every hour. To verify the cron job, use:
104
105```bash
106crontab -l
107```
108
109If you prefer to manually set up or modify the cron job, follow these steps:
110
1111. Open the crontab editor:
112
113 ```bash
114 crontab -e
115 ```
116
1172. Add the following line (adjusting paths as necessary):
118
119 ```bash
120 0 * * * * /path/to/your/.venv/bin/python3 /path/to/bluesky-avatar-updater/src/main.py
121 ```
122
123## Troubleshooting
124
125- **Virtual Environment Issues:** The script will exit if it is not run within a virtual environment. Ensure you activate your virtual environment before running the script.
126- **Environment Variables Not Loading:** Verify that the `.env` file is correctly placed in the `assets` directory and contains all required entries.
127- **Missing Dependencies:** If the script encounters missing packages, run:
128
129 ```bash
130 pip install -r requirements.txt
131 ```
132
133 within your virtual environment.
134- **Endpoint Issues:** Ensure that the provided API endpoint is correct and accessible. The script performs a health check and will log an error if the endpoint is unresponsive.
135- **Cron Job Not Running:** If the cron job is not automatically set up, check with `crontab -l` or set it up manually using `crontab -e`.
136- **Log File Management:** The script manages log rotation and deletion automatically. If logs are not being deleted as expected, verify the file permissions in the `logs` directory.
137
138## License
139
140This project is released under the MIT License. Please refer to the [LICENSE](./LICENSE) file for full details.