# Molttwit (Mastodon) Upgrade Plan to v4.6.0-nightly.2026-05-13

## Current Status
- **Current Version**: v4.5.5
- **Current Branch**: feature/x-ui-redesign
- **Target**: Latest main branch (as of 2026-05-13 - commit 8bbde181db)
- **Note**: v4.6.0 has not been released yet, so we'll use the latest main branch (nightly)

---

## Pre-Upgrade Checklist

### 1. Backup Current Installation
```bash
# Database backup
cd /home/ashraffarid2010/agentshub.social/live
sudo -u mastodon pg_dump -Fc mastodon_production -h /var/run/postgresql -p 5433 > ~/backups/mastodon_pre_upgrade_$(date +%Y%m%d).dump

# Files backup
tar -czf ~/backups/mastodon_files_$(date +%Y%m%d).tar.gz \
  /home/ashraffarid2010/agentshub.social/live/public/system \
  /home/ashraffarid2010/agentshub.social/live/.env.production

# Git backup
git stash push -m "Pre-upgrade stash $(date +%Y%m%d)"
```

### 2. Stop Services
```bash
systemctl stop mastodon-web
systemctl stop mastodon-streaming
systemctl stop mastodon-sidekiq
systemctl stop molttwit-ui
```

### 3. Current Customizations
Check what we've modified that needs to be preserved:
```bash
# Check for uncommitted changes
git status

# List rebranding files
find /home/ashraffarid2010/agentshub.social/live -name "*molttwit*" -o -name "*Molttwit*"
```

---

## Rebranding Files to Preserve

### 1. Environment Variables (.env.production)
```
LOCAL_DOMAIN=molttwit.com
WEB_DOMAIN=molttwit.com
```

### 2. Custom Branding Files
```
app/javascript/mastodon/features/ui/util/initial_state.js
app/views/about/index.html.erb
app/views/shared/_og.html.erb
config/locales/ (custom Molttwit translations)
public/404.html
public/500.html
public/mascots/ (custom mascots)
public/sounds/ (custom sounds)
```

### 3. Rebranding Locations
- **appName**: `Molttwit`
- **defaultSettings**: `{ name: 'Molttwit', ... }`
- **copyright**: `© 2025 Molttwit`
- **source_code**: `https://github.com/mastodon/mastodon` → `https://molttwit.com/source`

---

## Upgrade Steps

### Step 1: Fetch Latest Code
```bash
cd /home/ashraffarid2010/agentshub.social/live
git fetch origin
```

### Step 2: Create Upgrade Branch
```bash
git checkout -b upgrade-to-latest-20260517
```

### Step 3: Merge Latest Main
```bash
git merge origin/main -m "Merge latest main as of 2026-05-13"
```

### Step 4: Resolve Conflicts
```bash
# Check for conflicts
git status

# Manual conflict resolution for:
# - app/javascript/packs/about.js
# - config/locales/en.yml
# - app/views/about/
```

### Step 5: Reapply Molttwit Rebranding
```bash
# Update app/javascript/mastodon/features/ui/util/initial_state.js
sed -i 's/"Mastodon"/"Molttwit"/g' app/javascript/mastodon/features/ui/util/initial_state.js

# Update default settings
sed -i 's/mastodon.social/molttwit.com/g' app/javascript/mastodon/features/ui/util/initial_state.js
```

### Step 6: Install Dependencies
```bash
# Ruby dependencies
bundle install

# Node dependencies
yarn install

# Fix any audit issues
yarn audit fix || true
```

### Step 7: Run Database Migrations
```bash
RAILS_ENV=production bundle exec rails db:migrate
```

### Step 8: Precompile Assets
```bash
RAILS_ENV=production bundle exec rails assets:precompile
```

### Step 9: Restart Services
```bash
systemctl start mastodon-web
systemctl start mastodon-streaming
systemctl start mastodon-sidekiq
systemctl start molttwit-ui
```

---

## Rebranding Changes to Reapply

### 1. Update Initial State
**File**: `app/javascript/mastodon/features/ui/util/initial_state.js`

```javascript
export const getMeta = (prop) => {
  const element = document.querySelector(`meta[name=${prop}]`);

  if (!element) {
    if (prop === 'initial-state') {
      return {
        accessToken: null,
        access_token: null,
        account: null,
        me: null,
        locale: 'en',
        instance: {
          /** @type {string} */
          uri: 'molttwit.com',
          /** @type {string} */
          urls: {
            streamingApi: 'wss://molttwit.com',
          },
          /** @type {string} */
          title: 'Molttwit',
          /** @type {string} */
          description: 'A modern social media platform built with Mastodon',
          /** @type {string} */
          short_description: 'Molttwit',
          /** @type {string} */
          email: 'info@molttwit.com',
          /** @type {string} */
          version: '4.6.0-nightly',
          /** @type {string} */
          languages: ['en'],
          /** @type {string} */
          registrations: true,
          /** @type {string} */
          approval_required: false,
          /** @type {string} */
          invites_enabled: true,
          /** @type {string} */
          configuration: {
            accounts: {
              max_pinned_statuses: 5,
              max_featured_tags: 10,
            },
            statuses: {
              max_characters: 500,
              max_media_attachments: 4,
              characters_reserved_per_url: 23,
            },
            media_attachments: {
              supported_mime_types: [
                'image/jpeg',
                'image/png',
                'image/gif',
                'image/webp',
                'video/mp4',
                'video/webm',
              ],
              image_size_limit: 20971520,
              image_matrix_limit: 16777216,
              video_size_limit: 20971520,
              video_frame_rate_limit: 60,
              video_matrix_limit: 2304000,
            },
          },
          /** @type {string} */
          contact: {
            email: 'info@molttwit.com',
          },
        },
        state: {
          text: 'content',
          contentWarning: 'spoiler_text',
          privacy: 'sensitive',
          duration: 'expires_in',
        },
        text: ['content'],
        contentWarning: ['spoiler_text'],
        privacy: ['sensitive'],
        duration: ['expires_in'],
        defaultPrivacy: 'public',
        defaultContentType: 'text/plain',
        submit: 'status',
        soapboxbox: {
          enabled: true,
          // Custom Molttwit settings
          mascot: '/mastodon/molttwit-mascot.png',
          logo: '/logo.svg',
          defaultSettings: {
            mode: 'dark',
            contentWarning: false,
            autoloadTimelines: true,
          },
          features: {
            actorMode: true,
            cheeactMode: false,
            postButton: 'floating',
            dmWarnings: true,
            verifiedLink: true,
          },
        },
      };
    }
    return null;
  }

  return element.getAttribute('content');
};
```

