Skip to content

User Management

New as of 1.3

User management is available in Dokku Pro 1.3 and later.

Users are a Dokku Pro construct built on top of Dokku's ssh-keys plugin. A user created with users:create is automatically mapped to the matching SSH key added via ssh-keys:add, can sign in to the Dokku Pro UI and API, and is granted whatever access their teams provide. This page covers the users:* CLI commands; to manage the same users from the browser, see Managing Users.

users:create <user> [<password>] # Create a user
users:destroy <user>             # Destroy a user
users:list                       # List all users
users:refresh-reset-token <user> # Refresh the password reset token for a user
users:report [<user>]            # Gets info for a user

Installing the Users Plugin

Note

The users plugin requires the teams plugin to be enabled.

Before using the commands, install the plugin:

# make the plugin available for dokku
sudo dokku-pro teams:install

# enable the teams plugin in dokku
sudo dokku plugin:enable teams

# enable the users plugin in dokku
sudo dokku plugin:enable users

# enable integration with dokku
sudo dokku teams:enable

Special Users

The admin and dokku users are special, root-level users that cannot be added or removed. A password can be associated with them, and SSH keys are associated appropriately.

In addition, the Dokku Pro UI comes configured with a single root user. By default its username is root; it can be changed with an environment variable (see the Configuration documentation).

Adding Users

Note

By default, only admins can create users. The user commands can be granted to a team.

To add a user, run users:create with a username and an optional password:

dokku users:create camilla super-long-password

Username rules (updated in 1.4.0)

A username must begin with an alphanumeric character and cannot contain / or :. Uppercase letters and underscores are permitted (as are ., -, and @), so an email such as Alice@example.com is a valid username. Usernames are case-sensitive but unique case-insensitively: you cannot create Bob while bob exists. This is what lets a name from an upstream proxy map onto a user - see Reverse Proxy Authentication.

If no password is specified, a reset token is written to the user's record and a message like the following is printed. Give the user the reset URL so they can set their own password securely.

Password not specified for user, please have user browse to https://admin.dokku.me/auth/reset?token=ztYsYDzGAl to set an initial password

The same reset URL and token are shown on the user's page in the UI:

A user's page showing the generated single-use password reset link and token A user's page showing the generated single-use password reset link and token
The password reset link on a user's page

Destroying Users

Remove a user with users:destroy. Only the user is removed - remove the SSH key separately with ssh-keys:remove.

dokku --force users:destroy camilla

-----> Destroying camilla...
 !     Skipping ssh-key removal for user, run 'dokku ssh-keys:remove camilla' to remove ssh-keys

Listing Users

Warning

This command does not include the default root user configured for Dokku Pro. It lists only users explicitly added via users:create.

List users with users:list:

dokku users:list

-----> Users
camilla

Refreshing a User's Password Reset Token

Refresh a user's password reset token with users:refresh-reset-token. This generates a new token and prints the new reset URL.

dokku users:refresh-reset-token camilla

-----> Refreshing password reset token for camilla...
       Password reset token refreshed for user, please have user browse to https://admin.dokku.me/auth/reset?token=bowYpDyPCv to set a password

Displaying a User Report

Display a report for a user with users:report:

dokku users:report camilla

=====> camilla user information
       User reset url:                https://admin.dokku.me/auth/reset?token=bowYpDyPCv
       Username:                      camilla