User Management Guide

This guide covers user account management, permissions, and access control for the DDEV Coder template.

Overview

Coder uses a role-based access control (RBAC) system to manage users and their permissions. This guide focuses on template-specific considerations for the DDEV environment.

User Accounts

Creating User Accounts

Via Web UI:

  1. Log into Coder as admin
  2. Navigate to Users section
  3. Click Create User
  4. Enter username, email, password
  5. Assign roles (see Roles section below)
  6. Click Create

Via CLI:

# Create user
coder users create <username>

# Create user with email
coder users create <username> --email user@example.com

# Set password (user will be prompted)
coder users create <username> --set-password

User Roles

Coder has three built-in roles:

Role Permissions Use Case
Owner Full system access, manage all workspaces, templates, users System administrators
Template Admin Create/edit templates, manage own workspaces DevOps, platform team
Member Create/manage own workspaces from allowed templates Developers, users

Assigning roles:

# Set user roles
coder users edit-roles <username> --roles template-admin

# Set to member (default)
coder users edit-roles <username> --roles member

Template Access

By default, all users can access all templates.

Organization-based access:

User Provisioning

For organizations with SSO/OIDC:

Coder supports automatic user provisioning via:

Users are created on first login and assigned default role (Member).

See Coder Authentication Docs for setup.

Organizations

Organizations provide multi-tenancy and resource isolation.

Creating Organizations

# Create organization
coder organizations create <org-name>

# List organizations
coder organizations list

# Add user to organization
coder organizations members add <org-name> <username>

Template Deployment per Organization

# Deploy template to specific organization
coder templates push \
  --directory user-defined-web \
  --org <org-name> \
  user-defined-web \
  --yes

# Users can only create workspaces from templates in their organization

Use Cases for Organizations

SSH Key Management

Users need SSH keys for Git operations inside workspaces.

User SSH Keys

Users can add their own keys:

  1. Log into Coder UI
  2. Go to Account → SSH Keys
  3. Add public key
  4. SSH key is automatically available in all workspaces

Or via CLI (shows your Coder Git SSH public key):

coder publickey

SSH key management (add/remove keys) is done via the Coder web UI under Account → SSH Keys.

Git SSH Configuration

The DDEV template automatically configures Git SSH via Coder’s GitSSH wrapper:

# In workspace startup script (user-defined-web/scripts/startup.sh):
git config --global core.sshCommand "$GIT_SSH_COMMAND"

Users can clone repositories using SSH:

git clone git@github.com:user/repo.git

SSH Access to Workspaces

Users can SSH into their workspaces:

# SSH into workspace
coder ssh my-workspace

# Run command via SSH
coder ssh my-workspace -- ddev describe

# Port forwarding
coder port-forward my-workspace --tcp 8080:8080

Generate SSH config:

# Add workspaces to ~/.ssh/config
coder config-ssh

# Then SSH directly
ssh coder.my-workspace

API Tokens

Users need API tokens for CLI access and automation.

Creating Tokens

Via Web UI:

  1. Log into Coder
  2. Go to Account → Tokens
  3. Click Create Token
  4. Set expiration (optional)
  5. Copy token (shown once)

Via CLI:

# Create token
coder tokens create --name <token-name>

# List tokens
coder tokens list

# Remove token
coder tokens remove <token-id>

Using Tokens

# Login with token
coder login <coder-url> --token <token>

# Or set environment variable
export CODER_SESSION_TOKEN=<token>
coder list

Token Scopes

Tokens inherit user’s role permissions:

Security best practices:

Workspace Permissions

Ownership

Sharing Workspaces

Coder does not support workspace sharing out-of-the-box.

Workarounds for collaboration:

Option 1: VS Code Live Share

Option 2: Port Forwarding

Option 3: Shared Workspaces (Manual)

Option 4: Project handoff

Resource Quotas

Workspace Limits

Template-level defaults:

Edit user-defined-web/template.tf:

variable "cpu" {
  default     = 4
  validation {
    condition     = var.cpu <= 8
    error_message = "CPU must be 8 or less"
  }
}

variable "memory" {
  default     = 8
  validation {
    condition     = var.memory <= 16
    error_message = "Memory must be 16GB or less"
  }
}

Storage Quotas

Host-level disk quotas:

Each workspace uses:

Set filesystem quotas (Linux):

# Enable quotas on host filesystem
apt-get install quota
mount -o remount,usrquota,grpquota /home

# Set quota for workspace directories
setquota -u coder 50G 60G 0 0 /home

Monitor disk usage:

