====== Preparation ======

Read [[https://github.com/mastodon/mastodon/releases|release notes]] (be sure to click the release version heading to see the full notes).

Check out the (brief) [[https://docs.joinmastodon.org/admin/upgrading/|generic release notes on joinmastodon.org]]

Make sure you have a copy of https://gitlab.com/sunbeam.city/mastodon/ cloned locally.

====== Build a new version ======

**New_instructions_final_FINAL_Nov2025.docx**

//Theme still broken 😭//

  export NEW_VERSION=4.5  # change to actual new version, beware wacky branch naming scheme??
  git fetch upstream --tags
  git checkout sunbeam-changes
  git rebase stable-$NEW_VERSION
  # fix some probably annoying merge conflicts
  git push -f

<del>**As of October 2024, these instructions seem to lead to a festival of annoying merge conflicts. See below for alternative.**</del>

  export NEW_VERSION=4.2.0  # change to actual new version
  git checkout trunk
  git fetch upstream --tags
  git checkout -b merged-$NEW_VERSION
  git merge v$NEW_VERSION
  git checkout trunk
  git merge merged-$NEW_VERSION
  git push

<del>Instead (not yet tested 🤡):</del>

  export NEW_VERSION=4.2.0  # change to actual new version
  git fetch upstream --tags
  git checkout sunbeam-changes-new
  git pull
  git rebase v$NEW_VERSION
  git push -f
  git checkout trunk
  git reset --hard v$NEW_VERSION
  git merge sunbeam-changes-new
  git push -f

Then check [[https://gitlab.com/sunbeam.city/mastodon/-/jobs|the "Jobs" page on Gitlab]], and you should see the Docker image build happily running 🏃 It takes about 8 minutes.

====== Deploy the new version ======

SSH to the server (arkology.sunbeam.city).

Then run:

  cd /var/services/mastodon
  sudo -u services git pull
  sudo -s
  export COMPOSE_FILE="compose.yml:compose.sunbeam.yml"
  docker-compose pull && \
    docker-compose down && \
    docker-compose up -d
  docker-compose run --rm -e SKIP_POST_DEPLOYMENT_MIGRATIONS=true web bundle exec rails db:migrate