Enhance Docker support and configuration

- Updated .env.example to recommend using docker.env and secrets for sensitive data.
- Modified .gitignore to include docker.env and secrets directory.
- Adjusted docker-compose.yml to utilize environment files and updated port mappings.
- Implemented read_env_or_file utility for better environment variable management.
- Refactored portfolio and trades routers to use the new utility for fetching environment variables.
- Added integration and phase 2 test updates for new environment variable handling.
- Created new documentation for Docker operations and secret management.
- Added placeholder files for Docker secrets and configuration.

tests/test_integration.py

@@ -1,14 +1,11 @@
 """
 Integration test suite — pre-Docker validation.
 
-Run all tests (mocked IB):
+Run offline tests only:
     pytest tests/test_integration.py -v
 
 Run with live IB Gateway on port 4002:
-    pytest tests/test_integration.py -v  (SKIP_LIVE_TESTS must NOT be set)
-
-Skip live tests:
-    SKIP_LIVE_TESTS=1 pytest tests/test_integration.py -v
+    RUN_LIVE_IB_TESTS=1 pytest tests/test_integration.py -v
 """
 import os
 import sqlite3
@@ -22,7 +19,7 @@ import pytest
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-SKIP_LIVE = os.getenv("SKIP_LIVE_TESTS", "0") == "1"
+RUN_LIVE = os.getenv("RUN_LIVE_IB_TESTS", "0") == "1"
 
 # ── Minimal ib_async stubs (used when real ib_async not available) ────────────
 def _make_stub():
@@ -110,11 +107,12 @@ class TestIBKRConnection:
 
     def test_ibkr_port_env_set(self):
         port = int(os.getenv("IBKR_PORT", "4002"))
-        assert port in (4001, 4002), (
-            f"IBKR_PORT must be 4001 (live) or 4002 (paper), got {port}"
+        assert port in (4001, 4002, 4003, 4004), (
+            "IBKR_PORT must be 4001/4003 (live) or 4002/4004 (paper), "
+            f"got {port}"
         )
 
-    @pytest.mark.skipif(SKIP_LIVE, reason="SKIP_LIVE_TESTS=1")
+    @pytest.mark.skipif(not RUN_LIVE, reason="RUN_LIVE_IB_TESTS=1 required")
     def test_ibkr_connection_live(self):
         import asyncio
 
@@ -144,7 +142,7 @@ class TestIBKRConnection:
         assert ib.isConnected(), "IB Gateway connection not established"
         ib.disconnect()
 
-    @pytest.mark.skipif(SKIP_LIVE, reason="SKIP_LIVE_TESTS=1")
+    @pytest.mark.skipif(not RUN_LIVE, reason="RUN_LIVE_IB_TESTS=1 required")
     def test_history_returns_data(self):
         r = client.get("/history?symbol=AAPL")
         assert r.status_code == 200