DIT Digital Services Guidelines

Appearance

Separation of Environments ​

All applications must strictly separate environment-specific configuration from the software codebase. Under no circumstance may configuration values be hardcoded in the code (e.g., database connection strings, external service URLs, hostnames, IP addresses, secrets, or any environment-specific values).

All configuration must be injected through environment variables or external configuration providers so that each environment (development, staging, pre-production, production) can define its own values independently.

Any software that violates this rule will be classified as a script, not an application, and will not pass through normal CI/CD pipelines.
Such software may only be used with explicit written approval from both:

  • the Head of Digital Development, and
  • the Head of DevOps.

Documentation Requirements ​

Every project must document its configuration parameters in two required formats:

1. README.md (Mandatory) ​

Each codebase must include a README.md containing a table with the following columns:

ENV NAMEDESCRIPTIONDEFAULT VALUE(s)

This table must describe all environment variables expected by the system.

2. .env.example (Mandatory) ​

A file named .env.example must exist at the root of the repository.
This file must:

  • list every required environment variable,
  • include default or placeholder values when applicable, and
  • be directly convertible into a usable .env file simply by renaming it.

Any submission missing these documents is not accepted, and the software delivery is considered incomplete.

Security Constraint ​

The documentation, .env.example, and the codebase must never include secrets such as:

  • passwords
  • API keys
  • private keys
  • tokens
  • certificates
  • connection strings with credentials

All secrets must be stored only through the approved DevOps secret management system.

Naming Convention for Environment Variables ​

DIT follows a strict naming convention for environment variables to ensure clarity, grouping, and portability.

1. Grouping With Double Underscores (__) ​

Nested configuration keys must use double underscores:

bash
DB__CONNECTION=
DB__USERNAME=
DB__PASSWORD=
DB__DBNAME=

This corresponds to the following conceptual JSON structure:

json
{
  "DB": {
    "CONNECTION": "",
    "USERNAME": "",
    "PASSWORD": "",
    "DBNAME": ""
  }
}

Deeper nesting is permitted using the same pattern.

2. Arrays in Environment Variables ​

Array-type configuration values must use indexed keys:

bash
MONGODB__REPLICA_URL__0=
MONGODB__REPLICA_URL__1=
MONGODB__REPLICA_URL__2=

Equivalent JSON representation:

json
{
  "MONGODB": {
    "REPLICA_URL": ["", "", ""]
  }
}

By following these standards, all applications remain portable, secure, scalable, and fully compatible with DIT’s CI/CD, GitOps, and multi-environment deployment architecture.