Applications and environments #
On this page
An application groups your hosted code, size, hostnames, and environments. It starts with production, so each deploy goes live directly. Add development with create_environment to test deployed changes before moving them to production with promote.
Manage versions and environments covers rollback, halt, rename, and deletion.
Environments #
An application has one environment, production, or two, development and production. You turn development on with create_environment at any time, and off again with delete_environment, which needs browser approval. The manifest must not declare environments. A manifest that does is refused environment_unsupported.
create_environment and submit_manifest work in either order. The submission creates development's database and credentials, and turning development on creates neither. What submitting does says what a submission creates in each environment, and Test in development, then promote gives the steps.
Each environment has its own:
- database and role, on a development server or a production server;
- platform credential, the value a process presents to the platform;
- secret scope, so a development request never reads a production value;
- partition in every storage area;
- end-user realm, hostname, and version history.
Local runs use development data and credentials even without hosted development. Declared services provide a development database, secret scope, storage partitions, and the local log stream. Provisioning supplies development credentials to your computer; production credentials remain on the platform.
Without hosted development, local runs use the production realm for sign-in. There is no separate development realm or deployed development copy. An action on the hosted development environment of such an application, such as read_status, halt_environment, or a realm action, is refused 409 environment_not_created, naming create_environment. The actions on the development records still work, such as store_secret at the development scope, read_logs with local, and query_database with development, which reads the development database.
On one environment there is nothing to promote: promote is refused 409 environment_not_created, and roll_back puts an earlier production version back. Once development is turned on, a deploy targets development. deploy with environment: "production" is then refused 409 environment_unavailable, because production receives a version only through promote, which applies a version from the history with production's own settings and credentials.
What each application has of its own #
Applications are isolated from one another, including applications in the same account:
- Its image. Each environment runs from its own application's image. On its own container, the container's identity can pull only that application's image.
- Its platform credential. A call made with an environment's platform credential acts for that application alone.
- Its secrets. A secret stored for one application cannot be read by another, and no application can read the platform's own secrets.
- Its database. Each environment has its own PostgreSQL database and role on the shared server, and the role keeps that database apart from every other application's.
- Its files. Every storage area belongs to one application. A platform credential reaches its own application's areas and no other's, and no route reaches another account's files.
- Its external APIs. A declared upstream takes calls from its own application only, so another application's credential cannot call it with the stored key.
Your backend must also enforce access between its own users, including which files each user may read or write. See Store files.
Where each environment runs #
Each environment runs in one of two ways, and list_applications shows which in its grain member, pod or container:
- As one
podin a group on the hosting cell's shared cluster, where the cell has a group of the environment's kind open to new environments with room left. A development environment runs this way, and so does production on Shared 0.5 GB. - As its own
containerwhere the cell has no group of the environment's kind open to new environments, and always for production on Shared 1 GB. Where every open group of that kind is full, the deploy, promote, or size change is refused 409group_fullinstead.
Either way it runs the same image with the platform's settings, and a pod also sets HOME to /tmp and runs the process as user ID (uid) 1000. What the application runs under gives the image and the user on each grain. The grain_note of read_status says what each environment's grain means.
A development environment sleeps after thirty minutes without a request, whether it runs as a pod or a container. Production sleeps after the same interval when its sleep setting is on. An environment takes a changed idle interval at its next deploy, promote or restart_application. A sleeping environment starts on the next request, scheduled run or deploy. Development is charged at the Shared 0.5 GB rate (Size and usage).
Production keeps no idle copy where sleeping is on, or one where it is off, unless the account is paused. Each environment runs one replica, and two only while a deploy, promote or size change replaces it. Shared 1 GB production has 0.5 virtual CPU (vCPU) and 1 GiB of memory; Shared 0.5 GB has 0.25 vCPU and 0.5 GiB. A development container has 0.25 vCPU and 0.5 GiB, and a development pod takes its group's settings. How the sizes differ technically compares their compute.
Every deploy, promote, and redeploy injects the platform's settings into the environment's copy, with that environment's values. A deployed app's settings lists each one.
Where an application runs during development #
While you build, the application runs in up to three places, and each works differently:
- A local process on your machine, the local run, runs under the development records, on one environment or two.
- Where development is turned on, the deployed development copy runs on the platform after a deploy to it. On one environment there is no such copy, and every deploy reaches production.
- The application's tests run against the test doubles that the backend packages ship, with nothing provisioned.
| Local process | Deployed development copy | Tests over the doubles | |
|---|---|---|---|
| Environment | development, under the environment file the provision line writes | development, under the settings the deploy injects | none: a double reaches nothing outside the process |
| Database | the development database, from any address under the developer network rule | the development database | a PostgreSQL engine in the test process, with your migration files applied when it is created |
| Platform credential | the development credential | the development credential | none |
| Storage partition | the development partition of each area | the development partition of each area | the storage double, in memory |
| Secrets | the development scope's values | the development scope's values | none |
| Log stream | local |
development |
the logging double's entries |
| Hostname and router | no hosted hostname; the command listens in front with --sign-in, or with client/ and a numeric port; otherwise the application listens directly |
the development hostname, behind the serving router | none |
| Runtime harness | not loaded | loaded by the platform's image | not loaded |
| Realm keys and scheduled runs | none | injected and run by the platform where the manifest declares them | the account double signs under a key pair of its own; the schedule double starts a run |
A separate option is to run against your own PostgreSQL on your computer, within the limits that section gives.
With development turned on, the local process and the deployed copy share the development environment's data and credential. They use the same development database, the same partition of each storage area, and the same secrets. The deployed copy keeps the credential value it started with. The provision line mints a new value, and its last step restarts the deployed copy on it.
Only the deployed copy runs behind the platform's router and runtime harness. It serves under the development hostname, applies the manifest's audience, receives the realm's public keys, and receives scheduled runs.
On your machine, turnzero run --sign-in relays /__account/ requests to the application's hosted hostname. With sign-in, or with client/ and a numeric port, the command listens in front of the application and gives it a free port as PORT.
Without that listener, the application uses the port its code chooses, PORT where you set it. It verifies an end-user session through the platform's verification route, because the environment file has no realm keys. Know what a local run reaches gives the rest.
Tests use the packages' test doubles without an account, network connection, or environment file (Test your application locally). A local application that calls real platform services needs credentials, supplied through its environment or an environment file.
The platform never creates the schema. The application creates its tables from its migration files when it starts, and the same files are applied to every database it uses, as Add a database describes.
Environment states #
In list_applications and read_status, an environment's state is one of six values. The state is the first of these that applies:
deleting: the application or the environment is being deleted.halted: you or the platform halted the environment.deploying: a deploy, a promote, or a platform redeploy of the environment is in progress.deployed: a version is serving.failed: no version is serving, and the environment's latest deploy or promote failed.never_deployed: none of the above.
list_applications gives each application's environments, one object per environment, development first where it has one. Beside each state, read_status gives compute_state, the hosting provider's own word for the environment's compute, null until the compute exists. The response's top-level members describe one environment: the one the call names in environment, or production where your call leaves it out. The top-level environment member says which environment that is. The read_status and list_applications reference pages list every member.
The development hostname #
You choose the application's name in create_application. The platform adds a unique suffix at creation and returns the result as label. You cannot choose that suffix or know the exact hostname before the call succeeds. Production uses <label>.ai.host; development uses <label>-dev.ai.host. Use the returned label and read the hostname from the platform's answers. The suffix contains no hyphen, so the two forms cannot collide. A hostname retired by deletion or renaming is never reused.
Your applications use .ai.host, with <label>-dev.ai.host for a development environment; .dev.ai.host belongs to tests of the platform itself.
Any application can attach one custom domain to production, a monthly item (Attach your own domain). From when the domain first serves until you detach it, a failed state included, the production copy's APP_PUBLIC_HOST is that domain (A deployed app's settings). The managed production hostname keeps serving the application, but a sign-in started on it does not complete. The development hostname is unchanged.
Read the application's hostname from list_applications, create_environment, deploy, or promote rather than composing it.
The router serves the development hostname from the moment the application is created. Before the first development deploy, it returns 404 not_deployed on every path except /__account/. On an application with one environment, that path returns 404 too, naming create_environment, because there is no development realm. Once development is turned on, it serves the development realm's sign-in pages where the manifest declares the accounts kind. So an end user can sign in to the development realm before the environment has a running copy.
Every response on the development hostname includes the header X-Robots-Tag: noindex, nofollow, and the platform publishes no list of development hostnames. The development environment serves your build under the manifest's audience. With public, anyone who knows the hostname can reach the application. Your backend must still control which data each visitor can read. Manage end users explains what that means for test data.
The version history #
Every deploy, promote, restart, and platform redeploy writes one row of the application's version history, which list_versions returns newest first. The version history says what each row's members mean, and the list_versions reference lists them.
A row's kind says what wrote it. It is "deploy" for a deploy's row and "promote" for a promote's or rollback's row. It is "restart" for a row written when restart_application, a rename, or the platform re-created the running copy under current settings, with the same version and image. A restart keeps the application's version and image and applies current platform settings.
A deploy takes the next number of one sequence per application, shared by development and production. A promote row has the number and the harness of the deploy it promotes, because it applies that deploy's image. So a version gets the current harness only through a new deploy. A "restart" row has the number and harness of the row it re-created, and once it finishes it is its environment's serving row, which a promote can take. The same number can therefore appear on a development "deploy" row, a production "promote" row, and a "restart" row of either environment.
On one environment, a deploy's row is production's own "deploy" row. An environment's serving version is its newest deployed row. Rows that delete_environment retired are not returned and never serve.
The halted state #
A halted environment keeps its deployed version, its data, its credentials, and its schedule declarations, but serves nothing. Its hostname returns 503 environment_halted on every path, including the sign-in path /__account/. Its schedules do not run, and each schedule's next_due stays where it was.
What a halt stops:
- A halt of production stops production's compute, a container or a pod.
- Development already sleeps when idle. Its halt prevents a request or scheduled run from starting it.
A halt that stops a pod returns at once, and the pod stops within about 11 seconds. The platform waits that long so every router already returns 503 environment_halted when the pod stops. During some platform updates, a router can hold the pod's address longer. For up to about 19 seconds after the pod stops, a request can then reach it and wait without an answer. If the stop is cut short, the next daily check stops the pod.
Only an environment with a deployed version can be halted, so halt_environment refuses one with none, 409 environment_never_deployed. A deploy to a halted development environment ends its halt after its checks, and so does halt_environment with resume: true. Only halt_environment with resume: true ends a production halt, and until then a deploy or a promote to production is refused 409 target_environment_halted. A resume restarts every schedule of the environment from the moment of the resume, and no missed run is recorded.
Halts the platform makes #
Where development is turned on, the platform halts the development environment itself, with by set to platform, once its halt interval has passed. The interval runs from the later of two moments: the end of the deploy that made the environment's serving version, and the environment's last resume. So a successful deploy or a halt_environment with resume: true starts the interval again, and a deploy that ends failed does not.
The interval is seven days for every application, and platform staff can change it without a release. A daily check applies the rule, so the halt happens within one day after the interval ends. This automatic halt applies only to development.
The platform also re-creates an environment's running copy after it changes its router mark. This writes a restart row and one event in your log stream, and leaves the version and everything else of yours unchanged. A halted environment is re-created after its resume.
Deleting, clearing, and renaming #
Each of the four actions below needs a person's approval in a browser, as The pending action describes.
Deleting an application #
delete_application removes every environment and everything bound to the application, as Delete the application lists, with what the deletion keeps.
Deleting the development environment #
delete_environment removes the development environment alone and turns development off, so the next deploy goes to production. It refuses production with invalid_request, because production is deleted only with its application. A development environment that was never deployed can be deleted too, which removes whatever it contains, such as its realm and its secrets.
On an application with one environment there is no development environment to turn off, but your local runs keep records there. They are the development database, its platform credential, and the secrets, files, and logs you stored for them. The call is accepted when:
- a development database exists, or its setup stopped before completion, for example when
submit_manifestrefuses withserver_unavailableorstore_secretwithreplace: truerefuses withdatabase_provisioning_failed; - an earlier deletion of these records stopped partway; the same call completes it;
It then removes those records, leaves production untouched, and the application keeps one environment. In any other case the call is refused 409 environment_not_created, before anything is asked of you.
The deletion removes the development environment's:
- container;
- database and role, with their credential;
- realm, with its passkeys and invitations;
- issue-tracking space, where the application kept one for each environment, deleted at the issue service with every record in it;
- binding to an issue space of your account's own, which keeps its records;
- application-scoped secrets and platform credential;
- partition of every bound storage area;
- log entries and counter totals;
- version rows, which
list_versionsno longer returns and whose numbers are never used again.
The application, its production environment, its storage areas, and its declarations remain. The secret store keeps the deleted secret values for ninety days before it purges them, and the usage meters keep their rows.
Afterwards the application has one environment, production. The next submit_manifest creates a new development database and role and a new development platform credential for local runs, and returns the development credentials once, as a first submission does. The secrets and files you stored for development are not brought back; store them again if you still need them. An application that kept an issue-tracking space for each environment also gets a new empty development space. It creates no development realm.
The development schedule declarations remain, and the schedules run again after the next development deploy. Development turned on again has a new realm where the manifest declares the accounts kind, and no database until the next submission, as Delete the development environment describes.
Clearing the development database #
clear_development_database empties the development database and keeps everything else. It drops the database with every table and row in it, then creates it again empty under the same role. The role keeps its password, so the development credential and the connection string in .env stay valid.
The tables come back when the application's migrations run again, at the next local start or the deployed copy's next start, as Add a database describes. The action refuses production with invalid_request, and an application with no development database with not_found.
Renaming an application #
rename_application takes the application identifier and a new name. The name has at most forty characters: a lowercase letter, then lowercase letters, digits, or hyphens. It must differ from the current name, or the call is refused invalid_request. It must also differ from the name of every other live application in the account, or the call is refused name_taken.
A rename permanently retires both of the application's hostnames, production's and development's, and its passkeys and invitation links stop working with them. Rename the application lists every effect.
The rename retires exactly the hostname the approved description named. If another rename or a deletion changed the application after the approval, the outcome is renamed: false with the reason, and nothing changes. Read the application with read_status, and request the rename again if it still applies.
Backend versions and snapshots #
The application applies its own migration files when it starts, and neither a deploy nor a promote takes a snapshot. roll_back promotes an earlier version, restoring its code, setting bindings and plain values, and changes no data. Across a data-model change, you decide how the data is migrated or restored. Do not assume the platform has taken a snapshot or can reverse a schema change.
The catalog's two actions for this, apply_migration and restore_snapshot, are not provided by the running platform: the tool list leaves them out, and a call to either over the management route returns 501 not_yet_provisioned.
Related #
- Deploy from your computer creates an application and deploys it to production.
- Test in development, then promote turns on a development environment to promote from.
- Manage versions and environments rolls back, restarts, halts, renames, and deletes.
- Run your app on your computer runs the application on your machine under the development records.
- Test your application locally runs the application's tests against the backend packages' test doubles.
- A deployed app's settings lists the settings each environment's copy reads.
- What happens without asking explains the browser approval that
delete_application,delete_environment,clear_development_database, andrename_applicationneed. - Size and usage explains
set_app_sizeandread_usage. - Actions lists every management action a customer can call, with its inputs and outputs.