Team Management

New as of 1.2

Team management is available in Dokku Pro 1.2 and later.

Team management controls which users may run which commands against which apps and services. You group users into teams, grant each team access to a set of commands, apps, and services, and a user gets the combined access of every team they belong to. This page covers the teams:* CLI commands; to manage the same teams from the browser, see Managing Teams.

teams:app-add <team> [<app> ...]                        # add an app to a team
teams:app-remove <team> [<app> ...]                     # remove an app from a team
teams:apps-set <team> <app> ...                         # set the apps for a team
teams:command-add <team> [<command> ...]                # allow a team to access specific command(s)
teams:command-remove <team> [<command> ...]             # remove team access to specific command(s)
teams:commands-set <team> <command> ...                 # set the commands for a team
teams:create <team>                                     # create a team
teams:destroy <team>                                    # destroy a team
teams:list                                              # list all teams
teams:member-add <team> [<user> ...]                    # add a user to a team
teams:member-remove <team> [<user> ...]                 # remove a user from a team
teams:members-set <team> <user> ...                     # set the members for a team
teams:owner-add <team> [<user> ...]                     # add a team owner
teams:owner-remove <team> [<user> ...]                  # remove a team owner
teams:owners-set <team> <user> ...                      # set the owners for a team
teams:service-add <team> [<service-type> <service>]     # add a service to a team
teams:service-remove <team> [<service-type> <service>]  # remove a service from a team
teams:services-set <team> <service-type> <service> ...  # set the services for a team
teams:team-report <team>                                # display a report about a team
teams:whoami                                            # outputs current user
teams:whois <user>                                      # outputs user information

The teams plugin can be disabled safely if you do not need it. Dokku core has native support for the plugin, but not every community plugin does; those must be updated to participate in the team system (see the plugin development documentation).

How It Works

Dokku Pro's team system is made of the following objects:

Teams - groups of users that are granted permission to run commands against apps and services.
Admins - a special team of users with full access to the entire Dokku system.
Owners - a team can have one or more owners. Owners can add and remove other owners and administer team membership. Owners do not inherit the command, app, or service access a member has, but they can grant themselves membership in their own teams to gain it.
Members - team members have the access to commands, apps, and services the team grants.
Commands - almost any dokku command can be added to or removed from a team; combining commands with apps and services is what lets members act on the system.
Apps - Dokku apps can be added to or removed from teams, and are combined with the team's commands to scope actions.
Services - Dokku services can be added to or removed from teams, the same way. All official datastore plugins are supported as services by Dokku Pro.

To show how the system might work, here are a few hypothetical teams:

Team Name: "elevated-access"
- Owners: camila
- Members: jose, michael
- Commands: *
- Apps: *
- Services: *
Team Name: "restricted-users"
- Owners: camila
- Members: eli, danielle
- Commands: git-*, postgres:create, apps:list
- Apps: node-js-app
- Services:
Team Name: "fancy-users"
- Owners: camila
- Members: eli
- Commands: git-*, apps:*
- Apps: ruby-app
- Services:

With the above setup, the following holds true:

Both the jose and michael users can perform almost every action¹ in the system.
The users eli and danielle can perform git-* operations for the node-js-app app - necessary for deployments - as well as create postgres databases and list the node-js-app.
The eli user additionally sees the ruby-app in their output, and can perform git actions as well as any action in the apps: command-space for the ruby-app. apps: commands that do not require app access - such as app creation via apps:create - are also available to eli.
Finally, if jose, michael, and eli create apps - as allowed by their commands - they become owners of those apps and can run all app-specific commands against them.

Team permissions restrict commands to apps and services, so users cannot escalate access by being added to groups that combine non-overlapping resources with a different set of available commands.

Installing the Teams Plugin

Before usage, 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

Warning

As of Dokku Pro 1.2.x, there is a bug in creating cache directories used by the teams plugin. Work around it by running mkdir -p /var/lib/dokku/data/teams && chown dokku:dokku /var/lib/dokku/data/teams as the root user on your host.

Installing the plugin and enabling it in Dokku exposes the CLI commands, but the teams:enable command must also be run in order to:

set up custom triggers that add and remove teams when apps or services are created
integrate with the authentication system in Dokku and official Dokku plugins
set up the initial dokku@admin team
create app-specific teams (without any initial users or owners) for each existing app

Note

The dokku@admin team is a special team that grants access to all commands for all apps and services. When teams:enable is first triggered, all existing users - as reported by the ssh-keys plugin - are migrated into the dokku@admin team if it does not already exist. Users added via the initial web UI are also added to the dokku@admin team. Permissions for the dokku@admin team cannot be changed.

Checking the Current User

Note

Users can always check who they are via the teams:whoami command.

The teams:whoami command reports the current user, including their name and all the teams they are associated with.

dokku teams:whoami

=====> root user information
       User app membership:
       User app ownership:
       User is global admin:          true
       User membership:               elevated-access
       User ownership:                elevated-access
       User service membership:
       User service ownership:
       Username:                      root

Show a single field with the corresponding flag:

# show only the username
dokku teams:whoami --username

# show only the user membership, space-delimited
dokku teams:whoami --user-membership

Output can also be shown as JSON. Note that the membership and ownership values are a single space-delimited string rather than an array.

dokku teams:whoami --format json

{"user-membership":"elevated-access", "user-ownership":"elevated-access","username":"root", ...}

Checking a Specific User

Note

This command can only be run for the current user, or by a global admin.

The teams:whois command reports information about a given user, including their name and all the teams they are associated with.

dokku teams:whois root

=====> root user information
       User app membership:
       User app ownership:
       User is global admin:          true
       User membership:               elevated-access
       User ownership:                elevated-access
       User service membership:
       User service ownership:
       Username:                      root

Users that do not exist do not error, but their permissions are empty.

Show a single field with the corresponding flag:

# show only the username
dokku teams:whois root --username

# show only the user membership, space-delimited
dokku teams:whois root --user-membership

Output can also be shown as JSON. Note that the membership and ownership values are a single space-delimited string rather than an array.

dokku teams:whois root --format json

{"user-membership":"elevated-access", "user-ownership":"elevated-access","username":"root", ...}

Listing Teams

List teams with teams:list. This includes only teams the logged-in user has access to; for non-owners, that is only the teams they belong to.

dokku teams:list

=====> Teams
dokku@admin
elevated-access
restricted-users

Logged-in admins see all teams on the server, whether or not they belong to them.

Creating Teams

Reserved team names

A few team types are special:

dokku@admin - global admin users.
dokku@app--${APP} - managed automatically per app.
dokku@service--${SERVICE_TYPE}-${SERVICE} - managed automatically per service.

Custom team names must therefore not include the dokku@ prefix.

A user in the admin group can create a team with teams:create.

dokku teams:create elevated-access

Creating elevated-access

The user that created the team is set as its owner.

Destroying Teams

A team can be destroyed by an admin or a team owner with teams:destroy.

dokku teams:destroy elevated-access

 !     WARNING: Potentially Destructive Action
 !     This command will destroy the team elevated-access.
 !     To proceed, type "elevated-access"

> elevated-access
Destroying elevated-access

Destroying a team that does not exist, or one the current user cannot access, returns an error.

Owners and Members

Adding Owners to a Team

Warning

Non-existent users can be added as owners to pre-configure a team. Destroying the user does not remove them from the team. This behavior is subject to change in the future.

Admins and team owners can administer a team's permissions and membership. Add owners with teams:owner-add.

dokku teams:owner-add elevated-access other-user

Removing Owners From a Team

Admins and team owners can remove owners with teams:owner-remove.

dokku teams:owner-remove elevated-access other-user

A team must have at least one owner; attempting to remove the last owner returns an error.

Adding a User to a Team

Warning

Non-existent users can be added as members to pre-configure a team. Destroying the user does not remove them from the team. This behavior is subject to change in the future.

Adding a user to a team with teams:member-add grants them everything the team allows.

dokku teams:member-add elevated-access jose

A user can belong to multiple teams, combining overlapping permissions to broaden their access.

Removing a User From a Team

Removing a user from a team with teams:member-remove revokes any access not covered by their other teams.

dokku teams:member-remove elevated-access jose

Command Management

Warning

Internal teams cannot have their command access modified.

Commands must be whitelisted before a team can run them. Running a command that is not whitelisted returns an error.

Admin-Only Commands

For security reasons, the following commands may only be run by an admin. This list is subject to change as Dokku and Dokku Pro evolve.

domains:add-global
domains:clear-global
domains:remove-global
domains:set-global
events
events:list
events:off
events:on
git:allow-host
git:auth
logs:vector-start
logs:vector-stop
network:create
network:destroy
network:exists
network:info
network:list
network:rebuildall
shell
trace:on

Additionally, any command invoked with the --global flag is executable only by an admin.

Allowing Access to Specific Commands

Note

Only admins can add commands to a team.

Grant command access with teams:command-add.

dokku teams:command-add restricted-users postgres:create

Commands can be globbed with the * operator. When present, the entry is treated as a POSIX regex for command matching, which can whitelist all commands or a subset of a plugin's commands.

# the `*` character must be single-quoted
dokku teams:command-add elevated-access '*'

dokku teams:command-add restricted-users 'git*'

If a team has no commands added, its members cannot run any command on an app or service, regardless of other permissions.

Removing Access to Specific Commands

Remove a previously added command with teams:command-remove.

dokku teams:command-remove restricted-users postgres:create

Commands are matched as a literal string against those currently associated with the team.

dokku teams:command-remove restricted-users 'git*'

App Access

Warning

Internal teams cannot have their app access modified.

By default, teams have no access to any app. Any command that acts on an app is not executable - and returns an opaque error that does not reveal whether the app exists - until the app is added to a team.

Allowing Access to Specific Apps

Note

Only admins can add apps to a team.

Add apps to a team with teams:app-add.

dokku teams:app-add elevated-access node-js-app

Non-existent apps can be specified, allowing you to pre-configure permissions before an app exists. As a result, app permissions are not removed from teams when an app is deleted. Permissions do persist through clones and renames.

The special * operator grants access to all apps. It is not treated as a regex and overrides any other apps currently attached to the team.

# the `*` character must be single-quoted
dokku teams:app-add elevated-access '*'

Removing Access to Specific Apps

Remove apps from a team with teams:app-remove.

dokku teams:app-remove elevated-access node-js-app

The special * operator can also be removed from a team.

# the `*` character must be single-quoted
dokku teams:app-remove elevated-access '*'

Service Access

Warning

Internal teams cannot have their service access modified.

Service plugins can also take advantage of the team system. Services do not need to be whitelisted in Dokku core; they simply use the appropriate service "namespace" for access control (see the plugin development documentation).

If a service plugin supports the team system and a user lacks access to the service, an opaque error - one that does not indicate whether the service exists - is returned.

Allowing Access to a Service

Note

Only admins can add services to a team.

Add a service to a team with teams:service-add, giving a service-type and a service name.

dokku teams:service-add elevated-access postgres test-db

Non-existent services can be specified, allowing you to pre-configure permissions before a service exists. As a result, service permissions are not removed from teams when a service is deleted.

All services of a service-type can be allowed with the * operator. It is not treated as a regex and cannot be combined with other characters. Adding it overrides any other services of that type attached to the team.

# the `*` character must be single-quoted
dokku teams:service-add elevated-access postgres '*'

All services of all service-types can be whitelisted by giving only a * for the service-type argument. It is not treated as a regex and cannot be combined with other characters. Adding it overrides any other service settings on the team.

# the `*` character must be single-quoted
dokku teams:service-add elevated-access '*'

Removing Access to a Service

Remove a service from a team with teams:service-remove, giving a service-type and a service name.

dokku teams:service-remove elevated-access postgres test-db

The * operator can be removed the same way it was added.

# the `*` character must be single-quoted
dokku teams:service-remove elevated-access postgres '*'

# the `*` character must be single-quoted
dokku teams:service-remove elevated-access '*'

Displaying a Team Report

Global admins can get a report about a team with teams:team-report.

dokku teams:team-report dokku@admin

=====> dokku@admin team information
       Team apps:
       Team commands:
       Team is internal:              true
       Team is internal app team:     false
       Team is internal service team: false
       Team members:
       Team name:                     dokku@admin
       Team owners:                   admin1 default
       Team services:

Pass a flag to output only the value you want. For example:

dokku teams:team-report dokku@admin --team-members

Integrating Custom Plugins

A plugin that wants to implement the team system can call any of the following plugin triggers:

plugn trigger user-auth SSH_USER SSH_NAME COMMAND - exits with an error if the user does not have access to the command. Used for commands that do not interact with a specific app or service.
plugn trigger user-auth-app SSH_USER SSH_NAME APP - exits with an opaque error if the user does not have access to the app.
plugn trigger user-auth-service SSH_USER SSH_NAME SERVICE_TYPE SERVICE_NAME - exits with an opaque error if the user does not have access to the service.

Each plugin must implement these triggers before any logic runs. Plugins should avoid calling the dokku binary directly, since a command may not be available to a user, so commands that mutate state may partially fail.

The following triggers are already implemented in Dokku core:

user-auth - implemented within the dokku binary itself.
user-auth-app - implemented by any plugin that calls common.DokkuApps() (Go) or dokku_apps (shell).

As noted in the Admin-Only Commands section, some commands require global administrative access to be performed by users. ↩