Environments

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

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.

config.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:

Terminal
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 -remote=<env>[#<machine>] to run against a deployed machine instead of the local project.

Terminal
elements build -remote=production -json
elements db -remote=production#production1
elements test -remote=staging -json
elements ssh -remote=production
elements ssh -remote=production#production2

-remote without a value uses the first machine in production.

Reach for -remote 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.