github.com/brightbeanxyz/brightbean-studio @main sqlite

Open-source social media management for creators, agencies, and SMBs.

---

About BrightBean Studio

BrightBean Studio is an open-source, self-hostable social media management platform built for creators, agencies and SMBs. It does what Sendible, SocialPilot, or ContentStudio do, but free and without per-seat, per-channel, or per-workspace limits. Plan, compose, schedule, approve, publish, and monitor content across Facebook, Instagram, LinkedIn, TikTok, YouTube, Pinterest, Threads, Bluesky, Google Business Profile, Mastodon, and DEV.to from a single multi-workspace dashboard.

It's for people managing many client accounts under one roof who'd rather own their social stack than pay $100–300/month to a SaaS vendor. Every feature is available to every user. No paid tier, no feature gate, no upsell.

A free hosted version is available at brightbean.xyz/studio. You can also deploy it yourself with a one-click button on Heroku, Render, or Railway, run it on your own VPS via Docker, or run it locally. All platform integrations talk directly to the official first-party APIs using your own developer credentials, so there's no aggregator middleman, no vendor lock-in, and no third party sitting between you and your data.

Features

Multi-workspace & teams	Unlimited orgs → workspaces → members. Granular RBAC with custom roles, invitations, and a separate Client role for external collaborators.
Content composer	Rich editor with per-platform caption/media overrides, version history, reusable templates, content categories & tags, a Kanban idea board.
Calendar & scheduling	Visual calendar with recurring weekly posting slots per account and named queues that auto-assign posts to the next available slot.
Publishing engine	Direct first-party API integrations (no aggregator), automatic retries, per-account rate-limit tracking, and a 90-day publish audit log.
Approval workflows	Configurable stages (none / optional / internal / internal + client), threaded internal & external comments, reminders, and a full audit trail.
Unified social inbox	Comments, mentions, DMs, and reviews from every connected platform in one place, with sentiment analysis, assignments, threaded replies, and historical backfill.
Analytics	Per-post and channel-level performance from every connected platform's native API, with KPI cards, 7/30/90-day trend charts, and a sortable all-posts table for views, engagement, follower growth, reach, and watch time.
Media library	Org- and workspace-scoped libraries with nested folders, auto-generated platform-optimized variants, alt text, and built-in Unsplash stock-photo search in the composer.
Client portal	Passwordless 30-day magic-link access so clients can approve or reject posts without creating an account.
Notifications	In-app, email, and webhook delivery with per-user preferences for every event type.
Security & ops	Encrypted token & credential storage, Google SSO, Sentry support, and a 14-day reversible org-deletion grace period. 2FA (TOTP) is on the roadmap.
White-label friendly	Per-workspace branding (logo, colors) and workspace defaults for hashtags, first comments, and posting templates.

A quick look

Visual calendar - drag-and-drop scheduling with recurring slots and queues.
Post editor - composer with per-platform overrides and previews.	Idea board - Kanban workflow to keep track of all your post ideas.
Connect anything - 10+ first-party integrations, no aggregator.	Performance analytics - per-post and channel-level metrics with KPI cards and trend charts.

Supported Platforms

Platform	Publish	Comments	DMs	Insights
Facebook	✓	✓	✓	✓
Instagram	✓	✓	✓	✓
Instagram (Direct)	✓	✓	✓	✓
LinkedIn (Personal)	✓	✓	—	✓
LinkedIn (Company)	✓	✓	—	✓
TikTok	✓	—	—	✓
YouTube	✓	✓	—	✓
Pinterest	✓	—	—	✓
Threads	✓	✓	—	✓
Bluesky	✓	✓	—	—
Google Business Profile	✓	—	—	✓
Mastodon	✓	✓	—	—
DEV.to	✓	—	—	—

---

Hosted Version

A free hosted version of Brightbean Studio is available at brightbean.xyz/studio. It runs the same codebase as this repository, with no setup or maintenance required.

If you'd rather self-host, choose one of the options below.

One-Click Deploy

Heroku	Render	Railway

After deploying, set these environment variables in your platform's dashboard:

