social-media-manager

SocialManager — Personal Social Media Manager

A self-hosted, local-first social media management platform. Aggregate feeds from all your platforms, compose and cross-post content, schedule posts, and get AI-powered suggestions — all from one dashboard.

---

Features

• Unified Feed — Pull feeds from Twitter/X, Mastodon, Bluesky, LinkedIn, Instagram, Reddit and YouTube into a single dashboard
• Filter & Tag — Filter your feed by platform or custom tags
• Cross-post — Write once, publish to multiple platforms simultaneously
• Scheduler — Schedule posts for a specific date/time with BullMQ job queue
• AI Assistance — Grammar correction and platform-specific content adaptation (T5 model, runs locally)
• Multi-language UI — English and Turkish built-in; adding a new language is a single file
• Microservices — Each platform is an independent service, easy to add or remove
• Fully local — No SaaS, no subscriptions. Runs entirely on your machine via Docker

---

Tech Stack

Layer	Technology
Frontend	Vue 3, TypeScript, Vite, Tailwind CSS, Pinia, Vue Router, vue-i18n
API Gateway	Node.js / Fastify
Message Broker	RabbitMQ
Database	MongoDB
Job Queue	Redis + BullMQ
AI Service	Python / HappyTransformer (T5)
Platform SDKs	twitter-api-v2, masto, @atproto/api
Reverse Proxy	Nginx
Containerization	Docker Compose

---

Services

Service	Port	Description
nginx	8081	Reverse proxy — main entry point
ui	—	Vue 3 frontend (Vite dev server)
gateway	8084	REST API gateway
socket	8085	WebSocket server (real-time feed updates)
formatter	—	Platform-specific content formatter
ai-grammar-correction	—	AI grammar correction (T5)
feed-aggregator	3010	Pulls feeds from all platforms periodically
scheduler	3011	Scheduled post management (BullMQ)
twitter	3001	Twitter/X integration
linkedin	3002	LinkedIn integration
mastodon	3003	Mastodon integration
bluesky	3004	Bluesky (AT Protocol) integration
mongodb	27018	Database
redis	6379	Cache & job queue
messageBroker	5672 / 15672	RabbitMQ (+ management UI)

---

Getting Started

1. Clone the repository

git clone https://github.com/mehmetkirkoca/social-media-manager.git
cd social-media-manager

2. Configure environment

cp .env.example .env

Edit .env and fill in your API credentials for the platforms you want to use. You can start with just Mastodon or Bluesky — both have free, open APIs.

# Mastodon (easiest — get token from instance Settings > Development)
MASTODON_INSTANCE_URL=https://mastodon.social
MASTODON_ACCESS_TOKEN=your_token_here

# Bluesky (use an App Password from Settings > App Passwords)
BLUESKY_IDENTIFIER=yourhandle.bsky.social
BLUESKY_APP_PASSWORD=your_app_password_here

3. Start the application

docker compose up -d

Open http://localhost:8081 in your browser.

---

Platform Connection Guide

Platform	API Cost	Feed	Post	Notes
Mastodon	Free	✅	✅	Easiest — open REST API
Bluesky	Free	✅	✅	App Password auth, no OAuth needed
Reddit	Free	✅	✅	Register an app at reddit.com/prefs/apps
Twitter/X	Paid ($100/mo Basic)	⚠️	✅	Free tier very limited
LinkedIn	Free	⚠️	✅	Personal feed read not available via API
Instagram	Free	✅	✅	Business/Creator account + Facebook Page required
Facebook	Free	✅	✅	Facebook Page required (personal timelines not supported)
YouTube	Free	✅	❌	Subscription feed read-only

---

Instagram & Facebook Setup (Facebook Developer App)

Both Instagram and Facebook share one Facebook Developer App. You set it up once, then connect everything from the Settings UI — no token copying required.

Prerequisites

• A Facebook Developer account
• A Facebook Page (personal timelines are not supported by the Graph API)
• For Instagram: a Business or Creator Instagram account linked to that Facebook Page

---

Step 1 — Create a Facebook App

1. Go to developers.facebook.com/apps and click Create App
2. Choose Business as the app type and give it a name (e.g. SocialManager Local)
3. In Settings > Basic, note down your App ID and App Secret

---

Step 2 — Add Products & Permissions

In your app dashboard:

Facebook Login for Business

• Products > Facebook Login for Business > Set Up

• Under Client OAuth Settings, add to Valid OAuth Redirect URIs:

  http://localhost:8081/api/auth/meta/callback
  

(If hosting remotely, replace http://localhost:8081 with your APP_BASE_URL)

Instagram Graph API

• Products > Instagram Graph API > Set Up

Required Permissions

Enable in Development mode — no App Review needed for your own accounts:

Permission	Used for
pages_manage_posts	Post to Facebook Page
pages_read_engagement	Read Facebook Page feed
instagram_basic	Read Instagram media
instagram_content_publish	Publish Instagram posts
instagram_manage_insights	Required alongside content_publish

---

Step 3 — Connect from the Settings UI

1. Open http://localhost:8081/settings
2. In the Facebook & Instagram card, enter your App ID and App Secret → Save
3. Click Connect with Facebook & Instagram — this redirects you to Facebook's OAuth page
4. Authorise the app
5. You are returned to Settings with a page picker listing all your Facebook Pages and linked Instagram accounts
6. Check the ones you want to manage → Connect Selected

That's it. Tokens are stored in MongoDB — no .env editing required. You can connect multiple Pages and Instagram accounts simultaneously.

---

Token Notes

Token	Expiry	How it is handled
Short-lived user token	1–2 hours	Exchanged automatically during OAuth
Long-lived user token	~60 days	Stored in MongoDB; reconnect via Settings when it expires
Page access token	Never expires	Fetched during OAuth and stored; does not need refreshing

Instagram publishing: Instagram does not support text-only posts via the Graph API. Every post requires at least one image URL (imageUrl) or video URL (videoUrl) in addition to the caption. The compose view will need these fields when targeting Instagram.

---

Adding a New Language

1. Create ui/src/locales/xx.ts (copy en.ts and translate)

2. In ui/src/locales/index.ts:

   import xx from './xx'
   // Add to messages: { en, tr, xx }
   // Add to SUPPORTED_LOCALES: { code: 'xx', label: '...', flag: '🇽🇽' }
   

3. Done — language will appear in the NavBar dropdown automatically

---

Adding a New Platform

1. Create services/{platform}/ with index.js, package.json, Dockerfile
2. Extend BasePlatformService and implement fetchFeed(), publishPost(), getStatus()
3. Add the service to docker-compose.yml
4. Add the service URL to feed-aggregator and scheduler environment variables
5. Add platform metadata to ui/src/stores/platforms.ts

---

Project Structure

.
├── services/
│   ├── utils/               # Shared: RabbitMQ, MongoDB, BasePlatformService
│   ├── gateway/             # API gateway
│   ├── socket/              # WebSocket server
│   ├── formatter/           # Content formatter
│   ├── ai_grammar_correction/
│   ├── feed-aggregator/
│   ├── scheduler/
│   ├── twitter/
│   ├── linkedin/
│   ├── mastodon/
│   └── bluesky/
├── ui/
│   └── src/
│       ├── views/           # Dashboard, Compose, Scheduler, Settings
│       ├── components/
│       ├── stores/          # Pinia: feed, compose, platforms
│       ├── locales/         # i18n: en, tr
│       └── router/
├── docs/                    # Architecture, roadmap, platform guides (gitignored)
├── docker-compose.yml
├── nginx.conf
└── .env.example

---

License

LICENSE.txt