homelab-optimized/deployments/mastodon/USER_MANAGEMENT.md

User Management Guide

Creating New Users

Method 1: Command Line (Recommended for Admins)

# Create a new user (confirmed = skip email verification)
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts create USERNAME --email=user@example.com --confirmed'

# Approve the user (if approval mode is enabled)
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts approve USERNAME'

# Optional: Give them a role
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --role Moderator'
# Roles: Owner, Admin, Moderator (or leave blank for regular user)

Method 2: Web Registration

1. Go to https://your-domain.com
2. Click "Create account"
3. Fill in username, email, password
4. Admin approves in Settings → Administration → Pending accounts (if approval required)

Method 3: Invite Links

1. Login as admin
2. Go to Settings → Invites
3. Click "Generate invite link"
4. Share the link with your partner/friends

Example: Adding Your Partner

# Create account for partner
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts create partner --email=partner@example.com --confirmed'

# Save the generated password! It will be displayed like:
# New password: "REDACTED_PASSWORD"

# Approve the account
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts approve partner'

# Optional: Make them an admin too
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify partner --role Admin'

User Limits

There is NO hard limit on users.

Your only constraints are server resources:

• RAM: Each active user session uses some memory
• Storage: Media uploads (avatars, images, videos) take disk space
• CPU: More users = more background jobs

For a small personal instance (2-10 users), a VM with 4GB RAM and 20GB storage is more than enough.

Managing Existing Users

List all users

sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts list'

Reset a user's password

sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --reset-password'

Disable/Enable a user

# Disable
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --disable'

# Enable
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --enable'

Delete a user

sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts delete USERNAME'

Change user role

# Make admin
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --role Admin'

# Make moderator
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --role Moderator'

# Remove all roles (regular user)
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --role ""'

Registration Settings

Control how new users can join via the admin panel:

1. Login as admin
2. Go to Settings → Administration → Server Settings → Registrations
3. Choose:
   • Open: Anyone can sign up
   • Approval required: Admin must approve new accounts
   • Closed: No new registrations (invite-only)

User Roles

Role	Permissions
Owner	Full access, can't be demoted
Admin	Full admin panel access, manage users, server settings
Moderator	Handle reports, suspend users, manage content
User	Regular user, no admin access

Quick Reference

# Create user
bin/tootctl accounts create USERNAME --email=EMAIL --confirmed

# Approve user  
bin/tootctl accounts approve USERNAME

# Make admin
bin/tootctl accounts modify USERNAME --role Admin

# Reset password
bin/tootctl accounts modify USERNAME --reset-password

# Delete user
bin/tootctl accounts delete USERNAME

All commands require the prefix:

sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production ...'