Skip to content

Admin Overview

Jump to bottom
Andrew den Hertog edited this page Dec 3, 2025 · 1 revision

Administrator Guide Overview

This guide is for platform administrators who manage the Codex Web platform, including user accounts, groups, and system configuration.

Administrator Responsibilities

As a platform administrator, you have full access to:

User Management

  • Create and delete user accounts
  • Enable and disable accounts
  • Reset user passwords
  • Promote/demote admin privileges
  • Manage user group memberships

Group Management

  • Create and delete groups
  • Configure group resource quotas
  • Assign users to groups
  • Set group admin roles
  • Monitor group resource usage

Workspace Administration

  • View all workspaces across the platform
  • Delete any workspace
  • Monitor workspace resource consumption
  • Troubleshoot workspace issues

System Management

  • Configure system settings
  • Monitor platform health
  • View audit logs
  • Analyze platform statistics
  • Manage resource allocation

Quick Links

User Account Management

Group & Resource Management

Platform Operations

Admin Roles Overview

Platform Admin

Full Access:

  • ✅ All user management operations
  • ✅ Create/delete/modify groups
  • ✅ Manage all workspaces
  • ✅ View all audit logs
  • ✅ Configure system settings
  • ✅ View platform statistics

Use Cases:

  • IT administrators
  • DevOps engineers
  • Platform operators

Group Admin

Limited Scope:

  • ✅ Manage workspaces in their group(s)
  • ✅ View group members
  • ✅ Monitor group resources
  • ❌ Cannot add/remove group members
  • ❌ Cannot modify group quotas
  • ❌ Cannot create groups

Use Cases:

  • Team leads
  • Project managers
  • Senior developers

See: Privilege Guidelines for detailed comparison

Admin Dashboard

Accessing Admin Features

Admin Panel:

  1. Log in to Codex Web
  2. Click your avatar/name (top-right)
  3. Select Admin Panel
  4. Access admin-only features

Admin Routes:

  • /admin/users - User management
  • /admin/groups - Group management (if group create UI exists)
  • /admin/workspaces - All workspaces
  • /admin/stats - Platform statistics
  • /admin/audit - Audit logs
  • /admin/settings - System settings

Platform Statistics

Overview Dashboard:

┌─────────────────────────────────────────┐
│ Platform Statistics                     │
├─────────────────────────────────────────┤
│ Total Users:           125              │
│ Admin Users:           3                │
│ Total Groups:          12               │
│ Total Workspaces:      89               │
│ Running Workspaces:    34               │
├─────────────────────────────────────────┤
│ Activity (Last 7 Days)                  │
│ Active Users:          87               │
│ Workspace Utilization: 38%              │
└─────────────────────────────────────────┘

Resource Usage:

  • Total CPU allocated
  • Total memory allocated
  • Storage consumption
  • Pod count across clusters

Common Admin Tasks

Daily Operations

Monitor Platform Health:

  1. Check /admin/stats dashboard
  2. Review resource utilization
  3. Check for error states
  4. Monitor active workspaces

User Support:

  1. Respond to access requests
  2. Reset passwords as needed
  3. Troubleshoot workspace issues
  4. Assist with group access

Weekly Tasks

User Management:

  • Create new user accounts
  • Process offboarding requests
  • Review inactive accounts
  • Update group memberships

Resource Review:

  • Analyze group resource usage
  • Identify resource bottlenecks
  • Plan capacity adjustments
  • Clean up abandoned workspaces

Audit Review:

  • Review admin action logs
  • Check for anomalies
  • Verify compliance
  • Document incidents

As-Needed Tasks

Group Creation:

  • Create new groups for teams/projects
  • Configure resource quotas
  • Assign initial members
  • Set up group admins

Quota Adjustments:

  • Increase group limits as needed
  • Rebalance resources between groups
  • Plan for growth

Troubleshooting:

  • Investigate workspace failures
  • Debug authentication issues
  • Resolve resource conflicts
  • Address user issues

API Access for Admins

All admin operations are available via REST API:

Authentication

# Get your JWT token (from browser dev tools or OAuth flow)
export TOKEN="your-jwt-token"

API Endpoints

User Management:

# List all users
curl -H "Authorization: Bearer $TOKEN" \
  https://your-codex.com/api/admin/users

# Create user
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","name":"User Name","groups":[],"isAdmin":false}' \
  https://your-codex.com/api/admin/users

# Update user
curl -X PATCH -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Name"}' \
  https://your-codex.com/api/admin/users/{userId}

# Delete user
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  https://your-codex.com/api/admin/users/{userId}

Group Management:

# Create group
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"team-a","displayName":"Team A","namespace":"codex-team-a"}' \
  https://your-codex.com/api/groups

# Add user to group
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"groupId":"grp_123","role":"member"}' \
  https://your-codex.com/api/admin/users/{userId}/groups

System Operations:

# Get platform stats
curl -H "Authorization: Bearer $TOKEN" \
  https://your-codex.com/api/admin/stats

# Get audit logs
curl -H "Authorization: Bearer $TOKEN" \
  https://your-codex.com/api/admin/audit-logs