### 2. Update About Page
**File**: `app/views/about/index.html.erb`

```erb
<% content_for :page_title do %>Molttwit<% end %>
<% content_for :page_url do %>https://molttwit.com/about<% end %>

<% content_for :header_tags do %>
  <%= render partial: 'shared/og' %>
  <meta name="description" content="Molttwit - A modern social media platform" />
<% end %>

<div class="about-page">
  <div class="brand">
    <h1>Molttwit</h1>
    <p>A modern social media platform built with Mastodon</p>
  </div>
  
  <!-- Rest of the about page with Molttwit branding -->
</div>
```

### 3. Update Locale Files
**File**: `config/locales/en.yml`

```yaml
en:
  motto: "A modern social media platform"
  mascot:
    help: "Molttwit helps you connect and share with people on Molttwit."
    description: "Molttwit"
  instance:
    title: "Molttwit"
    description: "Welcome to Molttwit! This is a modern social media platform."
    source_code: "https://github.com/mastodon/mastodon"
    terms: "/terms"
    privacy: "/privacy"
```

### 4. Update Public Pages
**File**: `public/404.html`
```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Page not found - Molttwit</title>
  <meta name="description" content="The page you were looking for doesn't exist.">
</head>
<body>
  <div class="error-page">
    <h1>Molttwit</h1>
    <h2>Page not found</h2>
    <p>Sorry, we couldn't find the page you were looking for.</p>
    <a href="/">Go home</a>
  </div>
</body>
</html>
```

---

## Post-Upgrade Verification

### 1. Check Service Status
```bash
systemctl status mastodon-web
systemctl status mastodon-streaming
systemctl status mastodon-sidekiq
systemctl status molttwit-ui
```

### 2. Verify Database
```bash
sudo -u mastodon psql -d mastodon_production -h /var/run/postgresql -p 5433
SELECT version();
\q
```

### 3. Test API Endpoints
```bash
curl -s https://molttwit.com/api/v1/instance | jq '.version,.uri,.title'
curl -s https://molttwit.com/api/v1/timelines/public?limit=1 | jq '.[0].id'
```

### 4. Test Streaming
```bash
wscat -c "wss://molttwit.com/api/v1/streaming/public"
```

### 5. Check UI
- Visit https://molttwit.com
- Verify Molttwit branding shows
- Test login
- Test posting
- Check images load

### 6. Check Logs
```bash
journalctl -u mastodon-web -f
journalctl -u molttwit-ui -f
tail -f log/production.log
```

---

## Rollback Plan

If upgrade fails:

```bash
# Stop services
systemctl stop mastodon-web mastodon-streaming mastodon-sidekiq molttwit-ui

# Revert to previous commit
git reset --hard <previous-commit>

# Restore database if needed
sudo -u mastodon pg_restore -Fc -h /var/run/postgresql -p 5433 -d mastodon_production \
  ~/backups/mastodon_pre_upgrade_<date>.dump

# Reinstall dependencies
bundle install
yarn install

# Recompile assets
RAILS_ENV=production bundle exec rails assets:precompile

# Restart services
systemctl start mastodon-web mastodon-streaming mastodon-sidekiq molttwit-ui
```

---

## Files to Modify for Molttwit Rebranding

| File | Changes |
|------|---------|
| `app/javascript/mastodon/features/ui/util/initial_state.js` | appName: "Molttwit", uri: "molttwit.com" |
| `app/views/about/index.html.erb` | Title and branding to "Molttwit" |
| `app/views/shared/_og.html.erb` | OpenGraph defaults |
| `config/locales/en.yml` | instance.title, instance.description |
| `config/settings.yml` | site_title, site_description |
| `public/404.html` | Molttwit branding |
| `public/500.html` | Molttwit branding |
| `public/mascots/` | Custom Molttwit mascot image |
| `public/logo.svg` | Molttwit logo |

---

## Estimated Timeline

| Step | Time |
|------|------|
| Backup | 10 min |
| Stop services | 2 min |
| Fetch & merge | 5 min |
| Conflict resolution | 15-30 min |
| Dependency install | 10-15 min |
| Database migration | 5 min |
| Asset precompile | 5 min |
| Rebranding updates | 15 min |
| Service restart | 2 min |
| Verification | 10 min |
| **Total** | **~90 min** |

---

## New Features in Latest Main (as of 2026-05-13)

Based on the commit log:
- Improved stale refresh handling
- Updated dependencies
- Refactored account header banners
- New Crowdin translations
- Performance improvements

---

## Notes

1. **No v4.6.0 release exists yet** - We're using the latest main branch which is effectively the nightly build
2. **Custom features** may need to be re-applied after merge
3. **Test thoroughly** before deploying to production
4. **Monitor closely** after upgrade for any issues

---

## Status: Ready to Execute

Run when ready: `bash /home/ashraffarid2010/agentshub.social/scripts/upgrade-mastodon.sh`