# Environments

Naming and targeting environments, running tests before a deploy, and pointing a
command at a deploy machine with -connect.

An environment is a runtime target, and the set is small and well-known:
`development` (your local machine), `production` (the live site), and
`staging` (a live pre-production site) when you want one. The name selects both
the env file (`config/env/<name>.env`) and the deploy target
(`deploy.env.<name>`).

An environment is not a site or a label. Deploying a second site (a demo, a
marketing page, a client's instance) is a normal deploy to `production` (or
`staging`) with its own domain and machines, not a new environment named after
the site. Naming an environment `demo` just produces a stray
`config/env/demo.env` and a target nothing else knows about. Reach for a new
environment only when you have a genuinely separate runtime tier with its own
machines.

`deploy.env` is a map of environment names to per-environment overrides.

```jsoc
deploy: {
  domain: "example.com",                    // shared default
  ssh: { user: "ubuntu", ... },             // shared default
  env: {
    production: {
      machines: [...],
    },
    staging: {
      domain: "staging.example.com",        // override
      machines: [...],
    },
  },
}
```

`elements deploy` defaults to `production`. `elements deploy <env>` targets a
named environment.

Per-environment overrides: `port`, `address`, `domain`, `ssl`, `tlsCerts`,
`maint`, `ignoreStaleMigrations`, `license`, `ssh`, `services`, `packages`,
`redirects`, `machines`.

`port` and `address` resolve `deploy.env.<name>` first, then `deploy`, then the
top-level `server` block, then the defaults (4000 and `127.0.0.1`). Set them
under `server` when you just want to change the port the app listens on; set
them here when one deployed environment needs something different.

## Timeout

A deploy fails if it runs longer than `-timeout` (default 30m). Raise it for a
first deploy to a slow machine, where provisioning dominates:

```bash
elements deploy -timeout=1h
```

## Tests

Tests run as part of every deploy, against the target environment's test
database. There is no `test` environment to switch to in Elements. Each deploy
environment has both an app database (`<app>`) and a test database
(`<app>_test`), and tests for that environment run against the test database
before the release goes live. A failing test aborts the deploy and the previous
release continues serving traffic.

If you want an environment dedicated to verifying changes before production,
configure a `staging` environment. Tests run there on every deploy the same way
they run on production, against that environment's test database.

## Connecting to Deploy Machines

Most commands accept `-connect=<env>[#<machine>]` to run against a deployed
machine instead of the local project.

```
elements build -connect=production -json
elements db -connect=production#production1
elements test -connect=staging -json
elements ssh -connect=production
elements ssh -connect=production#production2
```

`-connect` without a value uses the first machine in `production`.

Reach for `-connect` when you have a question about a running deploy that you
went looking for on purpose. A failed `elements deploy` is not one: its
diagnostics already report what happened on the machine. See
[Operations](operations).