# Get system settings
curl -H "Authorization: Bearer $TOKEN" \
  https://your-codex.com/api/admin/settings

See the API documentation for complete endpoint details.

Best Practices

User Management

Account Creation:

  • Use clear naming conventions
  • Assign to appropriate groups immediately
  • Set correct admin status
  • Document special access

Access Control:

  • Follow principle of least privilege
  • Regularly review admin users
  • Audit group memberships quarterly
  • Remove access promptly when users leave

Password Management:

  • Enforce strong passwords via auth provider
  • Regularly rotate admin credentials
  • Use temporary passwords for new users
  • Enable MFA when possible

Group Management

Resource Allocation:

  • Start with conservative quotas
  • Monitor actual usage before increasing
  • Balance resources across groups fairly
  • Plan for peak usage patterns

Group Organization:

  • Align groups with organizational structure
  • Use clear, consistent naming
  • Document group purposes
  • Establish group ownership

Namespace Conventions:

  • Use predictable naming: codex-{team-name}
  • Keep names short and readable
  • Avoid special characters
  • Document namespace mapping

Workspace Administration

Monitoring:

  • Identify idle workspaces weekly
  • Track resource-heavy workspaces
  • Monitor workspace age
  • Clean up abandoned workspaces

Intervention:

  • Contact owners before deleting
  • Give notice for cleanup
  • Document deletions
  • Maintain audit trail

Security and Compliance

Audit Logging:

  • Review logs regularly
  • Investigate anomalies
  • Track admin actions
  • Maintain log retention policy

Access Reviews:

  • Quarterly user access reviews
  • Document admin privileges
  • Remove unnecessary admin access
  • Audit group memberships

Incident Response:

  • Document security incidents
  • Have rollback procedures
  • Maintain emergency contacts
  • Test recovery procedures

Troubleshooting Common Issues

User Can't Log In

Check:

  1. User exists in DynamoDB
  2. User is enabled in Cognito
  3. User has group memberships
  4. JWT token is valid

Solutions:

  • Reset password via Cognito
  • Re-enable account if disabled
  • Verify OAuth configuration
  • Check auth provider logs

Workspace Won't Start

Investigate:

  1. Check group resource quotas
  2. View workspace logs
  3. Verify namespace exists
  4. Check Kubernetes events

Common Causes:

  • Insufficient group resources
  • Invalid workspace image
  • Storage quota exceeded
  • Network policy issues

Group Creation Fails

Verify:

  1. Namespace doesn't already exist
  2. Resource quotas are valid
  3. Kubernetes is accessible
  4. Sufficient cluster capacity

Debug:

# Check if namespace exists
kubectl get namespace {namespace-name}

# View recent events
kubectl get events -n {namespace-name}

Resource Quota Issues

Symptoms:

  • Can't create workspaces
  • Workspaces stuck in Pending
  • Resource limit errors

Resolution:

  1. Check group resource usage
  2. Identify resource hogs
  3. Stop idle workspaces
  4. Increase quota if justified

Support and Escalation

User Support Tiers

Tier 1: Group Admins

  • Workspace issues within their group
  • Basic troubleshooting
  • Group-specific questions

Tier 2: Platform Admins

  • Account and access issues
  • Cross-group problems
  • System configuration
  • Resource allocation

Tier 3: Platform Engineers

  • Infrastructure issues
  • Kubernetes problems
  • Database issues
  • Code bugs

Escalation Process

  1. Gather Information:

    • User ID and email
    • Workspace ID (if applicable)
    • Error messages
    • Steps to reproduce

  2. Check Logs:

    • Application logs
    • Kubernetes pod logs
    • Audit logs
    • Browser console (if UI issue)

  3. Attempt Resolution:

    • Apply known fixes
    • Consult documentation
    • Check similar past issues

  4. Escalate if Needed:

    • Provide all gathered information
    • Document troubleshooting steps
    • Explain urgency/impact
    • Set expectations

Getting Started as a New Admin

First Steps

  1. Access Admin Panel:

    • Verify your admin privileges
    • Explore the admin UI
    • Familiarize yourself with layout

  2. Review Current State:

    • Check platform statistics
    • Review existing users
    • Understand group structure
    • Note resource allocation

  3. Review Documentation:

    • Read all admin guides
    • Understand workflows
    • Learn API endpoints
    • Review troubleshooting guides

  4. Shadow Existing Admins:

    • Observe admin actions
    • Ask questions
    • Learn processes
    • Understand escalation

  5. Practice in Non-Prod:

    • Test user creation
    • Try group operations
    • Practice workspace management
    • Learn safely

Additional Resources

Technical Documentation:

  • CLAUDE.md - Developer guide
  • backend/README.md - Backend technical docs
  • frontend/README.md - Frontend technical docs
  • Repository wiki - This documentation

External Resources:

  • AWS Cognito documentation
  • Kubernetes documentation
  • DynamoDB best practices
  • Express.js guides

Next Steps

Continue to specific admin guides:

Home | User Account Management →

Clone this wiki locally