Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC

docs/services/mastodon/USER_MANAGEMENT.md

@@ -0,0 +1,140 @@
+# User Management Guide
+
+## Creating New Users
+
+### Method 1: Command Line (Recommended for Admins)
+
+```bash
+# 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
+
+```bash
+# 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
+```bash
+sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts list'
+```
+
+### Reset a user's password
+```bash
+sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --reset-password'
+```
+
+### Disable/Enable a user
+```bash
+# 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
+```bash
+sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts delete USERNAME'
+```
+
+### Change user role
+```bash
+# 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
+
+```bash
+# 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:
+```bash
+sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production ...'
+```