Merge pull request #98 from githubnext/copilot/add-execution-environment-validation

Add execution environment validation for containerized MCP Gateway

Author: lpcox

Dockerfile

@@ -25,12 +25,14 @@ WORKDIR /app
 # Copy binary from builder
 COPY --from=builder /app/awmg .
 
-# Copy run.sh script
+# Copy run scripts
 COPY run.sh .
-RUN chmod +x run.sh
+COPY run_containerized.sh .
+RUN chmod +x run.sh run_containerized.sh
 
 # Expose default HTTP port
 EXPOSE 8000
 
-# Use run.sh as entrypoint
-ENTRYPOINT ["/app/run.sh"]
+# Use run_containerized.sh as entrypoint for container deployments
+# This script requires stdin (-i flag) for JSON configuration
+ENTRYPOINT ["/app/run_containerized.sh"]

README.md

@@ -31,15 +31,41 @@ For detailed setup instructions, building from source, and local development, se
    docker pull ghcr.io/githubnext/gh-aw-mcpg:latest
    ```
 
-2. **Run the container**:
+2. **Create a configuration file** (`config.json`):
+   ```json
+   {
+     "mcpServers": {
+       "github": {
+         "type": "stdio",
+         "container": "ghcr.io/github/github-mcp-server:latest",
+         "env": {
+           "GITHUB_PERSONAL_ACCESS_TOKEN": ""
+         }
+       }
+     }
+   }
+   ```
+
+3. **Run the container**:
    ```bash
-   docker run --rm -v $(pwd)/.env:/app/.env \
+   docker run --rm -i \
+     -e MCP_GATEWAY_PORT=8000 \
+     -e MCP_GATEWAY_DOMAIN=localhost \
+     -e MCP_GATEWAY_API_KEY=your-secret-key \
      -v /var/run/docker.sock:/var/run/docker.sock \
+     -v /path/to/logs:/tmp/gh-aw/sandbox/mcp \
      -p 8000:8000 \
-     ghcr.io/githubnext/gh-aw-mcpg:latest
+     ghcr.io/githubnext/gh-aw-mcpg:latest < config.json
    ```
 
-MCPG will start in routed mode on `http://127.0.0.1:8000`, proxying MCP requests to your configured backend servers.
+**Required flags:**
+- `-i`: Enables stdin for passing JSON configuration
+- `-e MCP_GATEWAY_*`: Required environment variables
+- `-v /var/run/docker.sock`: Required for spawning backend MCP servers
+- `-v /path/to/logs:/tmp/gh-aw/sandbox/mcp`: Mount for persistent gateway logs
+- `-p 8000:8000`: Port mapping must match `MCP_GATEWAY_PORT`
+
+MCPG will start in routed mode on `http://0.0.0.0:8000` (using `MCP_GATEWAY_PORT`), proxying MCP requests to your configured backend servers.
 
 ## Configuration
 
@@ -164,12 +190,107 @@ Usage:
 Flags:
   -c, --config string   Path to config file (default "config.toml")
       --config-stdin    Read MCP server configuration from stdin (JSON format). When enabled, overrides --config
+      --enable-difc     Enable DIFC enforcement and session requirement (requires sys___init call before tool access)
       --env string      Path to .env file to load environment variables
   -h, --help            help for awmg
   -l, --listen string   HTTP server listen address (default "127.0.0.1:3000")
       --log-dir string  Directory for log files (falls back to stdout if directory cannot be created) (default "/tmp/gh-aw/sandbox/mcp")
       --routed          Run in routed mode (each backend at /mcp/<server>)
       --unified         Run in unified mode (all backends at /mcp)
