---
layout: docs
page_title: Running Boundary in Non-Dev Environments
description: |-
  How to install boundary in non-dev environments.
---

# Installing Boundary Without Generated Resources

What are generated resources? When you run `boundary dev` or `boundary database init`, Boundary automatically
generates a number of resources to make getting started easier. Default scopes, auth methods, user, account, and
targets are just some of the resources Boundary will generate unless you tell it not to.

In a production or long-running environment, these resources are not necessary, but without them, managing
Boundary from scratch isn't straight forward. How do you create your first user and login to administer a Boundary
deployment that has no authentication methods, users, accounts, etc.? This section describes how to get your freshly
deployed Boundary installation off the ground for non-dev environments.

## Recovery KMS Workflow

Initializing Boundary without generated resources starts with your Boundary configuration file. Specifically,
the controller configuration specifies three KMS blocks:

```hcl
<truncated>
kms "aead" {
	purpose   = "root"
	aead_type = "aes-gcm"
	key       = "sP1fnF5Xz85RrXyELHFeZg9Ad2qt4Z4bgNHVGtD6ung="
	key_id    = "global_root"
}

kms "aead" {
	purpose   = "worker-auth"
	aead_type = "aes-gcm"
	key       = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
	key_id    = "global_worker-auth"
}

kms "aead" {
	purpose   = "recovery"
	aead_type = "aes-gcm"
	key       = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
	key_id    = "global_recovery"
}
<truncated>
```

In this example, we're using hardcoded AEAD keys, but in a real world non-dev deployment, you
should use your cloud provider's KMS such as [AWS KMS](/docs/configuration/kms/awskms) to manage the keys Boundary
uses to encrypt sensitive information.

The KMS block we're focused on is the `recovery` block. This block specifies the key used to "recover" Boundary
but you can also use it to authenticate to Boundary and manage it as a "global" super user. This allows
you to authenticate from the CLI or from Terraform in order to manage Boundary without any generated
resources.

To authenticate to Boundary using the recovery KMS workflow:

<Tabs>
<Tab heading="CLI">


To use the recovery workflow on the CLI, you must pass the `-recovery-config <path_to_kms_recovery_config>` flag or set the environment
variable for `BOUNDARY_RECOVERY_CONFIG` for every command ran. Authentication takes place for every command
ran when using the recovery workflow, there is no `boundary authenticate` step:

```bash
$ cat << EOF > /tmp/recovery.hcl
kms "aead" {
        purpose   = "recovery"
        aead_type = "aes-gcm"
        key       = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
        key_id    = "global_recovery"
}
EOF

$ boundary users create <truncated> -recovery-config /tmp/recovery.hcl
...
```

</Tab>
<Tab heading="Terraform">


To configure your provider to use the recovery KMS workflow, provide the KMS block as the value for
`recovery_kms_hcl`:

```hcl
provider "boundary" {
  addr             = 'https://boundary.mycorp.com:9200'
  recovery_kms_hcl = <<EOT
kms "aead" {
	purpose   = "recovery"
	aead_type = "aes-gcm"
	key       = "8fZBjCUfN0TzjEGLQldGY4+iE9AkOvCfjh7+p0GtRBQ="
	key_id    = "global_recovery"
}
EOT
}
```

</Tab>
</Tabs>


## Initialize the Database

Before you can start Boundary, the database must be initialized. It's useful to look at the help output for the init command:

```
$ boundary database init -h
...
```

From this command, you can see the flags available to skip the creation of auto-generated resources.

To initialize the Boundary database without generated resources:

```
$ boundary database init \
   -skip-auth-method-creation \
   -skip-host-resources-creation \
   -skip-scopes-creation \
   -skip-target-creation \
   -config /etc/boundary.hcl
```

When you start Boundary, you will effectively have a blank sheet to work against. The initial migrations in the database have been run (note that this includes creating special users like `u_anon` and the `global` scope) and the internal keyrings have been initialized. From here, it's required that
you use the KMS recovery workflow described above to create at a minimum an auth method, a user, an account, and a
role with sufficient grants. Otherwise, you need to continue to use the recovery workflow for management. It's important
to realize that this is effectively a global super user type of workflow and comes with security concerns.

## Creating Your First Login Account

This section covers how to configure your first auth method, user, account, and role to login to Boundary without
the recovery KMS workflow. In this example, we're going to make an admin user for the global and project level
scopes we create. This will allow our user to configure targets within those scopes and manage them.

### Create Org and Project Scopes

In this example, we're going to create an org and project scope and skip creating an administrator and admin role
for each scope. We're going to specify a role for managing these scopes by selected users in a later step.

<Tabs>
<Tab heading="CLI">


```bash
$ boundary scopes create -name 'org' -scope-id 'global' \
  -recovery-config /tmp/recovery.hcl \
  -skip-admin-role-creation \
  -skip-default-role-creation
<truncated>

$ boundary scopes create -name 'project' -scope-id <org_scope_id_from_last_step> \
  -recovery-config /tmp/recovery.hcl \
  -skip-admin-role-creation \
  -skip-default-role-creation
<truncated>
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_scope" "org" {
  scope_id    = "global"
  name        = "organization"
  description = "Organization scope"

  auto_create_admin_role   = false
  auto_create_default_role = false
}

resource "boundary_scope" "project" {
  name                     = "project"
  description              = "My first project"
  scope_id                 = boundary_scope.org.id
  auto_create_admin_role   = false
  auto_create_default_role = false
}
```

</Tab>
</Tabs>


### Create an Auth Method

Create an auth method in the organization scope.

<Tabs>
<Tab heading="CLI">


```bash
$ boundary auth-methods create password \
  -recovery-config /tmp/recovery.hcl \
  -scope-id <org_scope_id> \
  -name 'my_method' \
  -description 'My password auth method'
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_auth_method" "password" {
  name        = "my_password_auth_method"
  description = "Password auth method"
  type        = "password"
  scope_id    = boundary_scope.org.id
}
```

</Tab>
</Tabs>


### Create a Login Account

Create a login account for the auth method.

<Tabs>
<Tab heading="CLI">


```bash
$ boundary accounts create password \
  -recovery-config /tmp/recovery.hcl \
  -login-name "myuser" \
  -password "foofoofoo" \
  -auth-method-id <auth_method_id_from_last_step>
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_account" "myuser" {
  name           = "myuser"
  description    = "User account for my user"
  type           = "password"
  login_name     = "myuser"
  password       = "foofoofoo"
  auth_method_id = boundary_auth_method.password.id
}
```

</Tab>
</Tabs>


### Create a User

Create a user and associate the user with the login account created in the previous step.
This user will also be the principal in the role we create in the following step.

<Tabs>
<Tab heading="CLI">


```bash
$ boundary users create -scope-id <org_scope_id> \
  -recovery-config /tmp/recovery.hcl \
  -name "myuser" \
  -description "My user!"

$ boundary users add-accounts \
  -recovery-config /tmp/recovery.hcl \
  -id <myuser_user_id> \
  -account <myuser_account_id>
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_user" "myuser" {
  name        = "myuser"
  description = "My user!"
  account_ids = [boundary_account.myuser.id]
  scope_id    = boundary_scope.org.id
}
```

</Tab>
</Tabs>


### Create Roles to Manage Scopes

The following describes the four baseline roles you'll need to create to manage resources within the org and project
scopes created above. These roles are similar to the roles created for you if generation had not been skipped during `boundary database init` when executed with the `-skip-initial-login-role-creation` flag, Declaring roles explicitly
allows you to manage them independently and fully within Terraform or via the CLI. In doing so, you can precisely define their access.

The following example creates 4 roles:

1. To allow anonymous (unauthenticated) users the ability to list scopes and auth methods in the global scope.
1. To allow anonymous (unauthenticated) users the ability to list scopes and auth methods in the organization scope.
1. To allow `myuser` user administration grants at the org scope.
1. To allow `myuser` user administration grants at the project scope.

#### Anonymous listing role for global scope

<Tabs>
<Tab heading="CLI">


Assumes recovery key export from above steps is still set:

```bash
# Create global anonymous listing role
$ boundary roles create -name 'global_anon_listing' \
  -recovery-config /tmp/recovery.hcl \
  -scope-id 'global'

$ boundary roles add-grants -id <global_anon_listing_id> \
  -recovery-config /tmp/recovery.hcl \
  -grant 'id=*;type=auth-method;actions=list,authenticate' \
  -grant 'id=*;type=scope;actions=list,no-op' \
  -grant 'id={{account.id}};actions=read,change-password'

$ boundary roles add-principals -id <global_anon_listing_id> \
  -recovery-config /tmp/recovery.hcl \
  -principal 'u_anon'
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_role" "global_anon_listing" {
  scope_id = "global"
  grant_strings = [
    "id=*;type=auth-method;actions=list,authenticate",
    "id=*;type=scope;actions=list,no-op",
    "id={{account.id}};actions=read,change-password"
  ]
  principal_ids = ["u_anon"]
}
```

</Tab>
</Tabs>


#### Anonymous listing role for org scope

<Tabs>
<Tab heading="CLI">


Assumes recovery key export from above steps is still set:

```bash
$ boundary roles create -name 'org_anon_listing' \
  -recovery-config /tmp/recovery.hcl \
  -scope-id <org_scope_id>

$ boundary roles add-grants -id <org_anon_listing_id> \
  -recovery-config /tmp/recovery.hcl \
  -grant 'id=*;type=auth-method;actions=list,authenticate' \
  -grant 'type=scope;actions=list' \
  -grant 'id={{account.id}};actions=read,change-password'

$ boundary roles add-principals -id <org_anon_listing_id> \
  -recovery-config /tmp/recovery.hcl \
  -principal 'u_anon'
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_role" "org_anon_listing" {
  scope_id = boundary_scope.org.id
  grant_strings = [
    "id=*;type=auth-method;actions=list,authenticate",
    "type=scope;actions=list",
    "id={{account.id}};actions=read,change-password"
  ]
  principal_ids = ["u_anon"]
}
```

</Tab>
</Tabs>


#### Org admin role for myuser

<Tabs>
<Tab heading="CLI">


Assumes recovery key export from above steps is still set:

```bash
$ boundary roles create -name 'org_admin' \
  -recovery-config /tmp/recovery.hcl \
  -scope-id 'global' \
  -grant-scope-id <org_scope_id>

$ boundary roles add-grants -id <org_admin_id> \
  -recovery-config /tmp/recovery.hcl \
  -grant 'id=*;type=*;actions=*'

$ boundary roles add-principals -id <org_admin_id> \
  -recovery-config /tmp/recovery.hcl \
  -principal <myuser_user_id>
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_role" "org_admin" {
  scope_id       = "global"
  grant_scope_id = boundary_scope.org.id
  grant_strings = [
    "id=*;type=*;actions=*"
  ]
  principal_ids = [boundary_user.myuser.id]
}
```

</Tab>
</Tabs>


#### Project admin for myuser

<Tabs>
<Tab heading="CLI">


Assumes recovery key export from above steps is still set:

```bash
$ boundary roles create -name 'project_admin' \
  -recovery-config /tmp/recovery.hcl \
  -scope-id <org_scope_id> \
  -grant-scope-id <project_scope_id>

$ boundary roles add-grants -id <project_admin_id> \
  -recovery-config /tmp/recovery.hcl \
  -grant 'id=*;type=*;actions=*'

$ boundary roles add-principals -id <project_admin_id> \
  -recovery-config /tmp/recovery.hcl \
  -principal <myuser_user_id>
```

</Tab>
<Tab heading="Terraform">


```hcl
resource "boundary_role" "project_admin" {
  scope_id       = boundary_scope.org.id
  grant_scope_id = boundary_scope.project.id
  grant_strings = [
    "id=*;type=*;actions=*"
  ]
  principal_ids = [boundary_user.myuser.id]
}
```

</Tab>
</Tabs>


### Login as Your New User

```bash
boundary authenticate password \
  -auth-method-id <auth_method_id> \
  -login-name myuser \
  -password foofoofoo
```