Skip to content

User Management

User Management

This guide explains how to manage users in the Tracker System. There are two ways to manage users:

  1. Admin Panel: The primary way to manage users through the user-friendly web interface
  2. CLI Tool: A development-only tool for working against the local Docker stack

User Management via Admin Panel

The admin panel provides a comprehensive interface for managing users, with features for creating, viewing, updating, and deleting user accounts.

Accessing User Management

  1. Log in to the admin panel with an admin account (the admin panel itself is restricted to the admin role — see Authentication & Authorization)
  2. Navigate to the "Users" section in the sidebar

Creating a User

  1. Click the add ("+") button on the Users card
  2. Fill in the fields in the "Add user" dialog:
  3. Name: User's full name
  4. Email: User's email address (used for login)
  5. Password: Initial password for the user (leave blank to email the user an invite instead)
  6. Confirm password
  7. Role: Select one role (user, manager, or admin)
  8. Client access: Check which clients the user can access (disabled/ignored for admins, who always have access to all clients)
  9. Notification preferences: Email notifications and/or UI notifications
  10. Click "Save user" to create the user

Viewing Users

The Users page displays a searchable, paginated card list with each user's:

  • Name and email
  • Role (shown as a colored badge)
  • SSO provider badge, if the account is linked to Google or Microsoft sign-in
  • Client access (client chips, or "All clients" for admins)

Use the filter box to search, and the role/client dropdowns to narrow the list. Cards can be shown two-up on wider screens.

Editing a User

  1. Hover over the user's card and click the edit action (edit/delete actions reveal on hover, matching the tracker/client cards elsewhere in the app)
  2. Update the user's information in the "Edit user" dialog
  3. Click "Save user" to apply the changes

If the user signed in via Google or Microsoft SSO, password login is disabled until the "Reset external auth binding" checkbox is used, which clears the SSO link and requires setting a new password.

Deleting a User

  1. Hover over the user's card and click the delete action
  2. Confirm the deletion in the confirmation dialog

User Roles

The system supports the following roles:

  • Admin: Full access to all features and data, and the only role that can access the admin panel itself
  • Manager: Access to data based on their client list, plus a few elevated permissions — managers can move trackers between production runs and create/edit child production runs (but not parent "batch" runs)
  • User: Access to data based on their client list, with no elevated permissions

Client Access Control

Users can be restricted to only access data related to specific clients:

  1. When creating or editing a user, check the clients they should have access to
  2. The user will only be able to view and manage data related to those clients
  3. Admin users bypass client filtering and can access all data

User Management CLI Tool

The User Management CLI tool allows you to create, update, and delete users from the command line. It is mainly useful in the Docker-based development environment, where you have direct access to the local database and can bootstrap or reset accounts quickly.

This tool is not a practical way to manage users in AWS deployments. Once the application is running on ECS, use the admin panel or the API instead.

Prerequisites

  • Docker Compose development stack running locally
  • Database connection configured for the local development environment

Usage

The User Management CLI tool provides several commands to manage users:

Create a User

./scripts/user create --name "Admin User" --email "admin@example.com" --password "securepassword" --roles admin,user

Parameters:

  • --name: User's full name (required)
  • --email: User's email address (required)
  • --password: User's password (required)
  • --roles: Comma-separated list of roles (default: "user")
  • --client-list: Comma-separated list of client IDs (optional)
  • --notification-preferences: JSON string of notification preferences (optional)

Example with all parameters:

./scripts/user create \
  --name "Admin User" \
  --email "admin@example.com" \
  --password "securepassword" \
  --roles admin,user \
  --client-list 1,2,3 \
  --notification-preferences '{"email":true,"ui":true}'

Update a User

./scripts/user update 1 --name "Updated Name" --password "newpassword"

Parameters:

  • user_id: ID of the user to update (required, positional argument)
  • --name: User's updated full name (optional)
  • --email: User's updated email address (optional)
  • --password: User's updated password (optional)
  • --roles: Comma-separated list of updated roles (optional)
  • --client-list: Comma-separated list of updated client IDs (optional)
  • --notification-preferences: JSON string of updated notification preferences (optional)

Example with multiple parameters:

./scripts/user update 1 \
  --name "Updated Name" \
  --email "updated@example.com" \
  --roles admin,user,manager

Delete a User

./scripts/user delete 1

Parameters:

  • user_id: ID of the user to delete (required, positional argument)

List All Users

./scripts/user list

Parameters:

  • --skip: Number of users to skip (default: 0)
  • --limit: Maximum number of users to return (default: 100)

Get a Specific User

./scripts/user get 1

Parameters:

  • user_id: ID of the user to get (required, positional argument)

Creating an Admin User

To create an initial admin user for the system:

./scripts/user create \
  --name "Admin User" \
  --email "admin@example.com" \
  --password "securepassword" \
  --roles admin

This will create a user with admin privileges who can then use the API to manage other users.

Common Scenarios

Initial System Setup

When setting up the system for the first time, you'll need to create an admin user:

./scripts/user create \
  --name "Admin User" \
  --email "admin@example.com" \
  --password "securepassword" \
  --roles admin

For staging bootstrap, the repository also includes an idempotent seed script that creates the default login accounts used by the frontend and admin panel:

python scripts/seed_default_users.py

This seeds the default development accounts:

  • admin@example.com / admin123
  • jane.smith@example.com / jane123

On AWS, those accounts should be created or managed through the deployed application flows rather than by running the CLI directly.

Resetting a User's Password

If a user forgets their password, you can reset it:

./scripts/user update 1 --password "newpassword"

Granting Admin Privileges

To grant admin privileges to an existing user:

./scripts/user update 1 --roles admin,user

Troubleshooting

Database Connection Issues

If you encounter database connection issues, check that:

  1. The database is running
  2. The connection details in .env are correct
  3. The user has permission to access the database

User Already Exists

If you get an error that a user already exists when trying to create a new user, you can either:

  1. Use a different email address
  2. Update the existing user instead of creating a new one
  3. Delete the existing user first (if appropriate)

User Not Found

When trying to get, update, or delete a user that doesn't exist, the API will return a 404 error with the message "The user with this id does not exist in the system". This can happen if:

  1. The user ID is incorrect
  2. The user has been deleted
  3. The database has been reset

In these cases, verify that the user ID is correct and that the user exists in the database.

Permission Issues

If you can't run the script due to permission issues, make sure the script is executable:

chmod +x scripts/user
chmod +x scripts/manage_users.py