# Environment file (.env)

Source: https://www.storeframe.io/docs/infrastructure/architecture/env-file

The .env file that holds each environment's configuration — what it contains, where it lives, and how to work with it safely.

Every customer VM has a single `.env` file at the root of its project directory. This file is the source of truth for that VM's configuration. The platform reads it before every operation to know the current state of the environment.

The file lives at:

```
/var/www/<subdomain>.<domain>/.env
```

For example: `/var/www/example.storeframe.store/.env`

The file also holds credentials generated at provisioning. Treat it as secret: don't share it or paste it into a support ticket.

## Format

`.env` is one flat file with one key per line, written as `KEY='value'`. Always wrap the value in single quotes.

Keys follow the pattern `SECTION__OPTION` in upper case. The double underscore separates the group from the setting, so `NGINX__WAF_ENABLED` is the `WAF_ENABLED` setting of the nginx group.

## Keys

### General

Platform identity and infrastructure choices for this environment.

```bash
GENERAL__PLATFORM_NAME='magento'
GENERAL__PLATFORM_SEARCHENGINE='opensearch'
```

`GENERAL__PLATFORM_NAME` is always `magento` for current customer VMs. `GENERAL__PLATFORM_SEARCHENGINE` can be `opensearch` or `elasticsearch`, depending on which search container was provisioned.

### Containers

Docker image versions for every service in the stack. These are pinned at provisioning time based on the Magento release profile and only change when you explicitly upgrade a service.

```bash
CONTAINERS__PHP_VERSION='8.4-frankenphp'
CONTAINERS__MARIADB_VERSION='10.4'
CONTAINERS__REDIS_VERSION='7.0'
CONTAINERS__OPENSEARCH_VERSION='2'
CONTAINERS__VARNISH_VERSION='7.1'
CONTAINERS__RABBITMQ_VERSION='3.9'
CONTAINERS__NGINX_VERSION='mainline'
CONTAINERS__NODEJS_VERSION='19'
CONTAINERS__COMPOSER_VERSION='2'
```

### MariaDB

Database settings used by the MariaDB container and by Magento to connect to the database.

```bash
MAGENTO_MARIADB__MARIADB_HOST='mariadb'
MAGENTO_MARIADB__MARIADB_PORT='3306'
MAGENTO_MARIADB__MARIADB_NAME='magento'
MAGENTO_MARIADB__INNODB_BUFFER_POOL_SIZE='12G'
```

`MAGENTO_MARIADB__INNODB_BUFFER_POOL_SIZE` is a tunable that controls MariaDB memory allocation. Increasing it can improve query performance on stores with large catalogs, but the value must fit within the VM's available RAM.

Each database section also carries a `__DATABASE` key naming its engine, for example `MAGENTO_MARIADB__DATABASE='mariadb'`.

### Redis

```bash
REDIS__REDIS_HOST='redis'
REDIS__REDIS_PORT='6379'
REDIS__REDIS_REPLICAS='1'
```

`REDIS__REDIS_REPLICAS` controls how many Redis containers run. The default is 1. With 3, the cache, full-page cache and sessions each get their own container. Changing it re-installs Redis, which clears sessions and logs shoppers out, so do it outside busy hours.

### PHP

PHP configuration. The runtime (FrankenPHP or PHP-FPM) is set by the suffix of `CONTAINERS__PHP_VERSION`.

```bash
PHP__PHP_MEMORY_LIMIT='2048'
PHP__PHP_OPCACHE_MEMORY='2048'
```

`PHP__PHP_MEMORY_LIMIT` and `PHP__PHP_OPCACHE_MEMORY` are in megabytes, without a unit suffix.

### Nginx

Edge security and proxy configuration.

```bash
NGINX__BLOCKLIST_ENABLED='yes'
NGINX__RATELIMIT_ENABLED='yes'
NGINX__NGINX_WHITELIST='203.0.113.10'
NGINX__NGINX_BLACKLIST=''
NGINX__POW_ENABLED='yes'
NGINX__POW_DIFFICULTY='1'
NGINX__POW_SESSION_EXPIRE='14400'
NGINX__RATELIMIT_RPS='150'
NGINX__RATELIMIT_BURST='900'
NGINX__WAF_ENABLED='yes'
NGINX__WAF_MODE='ban'
NGINX__CONNLIMIT_MAX='300'
```

`NGINX__NGINX_WHITELIST` accepts comma-separated IPs or CIDR ranges that bypass rate limiting and proof-of-work challenges. Use this for monitoring services or trusted partner IPs.

Leave any other generated `NGINX__` values as they are. The platform manages them.

### OpenSearch, Varnish, RabbitMQ

Each of these services has its own group of keys. Memory limits and resource settings are set from the release profile, and you can edit individual values such as `OPENSEARCH__OPENSEARCH_MEMORY` or `VARNISH__VARNISH_MEMORY` for advanced tuning.

## How it is generated

`.env` is written once during initial provisioning from the environment's release profile. Later platform runs keep the values you changed; a few derived values, such as the Varnish backend address, are recalculated by the platform.

## Safe edits

You can edit `.env` directly via SSH for advanced tuning:

```bash
ssh app@<subdomain>.storeframe.store -p2409
sudo nano /var/www/<subdomain>.<domain>/.env
```

After editing, open the environment's **Containers** tab in the Hub and choose **⋯ → Install** on the container you changed (for example nginx for `NGINX__` keys, PHP for `PHP__` keys). Install re-reads `.env` and re-applies that container's configuration. Restarting a container does not apply changes. The platform's regular maintenance runs also re-apply the file, so any edit you leave in it will take effect on the next run even if you skip this step.

Re-installing Redis clears its data, which logs shoppers out. Do it outside busy hours.

Keep the single quotes around every value.

Don't put comments on the same line as a value. In `NGINX__WAF_ENABLED='yes' # on` the trailing `# on` becomes part of the value, which the platform does not treat as `yes`, so the install can fail or the setting switches off. Put comments on their own line.

Do not delete keys the platform generated; a missing key will cause configuration to fail. Adding new keys is safe.

Most configuration changes should go through the Hub UI, which handles validation and re-applies configuration in the correct order. Direct edits to `.env` bypass that safety layer.
