Cross-posts between Mastodon or GoToSocial and Bluesky, with threads and hashtag filters.
  • Python 98.9%
  • Dockerfile 1.1%
Find a file
2025-11-06 20:39:09 -05:00
.dockerignore Initial commit 2025-11-06 01:12:59 -05:00
.gitignore gitignore 2025-11-06 14:49:32 -05:00
bluesky_client.py fix hashtags 2025-11-06 20:39:09 -05:00
config.example.env fix for version error 2025-11-06 01:51:42 -05:00
crosspost.py update for README, add thread support, and fix links. 2025-11-06 14:05:39 -05:00
database.py Initial commit 2025-11-06 01:12:59 -05:00
docker-compose.yml Initial commit 2025-11-06 01:12:59 -05:00
Dockerfile Initial commit 2025-11-06 01:12:59 -05:00
main.py Initial commit 2025-11-06 01:12:59 -05:00
mastodon_client.py fix hashtags 2025-11-06 20:39:09 -05:00
README.md update for README, add thread support, and fix links. 2025-11-06 14:05:39 -05:00
requirements.txt Initial commit 2025-11-06 01:12:59 -05:00

Social Media Cross-Poster

A self-hosted application for cross-posting between GoToSocial/Mastodon and Bluesky. Designed to run in a Docker container on your homelab.

Features

  • Bidirectional Sync: Automatically cross-post between Mastodon/GoToSocial and Bluesky
  • Thread Support: Long posts (>300 chars) are automatically split into threaded posts on Bluesky
  • Link Preservation: URLs in GTS/Mastodon posts are preserved when cross-posting to Bluesky
  • Media Support: Syncs images and other media attachments
  • Flexible Configuration: Choose sync direction (both ways, or one-way only)
  • Hashtag Filtering: Optionally sync only posts with specific hashtags
  • Duplicate Prevention: Tracks synced posts to avoid duplicates
  • Docker Ready: Easy deployment with Docker Compose
  • GoToSocial Compatible: Full support for GoToSocial instances via ActivityPub

Prerequisites

  • Docker and Docker Compose
  • A Mastodon or GoToSocial account with API access
  • A Bluesky account with an app password

Quick Start

1. Get the Code

Option A: Clone from Git (if you've forked/hosted this repo)

# Clone to your preferred location
git clone https://github.com/yourusername/social-media-crossposter.git
cd social-media-crossposter

Option B: Download directly

# If you have the code locally, just navigate to it:
cd /path/to/social-media-crossposter

# Or copy/download the files to your homelab apps directory:
cd /path/to/your/homelab/apps
# Copy the project files here

2. Get API Credentials

For Mastodon:

  1. Log into your instance
  2. Go to Settings → Development → New Application
  3. Give it a name (e.g., "Cross-Poster")
  4. Set scopes: read:statuses, write:statuses, write:media
  5. Copy the access token

For GoToSocial:

GoToSocial doesn't have a web UI for creating application tokens, so you need to use the API directly with curl:

Step 1: Register your application

curl -X POST https://your-gts-instance.social/api/v1/apps \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Cross-Poster",
    "redirect_uris": "urn:ietf:wg:oauth:2.0:oob",
    "scopes": "read write"
  }'

This will return a JSON response with client_id and client_secret. Save these values.

Step 2: Generate an access token

curl -X POST https://your-gts-instance.social/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID_FROM_STEP_1",
    "client_secret": "YOUR_CLIENT_SECRET_FROM_STEP_1",
    "redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
    "grant_type": "password",
    "username": "your_gts_username",
    "password": "your_gts_password",
    "scope": "read write"
  }'

This will return a JSON response with access_token. This is what you'll use in your .env file.

Example complete flow:

# Step 1: Register app
RESPONSE=$(curl -s -X POST https://gts.example.com/api/v1/apps \
  -H "Content-Type: application/json" \
  -d '{"client_name":"Cross-Poster","redirect_uris":"urn:ietf:wg:oauth:2.0:oob","scopes":"read write"}')

