feat: Docker setup, relay-status CLI, and integration tests (#3, #4, #5)

- Add Dockerfile and docker-compose.yml for L402 gateway + Phoenixd sidecar (#3)
- Add 'lightning-memory relay-status' CLI command showing relay connectivity,
  last sync time, and push count (#4)
- Add check_relay() and check_relays() to relay.py for probing relay health
- Add tests/test_sync_integration.py with 8 integration tests using a mock
  Nostr relay server (websockets): roundtrip push/pull, sync log tracking,
  dedup, cursor updates, signing requirement, NIP-78 export validation (#5)
- Add 3 unit tests for check_relay/check_relays to test_relay.py
- Update README with Docker and relay-status docs

Closes #3, closes #4, closes #5

Author: Jason Sosa

Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.12-slim AS builder
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY lightning_memory/ lightning_memory/
+
+RUN pip install --no-cache-dir ".[gateway]"
+
+FROM python:3.12-slim
+
+RUN useradd --create-home --shell /bin/bash lm
+WORKDIR /home/lm
+
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin/lightning-memory-gateway /usr/local/bin/lightning-memory-gateway
+
+USER lm
+
+EXPOSE 8402
+
+CMD ["lightning-memory-gateway"]

README.md

@@ -225,6 +225,16 @@ EOF
 
 4. Start: `lightning-memory-gateway`
 
+### Docker
+
+Run the gateway and Phoenixd together:
+
+```bash
+PHOENIXD_PASSWORD=your-password docker compose up
+```
+
+This starts the L402 gateway on port 8402 with Phoenixd as a sidecar on port 9740. Lightning state is persisted in a Docker volume.
+
 ### Client Example
 
 ```bash
@@ -240,6 +250,25 @@ curl -H "Authorization: L402 <macaroon>:<preimage>" \
 # → 200 + relevant memories
 ```
 
+## CLI Commands
+
+### `lightning-memory relay-status`
+
+Check connection status for all configured Nostr relays:
+
+```bash
+lightning-memory relay-status
+# Checking 3 relay(s)...
+#
+#   [+] wss://relay.damus.io: OK
+#   [+] wss://nos.lol: OK
+#   [x] wss://relay.nostr.band: FAIL (timeout)
+#
+# 2/3 relays reachable (5.2s)
+# Last pull: 2026-03-09 04:30:12 UTC
+# Memories pushed: 42
+```
+
 ## How It Works
 
 1. **First run**: A Nostr keypair is generated and stored at `~/.lightning-memory/keys/`

docker-compose.yml

@@ -0,0 +1,25 @@
+services:
+  phoenixd:
+    image: acinq/phoenixd:latest
+    ports:
+      - "9740:9740"
+    volumes:
+      - phoenixd-data:/phoenix/.phoenix
+    environment:
+      - PHOENIX_HTTP_PASSWORD=${PHOENIXD_PASSWORD:-changeme}
+
+  gateway:
+    build: .
+    ports:
+      - "8402:8402"
+    depends_on:
+      - phoenixd
+    volumes:
+      - gateway-config:/home/lm/.lightning-memory
+    environment:
+      - PHOENIXD_URL=http://phoenixd:9740
+      - PHOENIXD_PASSWORD=${PHOENIXD_PASSWORD:-changeme}
+
+volumes:
+  phoenixd-data:
+  gateway-config:

lightning_memory/relay.py

@@ -131,6 +131,43 @@ async def publish_to_relays(
     return list(await asyncio.gather(*tasks))
 
 
+async def check_relay(relay_url: str, timeout: float = 5.0) -> RelayResponse:
+    """Check if a relay is reachable by opening a WebSocket connection.
+
+    Args:
+        relay_url: WebSocket URL (wss://...)
+        timeout: Connection timeout in seconds
+
+    Returns:
+        RelayResponse with success=True if the relay accepted the connection
+    """
+    if websockets is None:
+        return RelayResponse(
+            relay=relay_url, success=False,
+            message="websockets not installed. pip install lightning-memory[sync]",
+        )
+
+    try:
+        async with websockets.connect(relay_url, close_timeout=2, open_timeout=timeout) as ws:
+            # Send a REQ and immediately close to verify the relay speaks NIP-01
+            sub_id = uuid.uuid4().hex[:8]
+            await ws.send(json.dumps(["REQ", sub_id, {"kinds": [30078], "limit": 0}]))
+            raw = await asyncio.wait_for(ws.recv(), timeout=timeout)
+            await ws.send(json.dumps(["CLOSE", sub_id]))
+            data = json.loads(raw)
+            if isinstance(data, list) and data[0] in ("EOSE", "EVENT", "NOTICE"):
+                return RelayResponse(relay=relay_url, success=True, message="connected")
+            return RelayResponse(relay=relay_url, success=True, message=f"response: {data[0]}")
+    except Exception as e:
+        return RelayResponse(relay=relay_url, success=False, message=str(e))
+
+
+async def check_relays(relay_urls: list[str], timeout: float = 5.0) -> list[RelayResponse]:
+    """Check multiple relays concurrently."""
+    tasks = [check_relay(url, timeout) for url in relay_urls]
+    return list(await asyncio.gather(*tasks))
+
+
 async def fetch_from_relays(
     relay_urls: list[str],
     filters: dict[str, Any],

lightning_memory/server.py

@@ -298,8 +298,61 @@ def ln_budget_status() -> dict:
     }
 
 
+def _cmd_relay_status() -> None:
+    """Show connection status for configured Nostr relays."""
+    import asyncio
+    import time
+
+    from .config import load_config
+    from .relay import check_relays
+
+    config = load_config()
+    relays = config.relays
+    print(f"Checking {len(relays)} relay(s)...\n")
+
+    start = time.monotonic()
+    results = asyncio.run(check_relays(relays))
+    elapsed = time.monotonic() - start
+
+    ok_count = 0
+    for r in results:
+        status = "OK" if r.success else "FAIL"
+        icon = "+" if r.success else "x"
+        msg = f"  [{icon}] {r.relay}: {status}"
+        if r.message and r.message != "connected":
+            msg += f" ({r.message})"
+        print(msg)
+        if r.success:
+            ok_count += 1
+
+    print(f"\n{ok_count}/{len(relays)} relays reachable ({elapsed:.1f}s)")
+
+    # Show last sync info if available
+    try:
+        engine = _get_engine()
+        from .sync import _ensure_sync_schema, _get_cursor
+        _ensure_sync_schema(engine.conn)
+        last_pull = _get_cursor(engine.conn, "last_pull_timestamp")
+        if last_pull:
+            from datetime import datetime, timezone
+            ts = datetime.fromtimestamp(float(last_pull), tz=timezone.utc)
+            print(f"Last pull: {ts.strftime('%Y-%m-%d %H:%M:%S UTC')}")
+
+        synced = engine.conn.execute("SELECT COUNT(*) FROM sync_log").fetchone()[0]
+        if synced:
+            print(f"Memories pushed: {synced}")
+    except Exception:
+        pass
+
+
 def main():
-    """Run the MCP server."""
+    """Run the MCP server, or a CLI subcommand."""
+    import sys
+
+    if len(sys.argv) > 1 and sys.argv[1] == "relay-status":
+        _cmd_relay_status()
+        return
+
     mcp.run()
 
 

tests/test_relay.py

@@ -8,6 +8,8 @@
 
 from lightning_memory.relay import (
     RelayResponse,
+    check_relay,
+    check_relays,
     fetch_events,
     fetch_from_relays,
     publish_event,
@@ -141,6 +143,40 @@ def test_fetch_from_multiple(self):
         assert len(results) == 2
 
 
+class TestCheckRelay:
+    def test_reachable_relay(self):
+        eose_response = json.dumps(["EOSE", "sub1"])
+        mock_connect = _mock_ws_connect([eose_response])
+
+        with patch("lightning_memory.relay.websockets") as mock_ws:
+            mock_ws.connect = MagicMock(return_value=mock_connect)
+
+            result = asyncio.run(check_relay("wss://test.relay"))
+
+        assert result.success is True
+        assert result.relay == "wss://test.relay"
+
+    def test_unreachable_relay(self):
+        with patch("lightning_memory.relay.websockets") as mock_ws:
+            mock_ws.connect = MagicMock(side_effect=ConnectionRefusedError("refused"))
+
+            result = asyncio.run(check_relay("wss://bad.relay"))
+
+        assert result.success is False
+        assert "refused" in result.message
+
+    def test_check_multiple_relays(self):
+        eose_response = json.dumps(["EOSE", "sub1"])
+        mock_connect = _mock_ws_connect([eose_response])
+
+        with patch("lightning_memory.relay.websockets") as mock_ws:
+            mock_ws.connect = MagicMock(return_value=mock_connect)
+
+            results = asyncio.run(check_relays(["wss://r1", "wss://r2"]))
+
+        assert len(results) == 2
+
+
 class TestRelayResponse:
     def test_defaults(self):
         r = RelayResponse(relay="wss://test", success=True)