Phase 8: Multiuser documentation (user, admin, API guides) with single-user mode support

[Copilot]

Summary

Implements Phase 8 of the multiuser implementation plan: comprehensive documentation for end users, administrators, and API consumers. Updated to reflect recent implementation changes including single-user mode support and CLI-based user management.

Documentation Created

User Guide (docs/multiuser/user_guide.md) - 428 lines

• Single-user vs multi-user mode explanation
• Login and account management (multi-user mode)
• Role capabilities (regular user vs admin) with permission matrices
• Personal boards, workflows, and queue management
• Shared board collaboration
• Read-only model viewing for non-admins
• Security best practices and troubleshooting

Administrator Guide (docs/multiuser/admin_guide.md) - 840 lines

• Initial setup and first admin account creation
• Configuration with multiuser option (true/false/absent)
• Single-user and multi-user mode behavior
• Mode switching and legacy "system" user ownership
• CLI-based user management (useradd.py, userdel.py, usermod.py, userlist.py)
• Shared board permission management
• Security hardening (JWT secret keys, HTTPS, session policies)
• Backup/recovery scripts (bash, cron examples)
• System monitoring and configuration reference

API Guide (docs/multiuser/api_guide.md) - 1,142 lines

• Single-user vs multi-user mode detection
• JWT authentication flow and token lifecycle (multi-user mode)
• 55+ production-ready code examples (Python, TypeScript, cURL)
• Adaptive API client examples for both modes
• Authentication, user management, and board sharing endpoints
• Error handling patterns and token refresh strategies
• Migration path from single-user API usage
• Security considerations for API consumers

Key Updates (Based on Recent Implementation Changes)

Configuration:

• multiuser: true - Multi-user mode (authentication required)
• multiuser: false or absent - Single-user mode (no authentication)

Single-User Mode:

• No login required - direct access to all InvokeAI functionality
• All boards and images visible in unified view
• Backwards compatible with legacy installations

Mode Switching:

• Switching to single-user: All user boards/images combined into unified view
• Switching to multi-user: Legacy content owned by internal "system" user
• Only administrators can access "system"-owned legacy assets
• Future release will include migration utility for legacy assets

User Management:

• CLI scripts: useradd.py, userdel.py, usermod.py, userlist.py
• Web-based user management UI coming in future release
• Comprehensive usage examples provided for all CLI tools

Example adaptive Python client:

class AdaptiveInvokeAIClient:
    def __init__(self, base_url="http://localhost:9090"):
        self.base_url = base_url
        self.token = None
        self.multiuser_mode = self._check_multiuser_mode()
    
    def _check_multiuser_mode(self):
        """Detect if multi-user mode is enabled."""
        response = requests.get(f"{self.base_url}/api/v1/boards/")
        return response.status_code == 401
    
    def login(self, email, password):
        """Login (only needed in multi-user mode)."""
        if not self.multiuser_mode:
            return
        # ... authentication logic

Documentation Site Integration

• Added "Multi-User Mode" navigation section to mkdocs.yml
• Cross-referenced between all guides and existing docs
• Linked to community resources (Discord, GitHub)

Coverage

All Phase 8 requirements complete with updates for latest implementation:

• User documentation: single-user mode, multi-user mode, mode switching, CLI tools
• Admin documentation: configuration, CLI scripts, legacy asset management
• API documentation: mode detection, adaptive clients, compatibility

Total: 2,997 lines, ~8,500 words, 55+ code examples, 20+ troubleshooting scenarios

Related Issues / Discussions

N/A - Implements documented Phase 8 of multiuser implementation plan

QA Instructions

Documentation validation:

# Verify files created/updated
ls -lh docs/multiuser/{user_guide,admin_guide,api_guide}.md

# Check mkdocs integration
grep -A 5 "Multi-User Mode:" mkdocs.yml

# Verify updates for single-user mode and CLI scripts
grep -n "multiuser" docs/multiuser/*.md
grep -n "single-user" docs/multiuser/*.md
grep -n "useradd\|usermod\|userdel\|userlist" docs/multiuser/*.md

# Line counts
wc -l docs/multiuser/{user_guide,admin_guide,api_guide,phase8_summary}.md

Build documentation site to verify navigation:

mkdocs serve
# Navigate to http://localhost:8080
# Verify "Multi-User Mode" section appears with all three guides

Merge Plan

No special merge considerations. Documentation updates with minimal config change (mkdocs.yml navigation section).

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Tests added / updated (if applicable) - N/A for documentation
• ❗Changes to a redux slice have a corresponding migration - N/A
• Documentation added / updated (if applicable) - Core deliverable
• Updated What's New copy (if doing a release after this PR)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[enhancement]: Implement Phase 8 of the multiuser implementatoin plan</issue_title>
<issue_description>### Is there an existing issue for this?

• I have searched the existing issues

Contact Details

No response

What should this feature add?

Begin the process of writing the user, API and administrator's guides to the new multiuser feature, as documented in docs/multiuser/.

Alternatives

No response

Additional Content

No response</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [enhancement]: Implement Phase 8 of the multiuser implementatoin plan #27

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[lstein]

@copilot There have been some significant changes in the multiuser mode since this pull request was first written. Could you examine the commits added to branch lstein-master and update the multiuser documentation? The important changes are as follows:

1. Single user mode is enabled when the new configuration file option multiuser is set to false or is absent.
2. In single user mode, the system will not ask for login credentials and all InvokeAI functionality will be enabled.
3. If boards or images were created while in multiuser mode and the server is then switched to single user mode, then those boards and images will be combined into a single unified view.
4. Legacy boards and images created under single-user mode will be owned by an internal user named "system." When switching to multiuser mode, only the Administrator will have access to these boards and images. A utility to migrate these legacy assets to another user will be part of a future release.
5. To add, delete and modify users and their passwords, there are several scripts in scripts named useradd.py, userdel.py, usermod.py and userlist.py. Please see the commit log messages and the contents of the scripts to describe their usage. Also mention that a web-based user interface that allows the Administrator to manage users and for users to change their display names and passwords is coming in a future release.

[Copilot]

@copilot There have been some significant changes in the multiuser mode since this pull request was first written. Could you examine the commits added to branch lstein-master and update the multiuse...

I've updated all three documentation guides to reflect the changes you described:

Key Updates:

1. Configuration: Documented the multiuser config option (true/false/absent determines mode)

2. Single-User Mode: Explained that when multiuser: false or absent, no login is required and all functionality is enabled

3. Mode Switching:

   • Switching to single-user: all boards/images combined into unified view
   • Switching to multi-user: legacy content owned by "system" user
   • Only admins can access "system"-owned assets until migration utility is available

4. CLI Scripts: Replaced web UI instructions with documentation for useradd.py, userdel.py, usermod.py, and userlist.py scripts, including usage examples

5. Future Features: Noted that web-based user management UI and user password change interfaces are coming in future releases

6. API Guide: Added adaptive client examples that detect and work with both single-user and multi-user modes

All changes are in commit 00f3817. The push is currently failing due to GitHub server errors (500), but the changes are committed locally and will push once GitHub recovers.

[lstein]

This branch got messed up by rebasing. Changes were cherry-picked into PR #50