Migration from Rebased/Soapbox to Main Pleroma Repository

Maciej Lesiak

November 22, 2024 - 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

Check if service is running:

systemctl status pleroma

Monitor logs for errors:

journalctl -u pleroma -f

Verify the website loads with Pleroma frontend
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

Monitor logs for any errors
Test all core functionality
Update your backup scripts if needed
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!

If you find this research valuable, consider supporting through Ko-fi. Your contribution helps maintain this project as an ad-free, independent resource.

COFFEE NOT BULLETS

Direct support means more research, better content, and no ads.