This repository has no description
Automated commit: update changes
author
Ewan Croft
date
(May 27, 2026, 6:16 PM +0100)
commit
296b9ded
296b9deda6884d8b24196ccde5884d06d1a0af10
parent
964fee93
964fee9346c1f81003db5d975a6c5ec5fccb807b
+49
-89
+49
-89
README.md
+49
-89
README.md
···
1
1
# Bluesky Avatar Updater
2
2
3
-
***This repository is available on [GitHub](https://github.com/ewanc26/bluesky-avatar-updater) and [Tangled](https://tangled.sh/did:plc:ofrbh253gwicbkc5nktqepol/bluesky-avatar-updater). GitHub is the primary version, and the Tangled version is a mirror.***
3
+
**_This repository is available on [GitHub](https://github.com/ewanc26/bluesky-avatar-updater) and [Tangled](https://tangled.sh/did:plc:ofrbh253gwicbkc5nktqepol/bluesky-avatar-updater). GitHub is the primary version, and the Tangled version is a mirror._**
4
4
5
5
## Overview
6
6
7
-
This 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).
7
+
This repository contains a Python script that updates a Bluesky profile avatar, and optionally a banner, based on the current hour. It looks up blob CIDs in `assets/cids.json`, fetches the blobs from the configured endpoint, and updates the profile record through the AT Protocol.
8
8
9
-
Developed 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.
9
+
The script also performs a health check against the endpoint, writes logs to `logs/update.log`, rotates logs every 14 days with up to 5 backups, removes old logs older than 30 days at startup, and installs an hourly cron job so the update runs automatically.
10
10
11
-
## Prerequisites
11
+
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).
12
12
13
-
Before running the script, please ensure you have the following:
13
+
> 🧶 Also available on [Tangled](https://tangled.org/ewancroft.uk/bluesky-avatar-updater)
14
14
15
-
- Python 3.6 or later installed. For Ubuntu, run:
15
+
## Requirements
16
+
17
+
- Python 3.6 or later
18
+
- A virtual environment
19
+
- Python packages from `requirements.txt`
20
+
- A valid Bluesky account with app password access
21
+
- A working AT Protocol endpoint that serves the blobs referenced in `cids.json`
16
22
17
-
```bash
18
-
sudo apt update && sudo apt install -y python3 python3-pip python3-dev
19
-
```
23
+
Install the Python dependencies with:
20
24
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.
25
+
```bash
26
+
pip install -r requirements.txt
27
+
```
29
28
30
-
## Installation
29
+
## Setup
31
30
32
-
1. **Clone the Repository:**
31
+
1. Clone the repository:
33
32
34
33
```bash
35
34
git clone https://github.com/ewanc26/bluesky-avatar-updater.git
36
35
cd bluesky-avatar-updater
37
36
```
38
37
39
-
2. **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
-
46
-
3. **Create and Activate a Virtual Environment:**
38
+
2. Create and activate a virtual environment:
47
39
48
40
```bash
49
41
python3 -m venv .venv
50
-
source .venv/bin/activate # On Windows use: .venv\Scripts\activate
42
+
source .venv/bin/activate
51
43
```
52
44
53
-
4. **Install Dependencies:**
54
-
With the virtual environment activated, install the required packages:
45
+
3. Create `assets/.env` with:
55
46
56
-
```bash
57
-
pip install -r requirements.txt
47
+
```env
48
+
ENDPOINT=your_endpoint
49
+
HANDLE=your_handle
50
+
PASSWORD=your_app_password
51
+
DID=your_did
52
+
UPDATE_BANNER=false
58
53
```
59
54
60
-
5. **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
-
72
-
6. **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:
55
+
4. Create `assets/cids.json` with hourly blob mappings:
74
56
75
57
```json
76
58
{
77
-
"00": { "avatar": "cid_for_midnight", "banner": "banner_cid_for_midnight" },
59
+
"00": {
60
+
"avatar": "cid_for_midnight",
61
+
"banner": "banner_cid_for_midnight"
62
+
},
78
63
"01": { "avatar": "cid_for_1am", "banner": "banner_cid_for_1am" }
79
64
}
80
65
```
81
66
82
67
## Usage
83
68
84
-
To run the script, execute:
69
+
Run the updater from the repository root while the virtual environment is active:
85
70
86
71
```bash
87
72
python -u ./src/main.py
88
73
```
89
74
90
-
Upon execution, the script will:
75
+
On start-up, the script will:
91
76
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.
77
+
1. Verify that it is running inside a virtual environment
78
+
2. Load `assets/.env`
79
+
3. Confirm the endpoint is healthy
80
+
4. Read the CID mapping from `assets/cids.json`
81
+
5. Select the avatar CID for the current hour
82
+
6. Log in to Bluesky and update the profile record
83
+
7. Ensure an hourly cron job exists for future runs
100
84
101
-
## Automating with Cron (Linux)
85
+
## Notes
102
86
103
-
The 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
106
-
crontab -l
107
-
```
108
-
109
-
If you prefer to manually set up or modify the cron job, follow these steps:
110
-
111
-
1. Open the crontab editor:
112
-
113
-
```bash
114
-
crontab -e
115
-
```
116
-
117
-
2. 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
-
```
87
+
- `UPDATE_BANNER=true` enables banner updates when a banner CID is present for the current hour.
88
+
- The endpoint value is normalised to HTTPS if necessary.
89
+
- The script expects the endpoint to support `/_health` and `com.atproto.sync.getBlob`.
122
90
123
91
## Troubleshooting
124
92
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.
93
+
- If the script exits immediately, double-check that the virtual environment is active.
94
+
- If authentication fails, confirm the handle and app password are correct.
95
+
- If blob fetching fails, make sure the endpoint can access the DID/CID pair in `cids.json`.
96
+
- If cron does not install, verify that `python-crontab` is available in the virtual environment.
137
97
138
98
## License
139
99