Skip to content

Initial migration

Darius Kazemi edited this page Jul 7, 2023 · 24 revisions

Hello! This is a guide to help you migrate from Mastodon to Hometown. This guide shows you how to migrate from Mastodon v4.0.6 to Hometown v4.0.6+hometown-1.1.1. Right now we are up to date with Mastodon 4.0.6, so make sure you are running Mastodon 4.0.6 before trying this. There are Mastodon installation instructions here. And please test in a local development environment or a test server first if at all possible.

THIS IS NOT FOR BEGINNERS. You should be comfortable maintaining Mastodon and updating from one version of Mastodon to another. If you are an instance admin who has upgraded your instance from, say, 2.9.5 up to 3.5.5 over time, you should be familiar with every step of this process.

Assuming you are running Mastodon 4.0.6 (aka you have the v4.0.6 tag checked out in git and a git log shows your most recent commit is 60b70755bed6a9d29644ba1b879c9bd75af6f3f4), the following should work.

First, triple-check you're on the v4.0.6 tag:

git describe --tags

The output should be:


If you get an error instead, Mastodon probably isn't installed as a Git repo. This can happen if you install Mastodon via downloading a ZIP of the source, or you use something that does that, like Yunohost. Hometown only supports a git-based Mastodon installation.

Next, add the Hometown Github repo as a remote called hometown and make a branch off of v4.0.4 for your new modified installation. Then, switch to that new branch, which right now is identical to 4.0.4.

git remote add hometown
git branch hometown-v1.1.1
git checkout hometown-v1.1.1

The next thing we do is fetch and merge the v4.0.6+hometown-1.1.1 tag from the Hometown Github repo and merge it into our current branch.

git fetch hometown
git merge v4.0.6+hometown-1.1.1

Now we need to run bundle install again, and then a database migration (replace "production" with your appropriate environment variable):

bundle install
RAILS_ENV=production bundle exec rails db:migrate

This adds some new fields to the statuses table in the database, like one called activity_pub_type, which keeps track of whether a given status in the database is an Article or a standard Note.

Next precompile your static assets:

RAILS_ENV=production bundle exec rails assets:precompile

And restart your Mastodon services. That should be everything! You can tell if it's working (aside from lack of error messages) if you see a message in the "getting started" footer linking to the Hometown source code: