From d7697e24b3a6ca2a5f508ff162e226b44cffd33a Mon Sep 17 00:00:00 2001
From: siujamo <jamo.siu@gmail.com>
Date: Thu, 30 Jul 2026 13:58:38 +0800
Subject: [PATCH] docs(mssql): add comments and .env.example

- Add file header with usage instructions and Developer edition licence notice
- Document all environment variables with inline comments
- Reorganise MSSQL_PID edition list into Free / Development / Paid categories
- Add .env.example with documented defaults for SA password and edition
---
 compose/sql-server-2025/.env.example        | 23 ++++++++++
 compose/sql-server-2025/docker-compose.yaml | 49 ++++++++++++++++-----
 2 files changed, 60 insertions(+), 12 deletions(-)
 create mode 100644 compose/sql-server-2025/.env.example

diff --git a/compose/sql-server-2025/.env.example b/compose/sql-server-2025/.env.example
new file mode 100644
index 0000000..fad8bf1
--- /dev/null
+++ b/compose/sql-server-2025/.env.example
@@ -0,0 +1,23 @@
+# Microsoft SQL Server 2025 — environment variables
+# Copy this file to .env and adjust values for your environment.
+
+# SA (system administrator) password.
+# Must be at least 8 characters and include uppercase, lowercase, digits,
+# and/or special characters.
+# The default is for local development only — always change for production.
+MSSQL_SA_PASSWORD='1q2w3e!Q@W#E'
+
+# Product edition (default: EnterpriseDeveloper).
+# IMPORTANT: Developer editions are for local development and testing only.
+# They may NOT be used in production environments.
+# Free:
+#   Evaluation          — full feature set, production use allowed, 180-day limit
+#   Express             — production use allowed, resource-limited (CPU/memory/size)
+# Development only (no production use rights):
+#   EnterpriseDeveloper — default, full feature set
+#   StandardDeveloper
+# Paid:
+#   Standard
+#   Enterprise          — CPU core utilisation restricted to 20 physical / 40 hyperthreaded
+#   Enterprise Core     — CPU core utilisation up to operating system maximum
+MSSQL_PID=EnterpriseDeveloper
diff --git a/compose/sql-server-2025/docker-compose.yaml b/compose/sql-server-2025/docker-compose.yaml
index 80d9958..e4b7942 100644
--- a/compose/sql-server-2025/docker-compose.yaml
+++ b/compose/sql-server-2025/docker-compose.yaml
@@ -1,23 +1,48 @@
+# Docker Compose file for Microsoft SQL Server 2025
+#
+# Usage:
+#   docker compose up -d
+#
+# IMPORTANT: The default edition (EnterpriseDeveloper) is for local development
+# and testing only. It may NOT be used in production environments.
+# See https://learn.microsoft.com/en-us/sql/sql-server/editions-and-components-of-sql-server
+#
+# Environment variables (see .env.example for details):
+#   MSSQL_SA_PASSWORD  - SA (system administrator) password (default: 1q2w3e!Q@W#E)
+#   MSSQL_PID          - Product edition (default: EnterpriseDeveloper)
+
 services:
   mssql:
+    # For available image tags, see https://mcr.microsoft.com/en-us/product/mssql/server/about
     image: mcr.microsoft.com/mssql/server:2025-latest
     container_name: mssql
     environment:
+      # Accept the End-User License Agreement (EULA).
+      # Setting ACCEPT_EULA=Y confirms acceptance:
+      # https://hub.docker.com/_/microsoft-mssql-server
       - ACCEPT_EULA=Y
+      # SA (system administrator) password.
+      # Must meet complexity requirements: at least 8 characters, with uppercase,
+      # lowercase, digits, and/or special characters.
+      # Default value is for local development only — change for production.
       - MSSQL_SA_PASSWORD=${MSSQL_SA_PASSWORD:-1q2w3e!Q@W#E}
-      # Product ID or edition that the container runs with.
+      # Product ID (edition) that the container runs with.
       # Acceptable values:
-      # - Evaluation (free, no production use rights, 180-day limit)
-      # - EnterpriseDeveloper (free, no production use rights)
-      # - StandardDeveloper (free, no production use rights)
-      # - Express (free)
-      # - Standard (PAID)
-      # - Enterprise (PAID) - CPU core utilization restricted to 20 physical/40 hyperthreaded
-      # - Enterprise Core (PAID) - CPU core utilization up to Operating System Maximum
-      # - I bought a license through a retail sales channel and have a product key to enter
-      # - Standard (Billed through Azure) - Use pay-as-you-go billing through Azure
-      # - Enterprise Core (Billed through Azure) - Use pay-as-you-go billing through Azure
+      #   Free:
+      #     - Evaluation          — full feature set, production use allowed, 180-day limit
+      #     - Express             — production use allowed, resource-limited (CPU/memory/size)
+      #   Development only (no production use rights):
+      #     - EnterpriseDeveloper — default, full feature set
+      #     - StandardDeveloper
+      #   Paid:
+      #     - Standard
+      #     - Enterprise          — CPU core utilisation restricted to 20 physical / 40 hyperthreaded
+      #     - Enterprise Core     — CPU core utilisation up to operating system maximum
+      #   Retail / Azure billed:
+      #     - A product key (retail sales channel)
+      #     - Standard (Billed through Azure)
+      #     - Enterprise Core (Billed through Azure)
       - MSSQL_PID=${MSSQL_PID:-EnterpriseDeveloper}
     ports:
+      # Map host port 1433 to container port 1433 (SQL Server default).
       - "1433:1433"
-    
\ No newline at end of file