A simple tool which lets you scrape twitter accounts and crosspost them to bluesky accounts! Comes with a CLI and a webapp for managing profiles! Works with images/videos/link embeds/threads.
Make Docker the default README quick start
Lead with a cross-platform Docker run flow, switch primary pull examples to Docker Hub, and keep source installs as an alternative path so new users can get running with one command.
+82
-21
+82
-21
README.md
+82
-21
README.md
···
2
2
3
3
Crosspost posts from Twitter/X to Bluesky with thread support, media handling, account mapping, and a web dashboard.
4
4
5
-
## Quick Start (Easy Mode)
5
+
## Quick Start (Recommended: Docker)
6
+
7
+
Most people should use Docker. It is the simplest setup and includes full feature parity (backend API + scheduler + frontend dashboard + Chromium).
8
+
9
+
Prerequisite: Docker Desktop (Windows/macOS) or Docker Engine (Linux). On Windows, use Docker Desktop in Linux container mode.
10
+
11
+
### 1) Run the latest image
12
+
13
+
macOS/Linux (bash):
14
+
15
+
```bash
16
+
docker run -d \
17
+
--name tweets-2-bsky \
18
+
-p 3000:3000 \
19
+
-v tweets2bsky_data:/app/data \
20
+
--restart unless-stopped \
21
+
j4ckxyz/tweets-2-bsky:latest
22
+
```
23
+
24
+
Windows (PowerShell):
25
+
26
+
```powershell
27
+
docker run -d --name tweets-2-bsky -p 3000:3000 -v tweets2bsky_data:/app/data --restart unless-stopped j4ckxyz/tweets-2-bsky:latest
28
+
```
29
+
30
+
Open `http://localhost:3000`.
31
+
32
+
If port `3000` is already in use, change only the first port (example: `-p 3001:3000`).
33
+
34
+
### 2) Complete first-time setup
35
+
36
+
1. Register the first user (this user becomes admin).
37
+
2. Add Twitter cookies in Settings.
38
+
3. Add at least one mapping.
39
+
4. Click `Run now`.
40
+
41
+
### 3) Useful Docker commands
42
+
43
+
```bash
44
+
docker logs -f tweets-2-bsky
45
+
docker exec -it tweets-2-bsky node dist/cli.js status
46
+
docker stop tweets-2-bsky
47
+
docker start tweets-2-bsky
48
+
```
49
+
50
+
### 4) Update to newest release
51
+
52
+
```bash
53
+
docker pull j4ckxyz/tweets-2-bsky:latest
54
+
docker stop tweets-2-bsky
55
+
docker rm tweets-2-bsky
56
+
docker run -d \
57
+
--name tweets-2-bsky \
58
+
-p 3000:3000 \
59
+
-v tweets2bsky_data:/app/data \
60
+
--restart unless-stopped \
61
+
j4ckxyz/tweets-2-bsky:latest
62
+
```
63
+
64
+
Alternative image registry: `ghcr.io/j4ckxyz/tweets-2-bsky:latest`.
6
65
7
-
If you are comfortable with terminal basics but do not want to manage PM2 manually, use the installer script.
66
+
## Source Install Quick Start (No Docker)
67
+
68
+
If you prefer running from source and do not want to manage PM2 manually, use the installer script.
8
69
9
70
### 1) Clone the repo
10
71
···
30
91
- otherwise uses `nohup`
31
92
- prints your local web URL (for example `http://localhost:3000`)
32
93
33
-
### 3) Open the dashboard
34
-
35
-
Open the printed URL in your browser, then:
36
-
37
-
1. Register the first user (this user becomes admin).
38
-
2. Add Twitter cookies in Settings.
39
-
3. Add at least one mapping.
40
-
4. Click `Run now`.
41
-
42
94
### Useful installer commands
43
95
44
96
```bash
···
51
103
./install.sh --skip-native-rebuild
52
104
```
53
105
54
-
If you prefer full manual setup, skip to [Manual Setup](#manual-setup-technical). For a portable single-container setup, use [Docker](#docker-single-container-backend--frontend--scheduler).
106
+
If you prefer full manual source setup details, skip to [Manual Setup](#manual-setup-technical).
107
+
108
+
After source install starts, open `http://localhost:3000` and follow the first-time setup steps in [Quick Start](#quick-start-recommended-docker).
55
109
56
110
## Docker (Single-Container, Backend + Frontend + Scheduler)
57
111
···
74
128
-p 3000:3000 \
75
129
-v tweets2bsky_data:/app/data \
76
130
--restart unless-stopped \
77
-
ghcr.io/j4ckxyz/tweets-2-bsky:latest
131
+
j4ckxyz/tweets-2-bsky:latest
78
132
```
79
133
80
134
Open `http://localhost:3000`.
···
82
136
PowerShell equivalent:
83
137
84
138
```powershell
85
-
docker run -d --name tweets-2-bsky -p 3000:3000 -v tweets2bsky_data:/app/data --restart unless-stopped ghcr.io/j4ckxyz/tweets-2-bsky:latest
139
+
docker run -d --name tweets-2-bsky -p 3000:3000 -v tweets2bsky_data:/app/data --restart unless-stopped j4ckxyz/tweets-2-bsky:latest
86
140
```
141
+
142
+
Alternative registry mirror: `ghcr.io/j4ckxyz/tweets-2-bsky:latest`.
87
143
88
144
### 2) Build locally (if you do not want to pull)
89
145
···
108
164
-p 3000:3000 \
109
165
-v tweets2bsky_data:/app/data \
110
166
--env-file .env \
111
-
ghcr.io/j4ckxyz/tweets-2-bsky:latest
167
+
j4ckxyz/tweets-2-bsky:latest
112
168
```
113
169
114
170
Common variables:
···
144
200
For Docker installs, update by pulling a newer image and recreating the container with the same volume:
145
201
146
202
```bash
147
-
docker pull ghcr.io/j4ckxyz/tweets-2-bsky:latest
203
+
docker pull j4ckxyz/tweets-2-bsky:latest
148
204
docker stop tweets-2-bsky
149
205
docker rm tweets-2-bsky
150
206
docker run -d \
···
152
208
-p 3000:3000 \
153
209
-v tweets2bsky_data:/app/data \
154
210
--restart unless-stopped \
155
-
ghcr.io/j4ckxyz/tweets-2-bsky:latest
211
+
j4ckxyz/tweets-2-bsky:latest
156
212
```
157
213
158
214
### 7) Platform support
···
184
240
gh secret set DOCKERHUB_TOKEN --body "<dockerhub-access-token>"
185
241
```
186
242
187
-
If you keep your default branch as `master`, users can always pull the newest build with:
243
+
Users can always pull the newest build with:
188
244
189
245
```bash
190
-
docker pull ghcr.io/j4ckxyz/tweets-2-bsky:latest
246
+
docker pull j4ckxyz/tweets-2-bsky:latest
191
247
```
192
248
193
249
#### Option A: GitHub Container Registry (GHCR)
···
276
332
277
333
## Requirements
278
334
335
+
Recommended runtime:
336
+
337
+
- Docker Desktop / Docker Engine
338
+
339
+
If running from source instead of Docker:
340
+
279
341
- Node.js 22+
280
342
- npm
281
343
- git
282
344
283
-
Optional but recommended:
345
+
Optional but recommended for source installs:
284
346
285
347
- PM2 (for managed background runtime)
286
348
- Chrome/Chromium (used for some quote-tweet screenshot fallbacks)
287
349
- build tools for native modules (`better-sqlite3`) if your platform needs source compilation
288
-
- Docker Desktop / Docker Engine (if using containerized deployment)
289
350
290
351
## Manual Setup (Technical)
291
352