docs: Update SSL configuration instructions in .env.example, README, and CONFIGURATION.md

- Enhanced the .env.example file with detailed comments on SSL setup for both local and production environments.
- Updated README to clarify HTTPS configuration steps and the use of SSL certificates.
- Revised CONFIGURATION.md to provide a comprehensive overview of SSL/TLS settings and usage instructions for Docker Compose.

Author: usnavy13

.env.example

@@ -32,12 +32,26 @@ MINIO_SECRET_KEY=minioadmin
 # SANDBOX_UID=1002         # Shared host UID for all sandbox languages
 
 # ── Port ──────────────────────────────────────────────────────
-# PORT=8000                # External port the API is reachable on
+# PORT=8000                # External host port published by docker compose
 
 # ── SSL/HTTPS ──────────────────────────────────────────────────
-# ENABLE_HTTPS=false
-# SSL_CERT_FILE=/path/to/cert.pem
-# SSL_KEY_FILE=/path/to/key.pem
+# HTTPS works the same with docker-compose.yml and docker-compose.prod.yml:
+# 1. SSL_CERTS_PATH is a host path mounted to /app/ssl inside the container
+# 2. SSL_CERT_FILE and SSL_KEY_FILE must be container paths under /app/ssl
+#
+# Simple local/self-managed cert directory:
+# PORT=443
+# ENABLE_HTTPS=true
+# SSL_CERTS_PATH=./ssl
+# SSL_CERT_FILE=/app/ssl/fullchain.pem
+# SSL_KEY_FILE=/app/ssl/privkey.pem
+#
+# Let's Encrypt on the host:
+# PORT=443
+# ENABLE_HTTPS=true
+# SSL_CERTS_PATH=/etc/letsencrypt
+# SSL_CERT_FILE=/app/ssl/live/example.com/fullchain.pem
+# SSL_KEY_FILE=/app/ssl/live/example.com/privkey.pem
 
 # ── Logging ────────────────────────────────────────────────────
 # LOG_LEVEL=INFO             # INFO = clean (1 log per execution); DEBUG = full detail

README.md

@@ -47,6 +47,8 @@ Most users should run the published Docker image from GHCR. You do not need to b
 The API will be available at `http://localhost:8000`.
 Visit `http://localhost:8000/docs` for the interactive API documentation.
 