# Check workspace home directories
du -sh /coder-workspaces/*

# Check Docker volumes
docker system df -v | grep coder

Audit and Monitoring

User Activity

View workspace activity:

# List all workspaces with owners
coder list --all

# Show workspace details
coder show <workspace-name>

# View workspace logs
coder logs <workspace-name>

Resource Usage

Per-workspace metrics:

# Check running workspaces
coder list --all

# SSH into workspace and check resources
coder ssh <workspace> -- docker stats
coder ssh <workspace> -- df -h

Host-level monitoring:

# Check all workspace containers
docker ps | grep coder

# Check resource usage
docker stats $(docker ps --filter "name=coder" -q)

# Check disk usage
df -h /coder-workspaces/
docker system df

User Offboarding

Removing Users

# 1. List user's workspaces
coder list -a --search "owner:<username>"

# 2. Delete all user workspaces
for ws in $(coder list -a --search "owner:<username>" -c workspace | grep -v WORKSPACE); do coder delete "$ws" --yes; done

# 3. Remove user account
coder users delete <username>

# 4. Remove user tokens (list all tokens as owner, identify by user)
coder tokens list -a
coder tokens remove <token-id>

Data Retention

When deleting a user:

Backup before deletion:

# Backup user workspace data
tar -czf user-backup.tar.gz /coder-workspaces/<username>-*

# Backup Docker volumes
docker volume ls | grep coder-<username>

Access Control Best Practices

User Provisioning

  1. Use SSO/OIDC for enterprise environments
  2. Create users via CLI/API for automation
  3. Assign appropriate roles based on responsibility
  4. Set password policies (expiration, complexity)

Template Access

  1. Restrict sensitive templates to specific groups
  2. Use organizations for multi-team isolation
  3. Version templates for stability (don’t auto-update)

Security

  1. Enable 2FA for admin accounts
  2. Rotate API tokens regularly
  3. Monitor workspace activity for suspicious behavior
  4. Set resource quotas to prevent abuse
  5. Review user permissions quarterly

Onboarding Checklist

For new users:

Offboarding Checklist

For departing users:

Troubleshooting

User Can’t Create Workspace

Check:

# Verify user role
coder users show <username>

# Check template access
coder templates list --org <org>

User Can’t SSH into Workspace

Check:

# Test SSH
coder ssh <workspace> -- echo "SSH works"

# Check workspace status
coder show <workspace>

Git SSH Not Working

Check:

# Test Git SSH
coder ssh my-workspace -- git clone git@github.com:user/repo.git

# Check GitSSH wrapper
coder ssh my-workspace -- which coder
coder ssh my-workspace -- coder gitssh --help

Permission Denied Errors

Check:

# Check user details
coder users show <username>

Access Management

New account creation on coder.ddev.com and staging-coder.ddev.com is restricted to members of two GitHub organizations: the ddev org and the coder-ddev-com org. Additionally, members of $100+/month DDEV sponsor organizations can sign in directly.

Existing accounts created before this restriction was applied remain active. Password authentication remains available for manually pre-created exception accounts.

Granting access via coder-ddev-com org membership

The coder-ddev-com GitHub organization is the access list for individuals who are not members of the ddev org or a sponsor org. Adding someone to this org grants signup access without any Coder server change.

Steps:

  1. Go to github.com/coder-ddev-com → People → Invite member
  2. Enter the person’s GitHub username and send the invitation
  3. Once they accept the invitation, they can visit coder.ddev.com and sign in with GitHub

Note on private membership: Users do not need to make their coder-ddev-com membership public. Private membership is sufficient — Coder uses the read:org OAuth scope to verify membership regardless of visibility.

Pre-creating password exception accounts

For users who cannot authenticate via GitHub OAuth (e.g., users without a GitHub account, or accounts needed before org configuration is complete), an admin can pre-create a password-based account directly.

Via CLI:

# Create the account
coder users create <username> --email user@example.com

# Set a password interactively
coder users create <username> --email user@example.com --set-password

Via Web UI:

  1. Log in as admin
  2. Navigate to Admin → Users → Create User
  3. Fill in username, email, and password
  4. Assign the Member role

The user logs in at coder.ddev.com with their username and password — GitHub OAuth is not required for password accounts.

Important: CODER_DISABLE_PASSWORD_AUTH must never be set to true. Password authentication must remain available for these exception accounts.

Private org membership and the read:org scope

Users who are members of ddev, coder-ddev-com, or a sponsor org do not need to make that membership public. Coder requests the read:org GitHub OAuth scope, which allows it to verify private org membership during authentication. Users are prompted to grant this scope when they first click “Sign in with GitHub.”

Initial coder-ddev-com members

Add these individuals when creating the coder-ddev-com org:

GitHub username Reason
dougvann Individual $100/month GitHub Sponsor
claudiu-cristea Webikon sponsor (linked as individual on ddev.com)

The following sponsor contacts should also be added once their GitHub usernames are confirmed: LetsTalk, Amedick Sommer, Pottkinder GmbH.

Additional Resources