+      --validate-env    Validate execution environment (Docker, env vars) before starting
+```
+
+## Environment Variables
+
+The following environment variables are used by the MCP Gateway:
+
+### Required for Production (Containerized Mode)
+
+When running in a container (`run_containerized.sh`), these variables **must** be set:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `MCP_GATEWAY_PORT` | The port the gateway listens on (used for `--listen` address) | `8080` |
+| `MCP_GATEWAY_DOMAIN` | The domain name for the gateway | `localhost` |
+| `MCP_GATEWAY_API_KEY` | API key for authentication | `your-secret-key` |
+
+### Optional (Non-Containerized Mode)
+
+When running locally (`run.sh`), these variables are optional (warnings shown if missing):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_GATEWAY_PORT` | Gateway listening port | `8000` |
+| `MCP_GATEWAY_DOMAIN` | Gateway domain | `localhost` |
+| `MCP_GATEWAY_API_KEY` | API authentication key | (disabled) |
+| `MCP_GATEWAY_HOST` | Gateway bind address | `0.0.0.0` |
+| `MCP_GATEWAY_MODE` | Gateway mode | `--routed` |
+| `MCP_GATEWAY_LOG_DIR` | Log file directory | `/tmp/gh-aw/sandbox/mcp` |
+
+### Docker Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DOCKER_HOST` | Docker daemon socket path | `/var/run/docker.sock` |
+| `DOCKER_API_VERSION` | Docker API version | Auto-detected (1.43 for arm64, 1.44 for amd64) |
+
+## Containerized Mode
+
+### Running in Docker
+
+For production deployments in Docker containers, use `run_containerized.sh` which:
+
+1. **Validates the container environment** before starting
+2. **Requires** all essential environment variables
+3. **Requires** stdin input (`-i` flag) for JSON configuration
+4. **Validates** Docker socket accessibility
+5. **Validates** port mapping configuration
+
+```bash
+# Correct way to run the gateway in a container:
+docker run -i \
+  -e MCP_GATEWAY_PORT=8080 \
+  -e MCP_GATEWAY_DOMAIN=localhost \
+  -e MCP_GATEWAY_API_KEY=your-key \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -p 8080:8080 \
+  ghcr.io/githubnext/gh-aw-mcpg:latest < config.json
+```
+
+**Important flags:**
+- `-i`: Required for passing configuration via stdin
+- `-v /var/run/docker.sock:/var/run/docker.sock`: Required for spawning backend MCP servers
+- `-p <host>:<container>`: Port mapping must match `MCP_GATEWAY_PORT`
+
+### Validation Checks
+
+The containerized startup script performs these validations:
+
+| Check | Description | Action on Failure |
+|-------|-------------|-------------------|
+| Docker Socket | Verifies Docker daemon is accessible | Exit with error |
+| Environment Variables | Checks required env vars are set | Exit with error |
+| Port Mapping | Verifies container port is mapped to host | Exit with error |
+| Stdin Interactive | Ensures `-i` flag was used | Exit with error |
+| Log Directory Mount | Verifies log directory is mounted to host | Warning (logs won't persist) |
+
+### Non-Containerized Mode
+
+For local development, use `run.sh` which:
+
+1. **Warns** about missing environment variables (but continues)
+2. **Provides** default configuration if no config file specified
+3. **Auto-detects** containerized environments and redirects to `run_containerized.sh`
+
+```bash
+# Run locally with defaults:
+./run.sh
+
+# Run with custom config:
+CONFIG=my-config.toml ./run.sh
+
+# Run with environment variables:
+MCP_GATEWAY_PORT=3000 ./run.sh
 ```
 
 ## Logging
@@ -178,12 +299,17 @@ MCPG provides comprehensive logging of all gateway operations to help diagnose i
 
 ### Log File Location
 
-By default, logs are written to `/tmp/gh-aw/sandbox/mcp/mcp-gateway.log`. This location can be configured using the `--log-dir` flag:
+By default, logs are written to `/tmp/gh-aw/sandbox/mcp/mcp-gateway.log`. This location can be configured using the `--log-dir` flag or `MCP_GATEWAY_LOG_DIR` environment variable:
 
 ```bash
 ./awmg --config config.toml --log-dir /var/log/mcp-gateway
 ```
 
+**Important for containerized mode:** Mount the log directory to persist logs outside the container:
+```bash
+docker run -v /path/on/host:/tmp/gh-aw/sandbox/mcp ...
+```
+
 If the log directory cannot be created or accessed, MCPG automatically falls back to logging to stdout.
 
 ### What Gets Logged

internal/cmd/root.go

@@ -45,6 +45,7 @@ var (
 	envFile     string
 	enableDIFC  bool
 	logDir      string
+	validateEnv bool
 	debugLog    = logger.New("cmd:root")
 	version     = "dev" // Default version, overridden by SetVersion
 )
@@ -67,6 +68,7 @@ func init() {
 	rootCmd.Flags().StringVar(&envFile, "env", defaultEnvFile, "Path to .env file to load environment variables")
 	rootCmd.Flags().BoolVar(&enableDIFC, "enable-difc", defaultEnableDIFC, "Enable DIFC enforcement and session requirement (requires sys___init call before tool access)")
 	rootCmd.Flags().StringVar(&logDir, "log-dir", defaultLogDir, "Directory for log files (falls back to stdout if directory cannot be created)")
+	rootCmd.Flags().BoolVar(&validateEnv, "validate-env", false, "Validate execution environment (Docker, env vars) before starting")
 
 	// Mark mutually exclusive flags
 	rootCmd.MarkFlagsMutuallyExclusive("routed", "unified")
@@ -96,6 +98,18 @@ func run(cmd *cobra.Command, args []string) error {
 		}
 	}
 
+	// Validate execution environment if requested
+	if validateEnv {
+		debugLog.Printf("Validating execution environment...")
+		result := config.ValidateExecutionEnvironment()
+		if !result.IsValid() {
+			logger.LogError("startup", "Environment validation failed: %s", result.Error())
+			return fmt.Errorf("environment validation failed: %s", result.Error())
+		}
+		logger.LogInfo("startup", "Environment validation passed")
+		log.Println("Environment validation passed")
+	}
+
 	// Load configuration
 	var cfg *config.Config
 	var err error