Instance Environment

An instance is a docker-compose project. Environment reaches its containers from three different places, owned by three different people — the product author, norsk-ctl itself, and you.

Source	Owner	For
parameters.yaml → ${NAME} in the product’s compose.yml	product author	Configuration the product designed: typed, defaulted, shown on the launch form
The generated runner-override.yml	norsk-ctl	Wiring the instance needs to work — service addresses, ports, URL prefixes
--overrides files	you	Deployment facts the product cannot know: cloud credentials, proxies, CA bundles

The third is what this page is about.

Why not just add a parameter?

A product-template parameter is the right home for a value the product shapes — folded into a JSON blob, tied to an allocated port, bounded, given a default and a form label. Adding one means editing the product and releasing it.

Cloud credentials, HTTP_PROXY and NODE_EXTRA_CA_CERTS are not that. The product has no opinion about them, cannot enumerate them, and there may be hundreds. Those are deployment facts, and they belong to whoever is deploying — so they are a launch option, not a product change.

Overrides vs sidecars

Both are compose files you write and pass at launch. They do different jobs:

• Sidecars add services that run — new containers with their own lifecycle, ports and health.
• Overrides adjust the environment of services that already exist. They add no containers.

An override may only set environment and env_file, on a service the stack already declares:

services:
  studio:
    environment:
      NODE_TLS_REJECT_UNAUTHORIZED: "0"
    env_file:
      - /etc/norsk/aws.env

norsk-ctl instance launch-template monday \
  --template new-nightly \
  --overrides /etc/norsk/tls.yml

--overrides is repeatable, and the paths are stored with the launch config, so instance relaunch keeps them.

Note

Anything other than environment / env_file — a command, a volumes, an extra service — is refused (see Validation). That restriction is what lets norsk-ctl check the file instead of handing it to compose unseen. If you need those, you want a sidecar.

Precedence

Lowest to highest. Nothing at any layer removes a key from a lower one — adding is the only operation, so an override can never accidentally strip the wiring an instance needs.

#	Layer	Notes
1	product compose.yml → env_file:	Within one service, env_file loses to environment
2	product compose.yml → environment:	The product’s own defaults
3	runner-override.yml	Generated by norsk-ctl, including the routing keys
4	--overrides → env_file:	Per service
5	--overrides → environment:	Beats its own env_file, same rule as layers 1–2

Multiple --overrides files apply in command-line order, later wins per key. Override files are merged after any sidecars, so your environment is final.

Parameters are a different mechanism

--param NAME=value does not appear in that table. Parameters are written to the instance’s .env file, which compose uses for interpolation across every file in the project. A parameter reaches a container only where some compose file names the key:

services:
  media:
    environment:
      BUCKET: "${S3_BUCKET}"   # interpolated from .env
      HTTP_PROXY               # bare name, also filled from .env

So --param is how you fill in a ${...} the product (or your sidecar) already declared. --overrides is how you set a variable nobody declared.

Validation

Every override file is checked before the launch does anything. A failure names the file, the service and the key:

Error	Cause
OVERRIDE_FILE_NOT_FOUND	The file does not exist, or could not be read
OVERRIDE_INVALID_YAML	Not YAML, or no top-level services: mapping
OVERRIDE_KEY_NOT_ALLOWED	A key other than environment / env_file under a service, or anything outside services:
OVERRIDE_TAG_NOT_ALLOWED	A !override or !reset tag — these remove values rather than adding them
OVERRIDE_SERVICE_UNKNOWN	No such service in this stack. The message lists the ones there are
ENV_KEY_RESERVED	A variable norsk-ctl owns (below)

Reserved variables

These are set by norsk-ctl and the instance’s proxy routing depends on them, so an override naming one refuses the launch rather than quietly breaking the instance:

STUDIO_NORSK_HOST, STUDIO_NORSK_INTERNAL_PREFIX, PORT, STUDIO_WORKING_DIRECTORY, PUBLIC_URL_PREFIX, STUDIO_URL_PREFIX.

LOG_LEVEL is deliberately not reserved. norsk-ctl sets it to info, and overriding it is a supported thing to do.

Where to keep the files

Anywhere the daemon can read them. Relative paths resolve against the instance’s working directory, absolute paths are taken as-is, and either way the resolved absolute path is what gets stored.

Caution

Keep override files outside the working directory — /etc/norsk/ or ~/.norsk-ctl/overrides/ are good homes. instance delete --purge deletes a working directory that norsk-ctl created, which would take your credentials file with it. Moving a file after launch also breaks instance relaunch, which looks for the stored absolute path.

See Set environment variables for worked examples.