Environments and variables

A web service, a static site or a hybrid site reads its settings from variables, such as a database address or an API key. Each deployment keeps its variables per environment, so production and previews can use different values, and env groups share one set of variables across several deployments. You set them on the deployment's Environment tab. A game server or a database keeps its settings as startup variables instead (Server settings).

A deployment has four environments:

production

What production releases read.

preview

What previews read (Turn on previews). A preview variable can also name a branch, and then only that branch's previews read it.

development

What you run on your own computer. coritan env pull writes these values to .env.local (The Coritan CLI).

all

Every environment, unless it has a value of its own.

When a key has several values, a release takes the first of these that exists: the value for its branch, then the value for its environment, then the all value, then the env groups linked to the deployment, in the order they were linked, and last the bindings.

Each variable also says where it is read: by the build, by the running instances, or by both. A variable the build reads, such as a public API address that a static site bakes into its pages, needs the build to run again before it changes anything.

1. Open the deployment and select the Environment tab.
2. Choose the environment, and for a preview variable the branch, if it is for one branch only.
3. Add the key and its value, and say whether the build, the running instances or both read it. A new variable is secret unless you say it is not.
4. Save. The deployment shows Your changes apply with the next release. Select Redeploy… to start one now. When a build-time variable changed, keep Build it again ticked.

A key uses upper-case letters, digits and underscores, starts with a letter or an underscore, and has up to 128 characters. A value can be up to 32 KiB. The platform sets some keys itself, so you cannot: PORT, TZ, STARTUP, SERVER_MEMORY, SERVER_IP, SERVER_PORT, and any key that starts with CORITAN_ or P_SERVER_. Your app reads the port to listen on from PORT.

Secret values are sealed when you save them, and nobody can read one back afterwards, you included. Only the last four characters of a value of eight or more are shown, to tell values apart. To change a secret, enter a new value.

To bring many variables at once, import a .env file into one environment (and branch) from the Environment tab. The file holds KEY=value lines, and may use export before a key, # comments, single quotes and double quotes, including values over several lines. It can be up to 256 KiB with up to 200 variables. If any line is wrong, nothing is saved and the error names the line, such as Line 3: not KEY=value.

Owners and admins can export the .env that a release of an environment would read, env groups included. Secret values are never exported: their keys are listed at the top of the file, so you can fill them in by hand.

An env group is a set of variables that several deployments of your account, or of one organization, read, such as the address of a shared database. Change a value in the group, and every linked deployment reads it from its next release.

• A group has its own production, preview, development and all values, without branches.
• A deployment can link up to 10 groups, and the group linked first wins when two hold the same key. The deployment's own variables win over every group.
• An account, or an organization, can have up to 50 groups.
• Deleting a group unlinks it, and its deployments lose its values with their next release.

An organization's groups can be linked only to that organization's deployments, and an account's only to its own.

A binding connects a deployment to another service you have with us and sets the variables that reach it, so no key or password is copied by hand:

Object Storage

A bucket, new or one you have, and an access key made for this deployment alone that reaches only that bucket, to read and write or only to read. It sets S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY and S3_REGION.

A database

One of your database deployments. It sets DATABASE_URL, DATABASE_HOST, DATABASE_PORT, DATABASE_USER, DATABASE_PASSWORD and DATABASE_NAME, or REDIS_URL, REDIS_HOST, REDIS_PORT and REDIS_PASSWORD for Redis. They are read from the database for each release, so a changed password reaches the next one.

SMTP Relay

A sending login made for this deployment. It sets SMTP_HOST, SMTP_PORT, SMTP_USER and SMTP_PASSWORD.

DNS

The CNAME and TXT records of each of the deployment's custom domains that is in one of your Coritan DNS zones (Add a custom domain).

DDoS Shield

The floating IPs of a game server or a database, put under one of your Shield profiles.

Bindings are made with the API (With the API). Their variables reach the next release, and any variable you set yourself wins over them. Removing a binding deletes the key, the login or the records it made, while a bucket and its files stay. A deployment can have up to 20 bindings, with one for DNS and one for Shield at most.

The next release reads the new values. The release that is serving keeps the values it started with until a new release replaces it.

The app still reads the old value

Variables apply with the next release. Select Redeploy…, and tick Build it again when the build reads the variable.

PORT is set by the platform and cannot be changed

The platform sets that key. Read it in your app instead of setting it, or rename your variable.

API_TOKEN needs a value

A new variable needs a value. An existing one keeps its saved value when you leave the value out.

Only a preview variable can be limited to one branch

Only the preview environment has values for one branch. Choose preview, or leave the branch out.

The production environment can have at most 200 variables

One environment (and branch) holds up to 200 variables and 256 KiB. Move shared values to an env group, or remove ones you no longer use. A deployment holds up to 1,000 values across all its environments and branches.

A deployment can link at most 10 env groups

Unlink a group, or merge two groups into one.

• Deploy from a git repository explains production and previews.
• The Coritan CLI pulls variables into .env.local with coritan env pull.

The routes are under /api/v1/client/deployments/{uuid} for your own deployment and /api/v1/orgs/{org_slug}/deployments/{uuid} for an organization's. Any member of an organization reads them; owners and admins change them. No answer carries a value once it is saved: value is always null, and hint holds the last four characters.

PUT /variables sets several variables of one environment and branch. A variable listed without value keeps its saved one, and "replace": true deletes the ones you did not list:

curl -X PUT https://api.coritan.com/api/v1/client/deployments/$DEPLOYMENT/variables \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"environment": "production", "vars": [{"key": "DATABASE_URL", "value": "postgres://shop@db.example.com/shop", "secret": true, "target": "runtime"}]}'

The answer lists what was created, updated and deleted, and redeploy_required. GET /variables lists every variable by environment and branch, PUT /variables/{key}?environment=preview&branch=feature-login sets one, and DELETE /variables/{key}?environment=production deletes one.

POST /variables/import takes the file's text in content, with environment, branch, secret, target and replace. GET /variables/export?environment=development answers the file in content and the secret keys it left out in withheld. GET /variables/resolved?environment=production names where each key a release would read comes from, without values.

Env groups are under /api/v1/client/env-groups for your account and /api/v1/orgs/{org_slug}/env-groups for an organization. POST / with {"name": "Shared database"} creates one, and PUT /{group}/variables sets its variables as on a deployment. POST /env-groups on a deployment, with {"group": "<uuid>"}, links a group, and DELETE /env-groups/{group} unlinks it.

GET /bindings/options on a deployment says which kinds of binding it can take and lists the resources you could name. POST /bindings makes one, with kind (object_storage, database, smtp, dns or shield) and, where the kind needs it, ref: a bucket, the database deployment's UUID, a sending domain or a Shield profile. env_prefix puts a prefix and _ before each key it sets, so two buckets can be bound side by side:

curl -X POST https://api.coritan.com/api/v1/client/deployments/$DEPLOYMENT/bindings \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "object_storage", "ref": "new", "env_prefix": "UPLOADS"}'

service_id picks the Object Storage or SMTP Relay service when you have several, "mode": "read" gives a bucket's key read access only, and "target": "both" lets builds read the variables too. GET /bindings lists the bindings with the keys each sets, never the values, and DELETE /bindings/{id} removes one. Two bindings that would set the same key answer 409 with variable_conflict.