Variable	Required	Description
DJANGO_SETTINGS_MODULE	Auto-set	config.settings.production. Set if deployment config has not placed it.
SECRET_KEY	Auto-generated	Django secret key. Set automatically by the deploy button.
ENCRYPTION_KEY_SALT	Auto-generated	Encryption salt. Set automatically by the deploy button.
DATABASE_URL	Auto-provisioned	PostgreSQL connection string. Set automatically.
ALLOWED_HOSTS	Yes	Your app's domain, e.g. your-app.herokuapp.com
APP_URL	Yes	Full public URL, e.g. https://your-app.herokuapp.com
STORAGE_BACKEND	No	Set to s3 for S3/R2 storage. Default: local. Heroku, Render, and Railway have ephemeral filesystems, so uploaded files are lost on redeploy without S3.
S3_ENDPOINT_URL	If using S3	S3-compatible endpoint URL
S3_ACCESS_KEY_ID	If using S3	S3 access key
S3_SECRET_ACCESS_KEY	If using S3	S3 secret key
S3_BUCKET_NAME	If using S3	S3 bucket name
EMAIL_HOST	No	SMTP server for sending invitations and password resets
EMAIL_PORT	No	SMTP port (default: 587)
EMAIL_HOST_USER	No	SMTP username
EMAIL_HOST_PASSWORD	No	SMTP password
GOOGLE_AUTH_CLIENT_ID	No	For Google OAuth login. Get from Google Cloud Console → Credentials.
GOOGLE_AUTH_CLIENT_SECRET	No	Google OAuth secret
UNSPLASH_ACCESS_KEY	No	Enables Unsplash stock-photo search in the composer. Create a free app at unsplash.com/developers.

For social media API keys, see Platform Credentials. Full variable reference: .env.example.

Quick Start (Docker)

git clone https://github.com/brightbeanxyz/brightbean-studio.git
cd brightbean-studio
cp .env.example .env

Edit .env - change DATABASE_URL to point to the Docker service name:

DATABASE_URL=postgres://postgres:postgres@postgres:5432/brightbean

Then start everything:

docker compose up -d --build
docker compose exec app python manage.py createsuperuser

Database migrations run automatically via the migrate Compose service before the app and worker services start, so there is no separate migrate step.

Tailwind compiles automatically via the tailwind Compose service. First build takes ~60–90 seconds (running npm install in a fresh container); subsequent starts are instant. Watch progress with docker compose logs -f tailwind.

Open http://localhost:8000 - you're running.

Fully Local Development (without Docker)

Run everything natively - no Docker, no PostgreSQL install. Uses SQLite for the database.

Prerequisites

• Python 3.12+
• Node.js 20+

Setup

1. Clone and configure

git clone https://github.com/brightbeanxyz/brightbean-studio.git
cd brightbean-studio
cp .env.example .env

2. Switch to SQLite

Open .env and replace the DATABASE_URL line:

DATABASE_URL=sqlite:///db.sqlite3

That's it - no database server to install or manage.

3. Set up Python

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4. Set up Tailwind CSS

cd theme/static_src
npm install
cd ../..

5. Run database migrations

python manage.py migrate

6. Create your admin account

python manage.py createsuperuser

7. Start the app (3 terminal tabs)

Tab 1 - Tailwind watcher:

cd theme/static_src && npm run start

Tab 2 - Django dev server:

source .venv/bin/activate
python manage.py runserver

Tab 3 - Background worker:

source .venv/bin/activate
python manage.py process_tasks

Open http://localhost:8000 and log in with the superuser you created.

Daily workflow (Docker-free)

source .venv/bin/activate                # activate Python env
python manage.py runserver               # start web server
# (open another tab)
python manage.py process_tasks           # start worker

Note: SQLite is fine for local development and small deployments. For production or heavy concurrent usage, switch to PostgreSQL.

Running Tests

pytest

With coverage:

pytest --cov=apps --cov-report=term-missing

Linting & Type Checking

ruff check .                             # lint
ruff format --check .                    # format check
mypy apps/ config/ --ignore-missing-imports  # type check

Auto-fix lint issues:

ruff check --fix .
ruff format .

Production Deployment

Docker Compose on a VPS (recommended)

# On your server:
git clone https://github.com/brightbeanxyz/brightbean-studio.git
cd brightbean-studio
cp .env.example .env
# Edit .env:
#   SECRET_KEY=<generate a random 50+ char string>
#   DEBUG=false
#   ALLOWED_HOSTS=yourdomain.com
#   APP_URL=https://yourdomain.com
#   DATABASE_URL=postgres://postgres:<strong-password>@postgres:5432/brightbean

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build
docker compose exec app python manage.py createsuperuser

This starts 5 containers: app (Gunicorn), worker, PostgreSQL, Caddy (auto-HTTPS), and a one-shot migrate container that runs database migrations automatically on startup. Edit the Caddyfile with your domain.

To update:

git pull
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

Other Platforms

Platform	Config file	Notes
Heroku	Procfile + app.json	Deploy-button ready. Must use Basic+ dynos (Eco dynos break the worker).
Railway	railway.toml	The one-click template provisions three services: web (Gunicorn, runs migrate on startup), worker (python manage.py process_tasks), and managed PostgreSQL. The web service's startup migrate fires the post_migrate hooks that register the recurring tasks, so scheduling works