Environments

An environment is a copy of a hosted app where you can try a release before production. There are two kinds:

The per-app limits are the defaults; the platform can change them. Environments are opt-in: nothing exists until you turn one on.

What an environment is

An environment is a child site of the production site. It brings its own pieces:

• Its own Identity app, live on the environment address, so its people, sign-in settings and callbacks are separate from production. Callbacks default to /callback on the environment address.
• Its own small App Data instance. The database sleeps when idle and wakes when something connects.
• Its own site, namespace and logins.

Its people and its data are separate from production's: it has its own Identity app and its own database.

An environment sleeps when nobody uses it and wakes when someone opens it. A sweep runs every 15 minutes for the organization that has environments. It marks idle ones as paused, and it lists previews past their time to live. It does not remove them: turn a preview off when its pull request is done.

Turn one on

Run apphost.environment.enable.

It creates the Identity app, the child site, the database and the backup policy, and makes sure the organization's sweep is scheduled. It is idempotent: a run that failed part way is finished by running it again, and running it for an environment that already exists finds that one instead of making another.

In Orkestia Cockpit, Apps → an app → Run → Environments does this for you.

See them

apphost.environment.status with the production site as parent_site_uuid lists its environments. Each item has:

site_uuid, kind, state, slug, hostname, pr_number, identity_app_uuid, last_used_at, ttl_at and active_release_uuid.

state is paused while asleep and destroying while being turned off. apphost.site.list also marks environment sites with environment_kind, environment_state and parent_site_uuid.

Promote a release

Run apphost.release.promote with from_site_uuid set to the environment. It moves the release running on that environment one level up:

A preview never promotes straight to production.

• Nothing is rebuilt. The exact bundle is copied byte for byte and published through the normal release publish, so what you tested is what you ship. Two releases are the same release when their bundle hashes match.
• Only the source's active release can be promoted. A release that did not run there is refused, and so is one already pruned from the source.
• It is safe to retry: a promotion whose bundle is already the target's active release publishes nothing.
• To go back, use apphost.release.rollback on the target site.

Turn one off

Run apphost.environment.disable with the environment's own site_uuid. It refuses a production site. It:

1. retires the environment's database, keeping a final dump and freeing its place on the database host,
2. removes its Identity app,
3. deletes its child site, namespace and logins.

If a run fails part way, running it again finishes the job. Turning it off cannot be reversed: turning on again makes a new, empty environment, and the final dump is not restored for you.

What it costs

• An environment does not count as a site against your site quota, and its machine does not count against your machine quota. Environments have their own, separate machine limit.
• Hosting usage is not billed today, and that includes what an environment runs. See Pricing and limits.
• Keep any payment or provider connection used by staging in sandbox mode.

Also available

• App as code. apphost.blueprint.validate, apphost.blueprint.diff and apphost.blueprint.apply take a compiled app document, check it, show a plan and apply the plan whose hash you confirmed. This is early; the compiler is orkestia app compile.

Planned

Before environments, and still possible

You can still stage with a second Identity app and a second site, running the same build against both. That staging app has its own users, App Data instance and hostname, counts toward your site quota, and has no one-click promote: you publish the tested release again to the production site.