CLIENT_ID=$(echo $RESPONSE | grep -o '"client_id":"[^"]*' | cut -d'"' -f4)
CLIENT_SECRET=$(echo $RESPONSE | grep -o '"client_secret":"[^"]*' | cut -d'"' -f4)

echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"

# Step 2: Get access token (replace USERNAME and PASSWORD)
curl -X POST https://gts.example.com/oauth/token \
  -H "Content-Type: application/json" \
  -d "{
    \"client_id\":\"$CLIENT_ID\",
    \"client_secret\":\"$CLIENT_SECRET\",
    \"redirect_uri\":\"urn:ietf:wg:oauth:2.0:oob\",
    \"grant_type\":\"password\",
    \"username\":\"your_username\",
    \"password\":\"your_password\",
    \"scope\":\"read write\"
  }"

The final response will include your access_token that you can use in the .env file.

For Bluesky:

  1. Log into Bluesky
  2. Go to Settings → App Passwords
  3. Create a new app password
  4. Copy the password (you won't see it again!)

3. Configure

Copy the example configuration:

cp config.example.env .env

Edit .env with your credentials:

# Mastodon/GoToSocial Configuration
MASTODON_INSTANCE_URL=https://your-instance.social
MASTODON_ACCESS_TOKEN=your_access_token_here

# Bluesky Configuration
# NOTE: Do NOT include the @ symbol in your handle
BLUESKY_HANDLE=yourhandle.bsky.social
BLUESKY_APP_PASSWORD=your_app_password_here

# Cross-posting Settings
POLL_INTERVAL_SECONDS=300
SYNC_DIRECTION=both  # Options: both, mastodon_to_bluesky, bluesky_to_mastodon

# Bootstrap mode: Set to 'true' on first run to mark existing posts as synced WITHOUT posting them
# After first run, set back to 'false' to enable normal cross-posting
BOOTSTRAP_MODE=true

# Optional: Hashtag filter (comma-separated, leave empty to sync all posts)
HASHTAG_FILTER=

# Database
DATABASE_PATH=/data/crosspost.db

Important Notes:

  • Bluesky Handle: Use yourhandle.bsky.social NOT @yourhandle.bsky.social
  • No Quotes Needed: Values don't need quotes unless they contain spaces
  • GoToSocial Users: Use read write scopes (not the granular read:statuses format). See the curl instructions above for generating tokens via API.

4. Run with Docker Compose

First Run (with bootstrap mode to prevent syncing old posts):

# Make sure BOOTSTRAP_MODE=true in .env
docker-compose up -d
docker-compose logs -f  # Wait for one sync cycle to complete
docker-compose down
# Edit .env and set BOOTSTRAP_MODE=false
docker-compose up -d

Normal Operation:

docker-compose up -d

To view logs:

docker-compose logs -f

To stop:

docker-compose down

Configuration Options

Variable Description Default Required
MASTODON_INSTANCE_URL Your Mastodon/GoToSocial instance URL - Yes
MASTODON_ACCESS_TOKEN API access token - Yes
BLUESKY_HANDLE Your Bluesky handle - Yes
BLUESKY_APP_PASSWORD Bluesky app password - Yes
POLL_INTERVAL_SECONDS How often to check for new posts (in seconds) 300 No
SYNC_DIRECTION Direction of sync both No
BOOTSTRAP_MODE Mark existing posts as synced without posting false No
HASHTAG_FILTER Comma-separated hashtags to filter (without #) - No
DATABASE_PATH Path to SQLite database /data/crosspost.db No

Sync Direction Options

  • both: Sync posts in both directions (Mastodon ↔ Bluesky)
  • mastodon_to_bluesky: Only sync from Mastodon to Bluesky
  • bluesky_to_mastodon: Only sync from Bluesky to Mastodon

Hashtag Filtering

To only sync posts with specific hashtags:

HASHTAG_FILTER=crosspost,sync,public

This will only sync posts containing #crosspost, #sync, or #public.

Bootstrap Mode (First Run)

IMPORTANT: On first run, you should use bootstrap mode to prevent syncing historical posts.

When you first start the application, it will see all your recent posts (up to 20) as "new" and try to cross-post them. To prevent this:

  1. Set BOOTSTRAP_MODE=true in your .env file
  2. Start the application: docker-compose up -d
  3. Let it run for one sync cycle (check logs: docker-compose logs -f)
  4. Stop the application: docker-compose down
  5. Set BOOTSTRAP_MODE=false in your .env file
  6. Start the application again: docker-compose up -d

In bootstrap mode, the application will:

  • Fetch recent posts from both platforms
  • Mark them as already synced in the database
  • NOT actually post them to the other platform

After bootstrap mode, only NEW posts will be cross-posted going forward.

How It Works

  1. The application polls both platforms at regular intervals (default: 5 minutes)
  2. It checks for new posts from your account
  3. Posts are checked against the sync database to avoid duplicates
  4. If configured, posts are filtered by hashtags
  5. New posts are cross-posted to the other platform
  6. Media attachments (images) are downloaded and re-uploaded
  7. The sync status is saved to the database

What Gets Synced

  • Original posts (not replies or boosts/reposts)
  • Text content (with links preserved)
  • Image attachments (up to 4 images)
  • Long posts are automatically split into threads when cross-posting to Bluesky

What Doesn't Get Synced

  • Replies to other users
  • Boosts/reposts
  • Polls
  • Videos (currently not supported)

Troubleshooting

Check logs

docker-compose logs -f crosspost

Permission issues

If you get database permission errors, create the data directory:

mkdir -p data
chmod 777 data

Posts not syncing

  1. Check that your API credentials are correct
  2. Verify the poll interval isn't too long
  3. Check logs for errors
  4. Ensure posts aren't filtered by hashtag settings
  5. Make sure posts aren't replies or boosts

Character limit handling

  • Bluesky: 300 characters max
  • Mastodon: Usually 500 characters (varies by instance)
  • GoToSocial: Usually 5000 characters

GTS → Bluesky: Posts exceeding 300 characters are automatically split into threaded posts with indicators like (1/3), (2/3), (3/3)

Bluesky → Mastodon/GTS: Posts exceeding the instance limit are truncated with "..."

Running Without Docker

If you prefer to run without Docker:

# Install Python 3.11+
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create .env file with your configuration
cp config.example.env .env
# Edit .env with your credentials

# Create data directory
mkdir -p data

# Run
python main.py

Data Persistence

The application uses SQLite to track synced posts. The database is stored in the ./data directory by default, which is mounted as a Docker volume. This ensures:

  • Posts aren't duplicated after container restarts
  • Sync history is preserved
  • You can back up the database for migration

Security Notes

  • Keep your .env file secure and never commit it to version control
  • Use app-specific passwords when possible
  • The application only needs read and write access to posts, not full account access
  • Regular Mastodon/GoToSocial access tokens can be regenerated if compromised
  • Bluesky app passwords can be revoked and recreated
  • GoToSocial curl authentication: When using curl to generate tokens, your password may be stored in bash history. Consider clearing it afterward (history -c) or using environment variables instead of typing passwords directly in commands

Limitations

  • Only syncs your own posts (not posts from others)
  • Doesn't sync replies or boosts/reposts
  • Video support not yet implemented
  • Poll support not yet implemented
  • Existing threads from GTS/Mastodon are synced as individual posts (but long individual posts are threaded automatically)

Contributing

This is a personal project, but suggestions and improvements are welcome!

License

MIT License - feel free to use and modify as needed.

Support

For issues or questions, please check the logs first. Most problems are related to:

  • Incorrect API credentials
  • Network connectivity
  • Platform API rate limits
  • Character limit truncation

Acknowledgments

Built with: