Website Logo Search ⌘K

Setup: Installation Instructions

If you’ve read our initial setup explainer and prerequisites, great! You’re now ready to install and set up Newsmast, starting with the plugin gem.

Installing the Plugin #

  1. From your server’s Mastodon root folder, edit the Gemfile and add the gem (with the matching Mastodon version pinned):
gem "newsmast_mastodon", "X.Y.Z.N"

You can run cat lib/mastodon/version.rb to see what the major/minor/patch values are, and then choose the latest gem patch as indicated in our Releases (missing).

  1. Install the gem by running:
bundle install
  1. Next, run database migrations. This will pick up the changes provided by the gem engine automatically:
bundle exec rails db:migrate
  1. Finally, you will need to install the code-level overrides provided by the gem. Run this command: 
bundle exec rails newsmast_mastodon:install

and then rebuild frontend assets:

yarn build:production  # or yarn build:development if you're just testing

Now restart the Mastodon instance (both the web server and the Sidekiq background service), and verify that it boots successfully. If there’s any detected mismatch between the Mastodon version and the gem version match, you’ll see an error logged to the console.

As an additional step, have a look at the Customizing (missing) section to see what environment variables you can set to modify the behavior of the plugin or add integrations with other services.

If you’re interested in setting up the administrative dashboard as well, keep reading for installation instructions.

Installing the Dashboard (Optional) #

To begin with, make sure you have the necessary access credentials and network information for the Mastodon instance’s:

  • REST API
  • PostgreSQL database
  • Redis

It’s up to you if you want to run the dashboard on the same server as the Mastodon instance or a different server. In either case, you’ll need to connect the dashboard to those three services.

Now, decide if you’d prefer to install the dashboard via a Docker container, or manually. We provide instructions for either approach.

Docker Installation #

  1. Clone the repo and copy the .env.sample file to .env, then add in the various access credentials.
git clone https://github.com/TheNewsmastFoundation/newsmast-dashboard.git
cd newsmast-dashboard
cp .env.sample .env
chmod 600 .env
$EDITOR .env

By default, Docker Compose will create and utilize the container network named mastodon_internal_network. You can edit docker-compose.yml file if necessary to change the network for the app service.

💬 Important

Do not commit .env or use any of the placeholder secrets.

  1. Pull and boot the Docker image.
docker compose pull
docker compose up -d
docker compose ps
docker compose logs app

Once you’ve verified the application has booted successfully, you can run the database migrations and seeds for initial application data.

docker compose exec app bundle exec rails db:migrate
docker compose exec app bundle exec rails db:seed
  1. Log into the dashboard with your admin credentials (as specified in .env).

Manual Installation #

  1. Clone the repo and copy the .env.sample file to .env, then add in the various access credentials.
git clone https://github.com/TheNewsmastFoundation/newsmast-dashboard.git
cp .env.sample .env
$EDITOR .env
  1. Install dependencies, setup database, and boot the Rails application server.
bin/setup
bundle exec rails server
  1. Log into the dashboard with your admin credentials (as specified in .env).

Further Setup #

If you need to upgrade in the future, read the guide here (missing).
Skip to content Close