Patchwork is a framework to add a suite of plug-ins to a Mastodon server, creating layers between the underlying plumbing of Mastodon and the frontend app used by a user to access it (usually also Mastodon).

Before running Patchwork, please ensure you have set up a Mastodon server and it is running properly.

You can find the instructions to set up a Mastodon server here.

Patchwork begins with the Dashboard.

Once your Mastodon server is up and running, please begin with this repository to set up the Patchwork Dashboard.

This is the core of Patchwork’s frame, introducing new features itself to make your server more powerful, and allowing you to install additional Patchwork plug-ins with ease.

Dashboard installation guide

Please follow the simple steps below to install Patchwork Dashboard:

1. Clone this repository (Patchwork Dashboard) in your server:

git clone

[email protected]:patchwork-hub/patchwork_dashboard.git

2. Create .env file by copying the .env.sample file:

$ cp .env.sample .env

3. Modify following environment variables:

RAILS_ENV=production

4. Connect with your mastodon server's redis

REDIS_HOST=localhost

REDIS_PORT=6379

5. PostgreSQL - Connect with your mastodon instance's database

DB_HOST=your_db_host

DB_NAME=your_mastodon_instance_db

DB_USER=your_db_username

DB_PASS=your_db_password

DB_PORT=5432

4. Generate Mastodon application credentials from your existing Mastodon instance under the "Development" settings, with the following scopes: read, profile, write, follow, and push:

MASTODON_APPLICATION_TOKEN=your_mastodon_application_token

MASTODON_CLIENT_ID=yur_mastodon_client_id

MASTODON_CLIENT_SECRET=your_mastodon_client_secret

MASTODON_INSTANCE_URL=https://example.com

5. Run the docker commands below to build the docker image and run the containers:

$ docker-compose build

$ docker-compose up -d

6. Get inside the docker container to feed necessary data to database:

$ docker exec -it patchwork-dashboard bash

7. Once your are inside the docker container, run below command to feed the data:

$ RAILS_ENV=production bundle exec rake db:seed

8. The container is open to port 3001 and you can access the application with ServerIP:3001.

9. To create a master admin account with access to the dashboard, run the following code in the Rails console:

username = 'MasterAdmin'
email = '[email protected]'
password = 'password'

# Create or update admin account  
admin = Account.where(username: username).first_or_initialize(username: username)  
admin.save(validate: false)  

# Create or update admin user with MasterAdmin role  
user = User.where(email: email).first_or_initialize(  
  email: email,  
  password: password,  
  password_confirmation: password,  
  confirmed_at: Time.now.utc,  
  role: UserRole.find_by(name: 'MasterAdmin'),  
  account: admin,  
  agreement: true,  
  approved: true  
)  
user.save!  

Once set up, you can log in to the dashboard using the newly created master admin account.

Install gems

Next, expand your server's capabilities by installing plug-ins.

Choose from this list:

• Content filters
• Advanced post features

Content filters

Filter timelines with defined hashtags & keywords, and manage your server's connection to Threads & Bluesky.

1. Add this line to your Mastodon application's Gemfile:

gem "content_filters", git: "https://github.com/patchwork-hub/content_filters"

2. Execute to install the gem:

$ bundle install

3. After installing the gem, restart your application to load it in your application.

Advanced post features

Give users on your server advanced posting options, including custom character limits and text formatting.

1. Add this line to your Mastodon application's Gemfile:

gem "posts", git: "https://github.com/patchwork-hub/posts"

2. Install The gem

bundle install

3. After installing the gem, restart your application to load it in your application.