Skip to content

Commit 8490fa2

Browse files
bupdbupd
authored
Merge pull request #6 from bupd/docs
2 parents 37db91d + b2f1a45 commit 8490fa2

1 file changed

Lines changed: 107 additions & 63 deletions

File tree

‎README.md‎

Lines changed: 107 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,51 @@
11
# shitpost
22

3-
Simple crossposting bridge that accepts text, photos, videos, and documents via a [Telegram bot](https://t.me/shitpost_engine_bot), runs the [crosspost](https://github.com/humanwhocodes/crosspost) CLI to publish them across social platforms.
3+
Telegram-powered social media crossposting tool. Post once to Telegram, publish everywhere.
44

5-
## Quick summary
6-
- Listens for posts using Telegram Bot.
7-
- Calls the `crosspost` CLI to publish (text-only or with image + alt text).
8-
- Built as a lightweight abstraction over [humanwhocodes/crosspost](https://github.com/humanwhocodes/crosspost) (see that repo for crosspost-specific configuration).
5+
Accept text, photos, videos, and documents via a [Telegram bot](https://t.me/shitpost_engine_bot), then publish them across all your social platforms simultaneously.
96

7+
A lightweight, self-hosted alternative to Postiz, Buffer, and Hootsuite for developers who want full control over their social media automation.
108

119
## Motivation
10+
1211
- I am fed up with posting and managing different platforms.
1312
- I have multiple thoughts popping up in my head which I would like to convey to people
1413
- But I lack the patience to go through multiple different apps just to say something...
1514
- And to update the content based on the app is more hated.
1615

17-
18-
## Requirements
19-
- Podman/Docker & Compose (recommended) or Go 1.25+ to build/run locally.
20-
- A Telegram bot token (create via @BotFather).
16+
## Features
17+
18+
- Post to multiple social networks simultaneously from Telegram
19+
- Supports text, images, videos, and documents
20+
- Alt-text support for accessible image posts
21+
- Self-hosted and privacy-focused
22+
- Multi-arch Docker images (amd64, arm64)
23+
- Lightweight Go binary with minimal dependencies
24+
25+
## Supported Platforms
26+
27+
| Platform | Text | Images | Videos |
28+
|----------|------|--------|--------|
29+
| Twitter/X | Yes | Yes | Yes |
30+
| Bluesky | Yes | Yes | Yes |
31+
| Mastodon | Yes | Yes | Yes |
32+
| LinkedIn | Yes | Yes | No |
33+
| Discord | Yes | Yes | Yes |
34+
| Telegram | Yes | Yes | Yes |
35+
| Slack | Yes | Yes | No |
36+
| Dev.to | Yes | No | No |
37+
| Nostr | Yes | No | No |
38+
39+
## Why shitpost?
40+
41+
| Feature | shitpost | Postiz | Buffer |
42+
|---------|----------|--------|--------|
43+
| Self-hosted | Yes | Yes | No |
44+
| Free | Yes | Freemium | Freemium |
45+
| Telegram interface | Yes | No | No |
46+
| No web UI required | Yes | No | No |
47+
| Privacy-focused | Yes | Partial | No |
48+
| Open source | Yes | Yes | No |
2149

2250
## Docker Images
2351

@@ -88,86 +116,102 @@ For production, use a versioned tag (e.g., `v1.0.0`) to avoid unexpected updates
88116

89117
5. Send messages or media to your bot in Telegram. The bot will post using crosspost and reply with logs.
90118

119+
## Requirements
91120

92-
## Environment variables
121+
- Docker/Podman (recommended) or Go 1.25+
122+
- Telegram bot token (create via [@BotFather](https://t.me/BotFather))
123+
- API keys for target platforms (Twitter, Bluesky, Mastodon, etc.)
93124

94-
- BOT_TOKEN (required) — Telegram bot token from BotFather.
125+
## Environment Variables
95126

96-
crosspost itself may require additional environment variables (API keys, tokens for target platforms). For details about those envs and how to obtain them, consult:
97-
https://github.com/humanwhocodes/crosspost
127+
| Variable | Required | Description |
128+
|----------|----------|-------------|
129+
| `BOT_TOKEN` | Yes | Telegram bot token from BotFather |
130+
| `TWITTER_API_CONSUMER_KEY` | No | Twitter API consumer key |
131+
| `TWITTER_API_CONSUMER_SECRET` | No | Twitter API consumer secret |
132+
| `TWITTER_ACCESS_TOKEN_KEY` | No | Twitter access token |
133+
| `TWITTER_ACCESS_TOKEN_SECRET` | No | Twitter access token secret |
134+
| `BLUESKY_HOST` | No | Bluesky host (e.g., bsky.social) |
135+
| `BLUESKY_IDENTIFIER` | No | Bluesky handle or email |
136+
| `BLUESKY_PASSWORD` | No | Bluesky app password |
137+
| `MASTODON_HOST` | No | Mastodon instance URL |
138+
| `MASTODON_ACCESS_TOKEN` | No | Mastodon access token |
98139

99-
Use .env (or docker-compose env_file) to supply values.
140+
crosspost itself may require additional environment variables (API keys, tokens for target platforms). For details about those envs and how to obtain them, consult the [crosspost documentation](https://github.com/humanwhocodes/crosspost).
100141

142+
## Usage
101143

102-
## Telegram usage / caption rules
144+
### Text Posts
145+
Send any text message to your bot. It will be posted to all configured platforms.
103146

104-
- Text messages: posted as text via crosspost.
105-
- Images/videos/documents: downloaded and posted via crosspost.
106-
- Alt-text parsing: if the last line of the caption starts with `alt:` (case-insensitive), that line is removed from the caption and used as the image alt text.
107-
Example:
108-
```
109-
Here’s the pic
110-
alt: A smiling cat on a red blanket
111-
```
147+
### Media Posts
148+
Send images, videos, or documents with an optional caption.
112149

150+
### Alt Text
151+
Add alt text for accessibility by ending your caption with `alt:`:
152+
```
153+
Check out this sunset!
154+
alt: Orange and purple sunset over mountains
155+
```
113156

114-
## Running locally (without Docker)
157+
## Running Locally (without Docker)
115158

116-
1. Ensure Go 1.25+ is installed.
117-
2. Install dependencies:
118-
```
119-
go mod download
120-
```
121-
3. Build:
122-
```
123-
CGO_ENABLED=0 GOOS=linux go build -o bot main.go
124-
```
125-
4. Export BOT_TOKEN and run:
159+
1. Install Go 1.25+ and crosspost CLI:
160+
```sh
161+
npm install -g @humanwhocodes/crosspost
126162
```
127-
export BOT_TOKEN=123456:ABC-DEF...
163+
164+
2. Build and run:
165+
```sh
166+
go build -o bot main.go
167+
export BOT_TOKEN=your_token_here
128168
./bot
129169
```
130170

131-
Note: When running locally, make sure the `crosspost` CLI is available in your PATH (install it with npm: npm install -g @humanwhocodes/crosspost) or adjust PATH accordingly.
132-
133-
134-
## Persistence & volumes
135-
- Media downloaded from Telegram are stored at ./downloads in the repo root (mounted to /app/downloads in the container). Keep this folder secure or change the mapping if needed.
171+
## Architecture
136172

173+
```
174+
Telegram → shitpost bot → crosspost CLI → Social platforms
175+
```
137176

138-
## Security & privacy notes
139-
- The bot downloads user media to local storage — protect the host and mounted volumes.
140-
- crosspost stdout/stderr are returned to the chat; ensure crosspost does not leak secrets or sensitive tokens in logs.
141-
- Consider implementing user allowlists if the bot will be public-facing (not implemented by default).
177+
Built as a lightweight wrapper around [humanwhocodes/crosspost](https://github.com/humanwhocodes/crosspost).
142178

179+
## Security
143180

181+
- Self-hosted: your data stays on your server
182+
- No third-party analytics or tracking
183+
- Media files stored locally (configure volume mounts)
184+
- Consider implementing allowlists for public-facing bots
144185

145186
## Troubleshooting
146187

147-
- Bot fails on startup:
148-
- Ensure BOT_TOKEN is set and valid.
149-
- Check container logs: docker compose logs -f
188+
### Bot fails on startup
189+
- Verify `BOT_TOKEN` is set correctly
190+
- Check logs: `docker compose logs -f`
150191

151-
- crosspost not found:
152-
- Dockerfile installs crosspost globally; if running locally, install it with:
153-
npm install -g @humanwhocodes/crosspost
154-
- Or ensure crosspost binary is on PATH.
192+
### Posts not appearing
193+
- Verify platform API keys are configured
194+
- Check crosspost output in bot logs
155195

156-
- Files not saved:
157-
- Ensure ./downloads exists and is writeable by the container/user.
158-
- The compose file maps ./downloads to /app/downloads; permissions on host may need adjusting.
196+
### Media not uploading
197+
- Ensure `./downloads` directory exists and is writable
198+
- Check disk space
159199

200+
## Contributing
160201

161-
## Development notes & roadmap (short)
162-
- Add allowlist/denylist for users or groups.
163-
- Add config options to control whether the posted file is returned.
164-
- Add graceful shutdown handling.
165-
- Add tests.
166-
- Improve logging and error reporting.
202+
Contributions welcome! Please open an issue or PR.
167203

168204
## License
169-
See LICENSE in the repository.
170205

171-
References
172-
- crosspost: https://github.com/humanwhocodes/crosspost
206+
See [LICENSE](LICENSE) in the repository.
207+
208+
## Related Projects
209+
210+
- [crosspost](https://github.com/humanwhocodes/crosspost) - CLI tool powering the cross-posting
211+
- [Postiz](https://github.com/gitroomhq/postiz-app) - Full-featured social media scheduler
212+
- [Buffer](https://buffer.com) - Commercial social media management
213+
214+
## GitHub Topics
173215

216+
Add these topics to your repository for better discoverability:
217+
`crosspost`, `social-media`, `telegram-bot`, `twitter`, `bluesky`, `mastodon`, `automation`, `self-hosted`, `golang`, `docker`

0 commit comments

Comments
 (0)