Environment Variables

Vivarium generates two categories of env files:

Compose env file -- written to ~/.local/share/vivarium/<name>/.env. Used by Docker Compose for variable interpolation. Not intended for your application code.
Package env files -- written to paths defined by envFile in each package config. These are the .env files your application actually reads.

Package env files are only written for packages that have envFile set in their config.

Only packages named backend and frontend receive convention-based environment variables. Any other package name (e.g., worker) only gets the vars you explicitly define in that package's env field.

Compose Env File

These variables are written to ~/.local/share/vivarium/<name>/.env and used exclusively by Docker Compose for container configuration and port binding. They are not written to your project directories.

Variable	Condition	Description
`COMPOSE_PROJECT_NAME`	Always	Unique project name for Docker Compose namespace
`POSTGRES_USER`	`postgres` configured	Database user
`POSTGRES_PASSWORD`	`postgres` configured	Database password
`POSTGRES_DB`	`postgres` configured	Database name
`POSTGRES_PORT`	`postgres` configured	Host port for Postgres
`REDIS_PORT`	`redis` configured	Host port for Redis
`S3_ACCESS_KEY`	`s3` configured	MinIO access key
`S3_SECRET_KEY`	`s3` configured	MinIO secret key
`S3_PORT`	`s3` configured	Host port for MinIO API
`S3_CONSOLE_PORT`	`s3` configured	Host port for MinIO console

Backend Package Env File

Generated when the package key is backend. Written to the path defined by envFile.

Always present

Variable	Example	Description
`API_LISTEN_PORT`	`4001`	Port the backend server should bind to
`API_URL`	`http://localhost:4001`	Full URL of the backend API

With `frontend` package present

Variable	Example	Description
`FRONTEND_URL`	`http://localhost:4000`	URL of the frontend package

With `postgres` configured

Variable	Example	Description
`DATABASE_URL`	`postgresql://app:secret@localhost:5432/myapp`	Full Postgres connection string

With `redis` configured

Variable	Example	Description
`REDIS_ENABLED`	`true`	Signals that Redis is available
`REDIS_URL`	`redis://localhost:6380`	Full Redis connection URL

With `s3` configured

Variable	Example	Description
`AWS_S3_REGION`	`us-east-1`	Region (always `us-east-1` for MinIO compatibility)
`AWS_S3_ACCESS_KEY_ID`	`minioadmin`	S3 access key
`AWS_S3_SECRET_ACCESS_KEY`	`minioadmin`	S3 secret key
`AWS_S3_ENDPOINT`	`http://localhost:9000`	MinIO API endpoint
`AWS_S3_BUCKET_NAME`	`assets`	First bucket name from config
`AWS_S3_TEMP_BUCKET_NAME`	`temp`	Second bucket name (only if two or more buckets are configured)

Frontend Package Env File

Generated when the package key is frontend. Written to the path defined by envFile.

The variable prefix depends on the framework field in the package config.

Framework Prefix

`framework` value	Prefix
`nextjs` (default)	`NEXT_PUBLIC_`
`vite`	`VITE_`

In the tables below, {PREFIX} refers to whichever prefix applies.

Always present

Variable	Example	Description
`PORT`	`4000`	Port the frontend server should bind to
`{PREFIX}FRONTEND_URL`	`http://localhost:4000`	Full URL of the frontend

With `backend` package present

Variable	Example	Description
`{PREFIX}API_URL`	`http://localhost:4001`	URL of the backend API

With `s3` configured

Variable	Example	Description
`{PREFIX}ASSET_SRC`	`http://localhost:9000`	MinIO API endpoint, for serving assets

Custom Env Overrides

The env field in any PackageConfig lets you add or override variables:

{
  "packages": {
    "backend": {
      "envFile": "backend/.env",
      "env": {
        "LOG_LEVEL": "debug",
        "DATABASE_URL": "postgresql://other:pass@localhost:5432/override"
      }
    }
  }
}

Custom env values are merged last via Object.assign. They always win over convention-generated variables. In the example above, the custom DATABASE_URL replaces the one Vivarium would normally derive from the postgres service config.

Any key-value pair you add is included as-is in the output file.

Override Precedence

convention-generated vars  <  custom env overrides

Convention vars are computed first. Custom env entries are applied on top via Object.assign. There is no further merging -- it is a flat override.

On this page