Mastodon is an open-source, decentralized social networking platform. By installing it on a Raspberry Pi, you can host your own personal Mastodon instance with relatively low energy use. This guide will walk through installing Mastodon on Raspberry Pi OS and optimizing the install for the best user experience.
Prerequisites
Before starting, you’ll need:
- A Raspberry Pi 2, 3, or 4
- An 8GB+ microSD card loaded with Raspberry Pi OS
- Access to the terminal on your Pi (through SSH or connected monitor)
- A domain name and ability to edit your DNS records
- Ports 80 and 443 forwarded if hosting externally
Install Required Software
Start by updating your Pi’s package list and installing required software:
sudo apt update
sudo apt install vim git curl postgresql nginx
The above includes Nginx as a reverse proxy, PostgreSQL for the database, and other utilities needed for the install.
Configure PostgreSQL
Next, switch over to the postgres user and configure a database for Mastodon with the proper permissions:
sudo su – postgres
psql -c “CREATE USER mastodon CREATEDB;”
psql -c “CREATE DATABASE mastodon OWNER mastodon;”
psql -c “ALTER USER mastodon WITH PASSWORD ‘DBPasswordHere’;”
Be sure to replace “DBPasswordHere” with a strong postgres password. This creates the user, database, and permissions Mastodon will utilize.
Install Ruby and Node.js
Mastodon is a Ruby on Rails application, so Ruby and Node.js are requirements as well:
sudo apt install ruby-bundler ruby-dev libxml2-dev libxslt1-dev nodejs gcc make g++
The dev packages, gcc, git, and other utilities support compiling Ruby gems and Node modules.
Configure Systemd Services
Let’s create a mastodon user for running the Mastodon services:
sudo user add mastodon –system –user-group –home /opt/mastodon
Next, configure the Mastodon systemd services:
sudo vim /etc/systemd/system/mastodon-web.service
sudo vim /etc/systemd/system/mastodon-sidekiq.service
sudo vim /etc/systemd/system/mastodon-streaming.service
Paste the following into each, modifying environment variables as needed:
[Unit]
Description=mastodon-web
After=network. Target
[Service]
Type=simple
User=mastodon
WorkingDirectory=/opt/mastodon
Environment=”RAILS_ENV=production”
Environment=”PORT=3000″
ExecStart=/home/mastodon/.rbenv/shims/bundle exec puma -C config/puma.rb
TimeoutSec=15
Restart=always
[Install]
WantedBy=multi-user.target
This allows managing the Mastodon services with:
sudo systemctl {start|stop|restart} mastodon-{web|sidekiq|streaming}
Install Mastodon
Now it’s finally time to install Mastodon itself:
sudo -u mastodon git clone https://github.com/mastodon/mastodon.git /opt/mastodon
This clones the Mastodon repository locally as the mastodon user. Next configure gems and Node dependencies:
sudo -u mastodon cd /opt/mastodon
sudo -u mastodon bundle config set deployment ‘true’
sudo -u mastodon bundle config set without ‘development test’
sudo -u mastodon bundle install -j$(getconf _NPROCESSORS_ONLN)
sudo -u mastodon yarn install –pure-lockfile
That configures bundler for production then installs Ruby gems and Node modules.
Configure Environment Variables
Configure the Mastodon environment variables:
sudo -u mastodon cp .env.production. Sample .env.production
Then edit .env.production and configure the options like SMTP details, AWS keys, and other settings. Be sure to generate and set random strings for SECRET_KEY_BASE and OTP_SECRET.
Once done editing .env.production, precompile assets:
sudo -u mastodon RAILS_ENV=production bundle exec rails assets:precompile
Finish Installation
The final Mastodon install steps involve database migrations and indexing:
cd /opt/mastodon
sudo -u mastodon RAILS_ENV=production bundle exec rails db:setup
sudo -u mastodon RAILS_ENV=production bundle exec rails mastodon:webpush:generate_vapid_key
With assets precompiled, database migrated, and VAPID key set – the install is complete!
Start the Mastodon systemd services:
sudo systemctl start mastodon-*.service
Then finish Web setup through the browser-based wizard at yourdomain.com.
Optimization and Tweaks
Here are some optional tweaks for improving Mastodon resource usage on the Pi:
Enable memory caching in Redis
Edit /etc/redis/redis.conf:
maxmemory 512mb
maxmemory-policy allkeys-lru
Configure Nginx server blocks
Edit /etc/nginx/sites-available/default:
proxy_busy_buffers_size 1024k;
fastcgi_buffers 1024 1024k;
fastcgi_buffer_size 1024k;
Enable HTTP/2 support
In nginx.conf uncomment:
listen 443 ssl http2;
include snippets/ssl-params.conf;
Reduce PostgreSQL reserved memory
In /etc/postgresql/11/main/postgresql.conf:
shared_buffers = 128MB
Enable PostgreSQL autovacuuming
Edit postgresql.conf:
autovacuum = on
Add mastodon user to audio group
sudo usermod -a -G audio mastodon
This allows processing audio uploads and transcoding media files.
Conclusion
With those tweaks, your home Mastodon instance should run smoothly on a Raspberry Pi! Being decentralized and open source, you now have control over your social feed and data. Have fun connecting with others across the “fediverse”.
Frequently Asked Questions
- What are the real-world energy costs for a Mastodon Pi?
For a Raspberry Pi 4B with average usage, expect around 5-7 kWh per month in electricity costs. This is <$1 per month in most regions. - What options are there for enabling email notifications?
You can configure SMTP and set up cron to enable email notifications. Or use a cloud mailing service like SendGrid. - Is there an admin interface for managing Mastodon?
Yes, Mastodon includes a built-in admin dashboard for site management. Access in the footer for admins. - Can hashtags and content warnings be disabled?
Yes! Hashtags, content warnings, and other post features can be disabled server-wide via Admin -> Settings. - What’s the maximum upload file size allowed?
Mastodon allows up to 4MB for image uploads and 40MB for video uploads by default. Adjustable in .env.production. - Can Mastodon utilize caching mechanisms?
Yes, Mastodon can use Redis, Memcached, or other backends for caching. Dramatically improves performance. - What Ruby version does Mastodon require?
Currently, Mastodon only works with Ruby version 3.0+. Older versions are not supported. - Is using Docker recommended over native installs?
Docker streamlines deployment, but more resources are needed. Native better optimizes limited hardware. Evaluate both! - Which Raspberry Pi models are supported?
Aim for a Pi 3 or Pi 4. The quad-core CPU helps. Some have Mastodon working on Pi 2, but performance may suffer after instance growth. - Can you federate with users on other platforms?
Yes! Mastodon supports full federation across the entire social “fediverse”, not just Mastodon instances. This includes PeerTube, PixelFed, Friendica, and more! - How do you backup a Mastodon instance?
Backup via the built-in backup feature under the Admin dashboard. Or backup the Postgres database, Redis database, assets folder, and any config files manually. Apply these backups for quick restoration anytime. - Is SVG file upload supported?
No. For security and compatibility reasons, Mastodon only allows PNG, GIF, JPG/JPEG, and WEBP image formats. Convert SVGs to PNGs before uploading. - Can custom apps and bots be used?
Absolutely! There is an entire ecosystem of Mastodon apps and bot tools available from the community. Autopost RSS feeds, make Twitter cross-posts, etc. - How many concurrent users can Mastodon handle?
Performance depends largely on instance configuration and hardware capabilities. Small single-board computers can comfortably serve ~100 concurrent users. Optimal setups can scale to the thousands. - Can Mastodon utilize a CDN for assets?
Yes! Using a content delivery network for hosting assets improves performance and minimizes server load. Set the CDN URL in Admin settings. - What’s the difference between sidekiq and streaming?
The sidekiq process handles asynchronous and background tasks like email delivery, news feed updating, and media processing. Streaming handles real-time updates. Both are critical! - How do you tune PostgreSQL for optimizing Mastodon?
Increase shared_buffers for more cache. Tune autovacuuming. Set effective_cache_size based on memory limits. Reduce wal_buffers and checkpoints. Many other optimizations possible!