Migration from Rebased/Soapbox to Main Pleroma Repository

By Maciej Lesiak

- 3 minutes read - 637 words

What's in this article

Ahoy, ye scurvy dogs! Abandon ship, or abandon hope!

I have only private git so I need to share this knowledge here. This guide describes how to migrate an existing Rebased/Soapbox Pleroma installation to the main Pleroma repository while preserving your data and users.

Prerequisites

  • Existing Rebased/Soapbox Pleroma installation
  • Root access to your server
  • Backup capabilities
  • Environment: Ubuntu 22.04.5 LTS jammy

1. Backup Current Installation

# Stop Pleroma service
systemctl stop pleroma

# Backup current installation
mv /opt/pleroma /opt/pleroma-old

# Backup PostgreSQL database
pg_dump pleroma > pleroma_backup_$(date +%Y%m%d).sql

2. Clone Main Pleroma Repository

sudo -Hu pleroma bash
# Clone fresh Pleroma
git clone https://git.pleroma.social/pleroma/pleroma.git /opt/pleroma
cd /opt/pleroma
git checkout stable
# check file ownership (for pleroma)
ls -la /opt/pleroma

3. Setup Elixir Version

# Set proper Elixir version for new Pleroma (as pleroma user)
export PATH="/var/lib/pleroma/.asdf/shims:$PATH"
/var/lib/pleroma/.asdf/bin/asdf local elixir 1.14.5-otp-24

# Verify version
elixir --version

4. Install Dependencies

# Install Hex and Rebar (as pleroma user)
mix local.hex --force
mix local.rebar --force

# Get Pleroma dependencies
mix deps.get

5. Copy Essential Configurations

# Create config directory if it doesn't exist
mkdir -p /opt/pleroma/config

# Copy critical configurations from old installation
cp /opt/pleroma-old/config/prod.secret.exs /opt/pleroma/config/prod.secret.exs

# Copy uploads
cp -r /opt/pleroma-old/uploads/* /opt/pleroma/uploads/
# Ensure correct file ownership
chown -R pleroma:pleroma /opt/pleroma/

6. Run Database Migrations

# Run migrations
cd /opt/pleroma
MIX_ENV=prod mix ecto.migrate

7. Install Default Frontend

# Install Pleroma frontend
MIX_ENV=prod mix pleroma.frontend install pleroma-fe --ref stable

# Clean up old frontend files
rm -rf /opt/pleroma/instance/static/packs/*
rm -rf /opt/pleroma/instance/static/frontends/*
rm -f /opt/pleroma/instance/static/index.html
rm -f /opt/pleroma/instance/static/sw.js*
rm -f /opt/pleroma/instance/static/manifest.*

8. Update Configuration

Edit /opt/pleroma/config/prod.secret.exs:

# Add these lines to your existing config
config :pleroma, :frontends,
  primary: %{
    "name" => "pleroma-fe",
    "ref" => "stable"
  }

# Add this to acknowledge database schema changes
config :pleroma, :i_am_aware_this_may_cause_data_loss, true

# Make sure these paths are correct
config :pleroma, :instance, static_dir: "/opt/pleroma/instance/static"
config :pleroma, Pleroma.Uploaders.Local, uploads: "/opt/pleroma/uploads"

9. Set Permissions

# Set correct ownership
chown -R pleroma:pleroma /opt/pleroma
chmod -R 755 /opt/pleroma

10. Start Service

# Start Pleroma
systemctl start pleroma
systemctl restart nginx
# Check status
systemctl status pleroma
# monitor issues - takes 5-10 seconds to get up
journalctl -u pleroma -f

11. (Optional) Migrate Config to Database

If you want to manage settings via admin interface:

# Export configuration to database
MIX_ENV=prod mix pleroma.config migrate_to_db

# Backup your current config
cp config/prod.secret.exs config/prod.secret.exs.backup

# Generate new database-based config
MIX_ENV=prod mix pleroma.config create_db_config

Verification Steps

  1. Check if service is running:
systemctl status pleroma
  1. Monitor logs for errors:
journalctl -u pleroma -f
  1. Verify the website loads with Pleroma frontend
  2. Test basic functionality:
    • Login to your account
    • Post a message
    • Check media uploads
    • Verify federation

Troubleshooting

Common Issues

Service Won’t Start

Check logs for unapplied migrations (sudo):

journalctl -u pleroma -f

If you see migration errors, run (as pleroma):

MIX_ENV=prod mix ecto.migrate

Still Shows Soapbox Frontend

Clear your browser cache or try in incognito mode. If persists:

# Reinstall Pleroma frontend (pleroma user)
MIX_ENV=prod mix pleroma.frontend install pleroma-fe --ref stable

# Force frontend settings in database
MIX_ENV=prod mix pleroma.config set "pleroma" "frontends" '{"primary":{"name":"pleroma-fe","ref":"stable"}}'

Database Errors

If you see database-related errors, verify your database configuration and permissions:

# Check database ownership (as root)
sudo -u postgres psql -c "\l" | grep pleroma

Rollback Plan

If something goes wrong (as sudo):

# Stop new installation
systemctl stop pleroma

# Restore old installation
rm -rf /opt/pleroma
mv /opt/pleroma-old /opt/pleroma

# Restore database if needed
psql pleroma < pleroma_backup_YYYYMMDD.sql

# Start service
systemctl start pleroma

Post-Migration Tasks

  1. Monitor logs for any errors
  2. Test all core functionality
  3. Update your backup scripts if needed
  4. Consider hardening your installation or migration to AKKOMA with downgrading DB schema to early 2022 Pleroma and than migrate to Akkoma. More info on web :)

Final Notes

  • Keep your backups until you’re confident everything is working :)
  • Test federation with other instances :D

Cheers!