+To enable HTTPS with either compose file, set `PORT`, `ENABLE_HTTPS`, `SSL_CERTS_PATH`, `SSL_CERT_FILE`, and `SSL_KEY_FILE` in `.env`. `SSL_CERTS_PATH` is the host path mounted into the container at `/app/ssl`, while `SSL_CERT_FILE` and `SSL_KEY_FILE` must point to the certificate files inside the container. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md#sslhttps-configuration).
+
 ### Common Consumer Commands
 
 ```bash
@@ -96,7 +98,7 @@ The dashboard requires the master API key for authentication.
 - **Session Management**: Redis-based session handling with automatic cleanup
 - **S3-Compatible Storage**: MinIO integration for persistent file storage
 - **Authentication**: API key-based authentication for secure access
-- **HTTPS/SSL Support**: Optional SSL/TLS encryption with automatic HTTP to HTTPS redirection
+- **HTTPS/SSL Support**: Optional in-container SSL/TLS termination for both compose workflows
 - **Health Monitoring**: Comprehensive health check endpoints for all dependencies
 - **Metrics Collection**: Execution and API metrics for monitoring and debugging
 - **Unicode Support**: Full Unicode filename support in file downloads

docker-compose.prod.yml

@@ -18,6 +18,8 @@ services:
       - MINIO_ENDPOINT=minio:9000
     volumes:
       - sandbox-data:/var/lib/code-interpreter/sandboxes
+      # SSL_CERTS_PATH is a host path; SSL_CERT_FILE and SSL_KEY_FILE must point
+      # to the mounted files inside the container under /app/ssl.
       - ${SSL_CERTS_PATH:-./ssl}:/app/ssl:ro
     tmpfs:
       - /app/data:size=100m

docker-compose.yml

@@ -27,6 +27,8 @@ services:
       - MINIO_ENDPOINT=minio:9000
     volumes:
       - sandbox-data:/var/lib/code-interpreter/sandboxes
+      # SSL_CERTS_PATH is a host path; SSL_CERT_FILE and SSL_KEY_FILE must point
+      # to the mounted files inside the container under /app/ssl.
       - ${SSL_CERTS_PATH:-./ssl}:/app/ssl:ro
     tmpfs:
       - /app/data:size=100m

docs/CONFIGURATION.md

@@ -43,42 +43,73 @@ Controls the basic API server settings.
 
 Configures SSL/TLS support for secure HTTPS connections.
 
-| Variable         | Default  | Description                                              |
-| ---------------- | -------- | -------------------------------------------------------- |
-| `ENABLE_HTTPS`   | `false`  | Enable HTTPS/SSL support                                 |
-| `SSL_CERTS_PATH` | `./ssl`  | Host path to directory containing `cert.pem` and `key.pem` |
-
-> **Note:** The certificate files are automatically mapped to `/app/ssl/` inside the API container via `docker-compose.yml`. You only need to set `SSL_CERTS_PATH` to point to your certificates directory on the host.
+Both `docker-compose.yml` and `docker-compose.prod.yml` use the same HTTPS contract:
+
+- `PORT` is the external host port published by Docker.
+- `SSL_CERTS_PATH` is a host path mounted into the API container at `/app/ssl`.
+- `SSL_CERT_FILE` and `SSL_KEY_FILE` are paths inside the container.
+- For predictable restarts, set `ENABLE_HTTPS=true` explicitly instead of relying on auto-detection.
+
+| Variable         | Default                | Description |
+| ---------------- | ---------------------- | ----------- |
+| `PORT`           | `8000`                 | External host port published by Docker Compose |
+| `ENABLE_HTTPS`   | auto                   | When unset, HTTPS auto-enables only if the configured cert and key files exist inside the container |
+| `SSL_CERTS_PATH` | `./ssl`                | Host path mounted into the container at `/app/ssl` |
+| `SSL_CERT_FILE`  | `/app/ssl/fullchain.pem` | Certificate file path inside the container |
+| `SSL_KEY_FILE`   | `/app/ssl/privkey.pem` | Private key file path inside the container |
+| `SSL_CA_CERTS`   | -                      | Optional CA bundle path inside the container |
 
 **HTTPS Setup:**
 
-1. **Generate or obtain SSL certificates**:
+1. **Use a simple cert directory on the host**:
 
    ```bash
-   # For development (self-signed certificate)
-   mkdir ssl
-   openssl req -x509 -newkey rsa:4096 -nodes -out ssl/cert.pem -keyout ssl/key.pem -days 365
-
-   # For production, use certificates from a trusted CA
+   mkdir -p ssl
+   openssl req -x509 -newkey rsa:4096 -nodes \
+     -out ssl/fullchain.pem \
+     -keyout ssl/privkey.pem \
+     -days 365
    ```
 
-2. **Configure HTTPS in .env**:
+   Then set:
 
    ```bash
+   PORT=443
    ENABLE_HTTPS=true
+   SSL_CERTS_PATH=./ssl
+   SSL_CERT_FILE=/app/ssl/fullchain.pem
+   SSL_KEY_FILE=/app/ssl/privkey.pem
+   ```
+
+2. **Use Let's Encrypt from the host**:
 
-   # If using the default ./ssl directory, no additional config needed.
-   # If your certs are elsewhere, set the path:
-   # SSL_CERTS_PATH=/path/to/your/ssl/certs
+   If the host already has certificates in `/etc/letsencrypt`, mount that tree and point the app at the files inside `/app/ssl`:
+
+   ```bash
+   PORT=443
+   ENABLE_HTTPS=true
+   SSL_CERTS_PATH=/etc/letsencrypt
+   SSL_CERT_FILE=/app/ssl/live/example.com/fullchain.pem
+   SSL_KEY_FILE=/app/ssl/live/example.com/privkey.pem
    ```
 
-   The directory must contain files named `cert.pem` and `key.pem`.
+3. **Start the stack with either compose file**:
 
-3. **Deploy with docker compose**:
    ```bash
    docker compose up -d
+
+   # or
+   docker compose -f docker-compose.prod.yml up -d
+   ```
+
+4. **Verify HTTPS**:
+
+   ```bash
+   curl -fsk https://localhost/health
    ```
 
+If you terminate TLS at an external reverse proxy instead, keep the API on HTTP by leaving `ENABLE_HTTPS` unset or setting it to `false`, and publish the proxy on `443` instead of the API container.
+
 **Security Notes:**
 
 - Use certificates from trusted Certificate Authorities in production