Improve self-hosted Docker onboarding

Author: MaxGhenis

README.md

@@ -2,6 +2,28 @@
 
 A version of the PolicyEngine API that runs the `calculate` endpoint over household object. To debug locally, run `make debug`. 
 
+## Quick self-hosted run
+
+If you want to try the API without requesting hosted credentials, run the published Docker image:
+
+```
+docker run --rm -p 8080:8080 ghcr.io/policyengine/policyengine-household-api:latest
+```
+
+Then inspect the service metadata:
+
+```
+curl http://localhost:8080/
+```
+
+and send calculations to:
+
+```
+http://localhost:8080/us/calculate
+```
+
+Hosted API docs live at https://www.policyengine.org/us/api.
+
 ## Local development with Docker Compose
 
 To run this app locally via Docker Compose:

changelog.d/codex-docker-self-serve-smoke.changed.md

@@ -0,0 +1 @@
+Return JSON service metadata from the home endpoint and improve self-hosted Docker guidance, including a container healthcheck and non-root runtime user.

config/README.md

@@ -77,15 +77,15 @@ CONFIG_FILE=config/local.yaml make debug
 # Mount a custom config file
 docker run -v /path/to/your/config.yaml:/custom/config.yaml \
            -e CONFIG_FILE=/custom/config.yaml \
-           policyengine/household-api
+           ghcr.io/policyengine/policyengine-household-api:latest
 ```
 
 #### Docker Compose
 ```yaml
 version: '3.13'
 services:
   household-api:
-    image: policyengine/household-api
+    image: ghcr.io/policyengine/policyengine-household-api:latest
     volumes:
       - ./my-config.yaml:/app/config/custom.yaml
     environment:
@@ -123,7 +123,7 @@ spec:
     spec:
       containers:
       - name: api
-        image: policyengine/household-api
+        image: ghcr.io/policyengine/policyengine-household-api:latest
         env:
         - name: CONFIG_FILE
           value: /config/config.yaml
@@ -301,11 +301,12 @@ Use environment variables to override specific settings:
 
 ```bash
 docker run -e FLASK_DEBUG=1 \
+           -p 8080:8080 \
            -e AUTH__ENABLED=false \    # Disable Auth0 for local dev
            -e ANALYTICS__ENABLED=false \ # Disable analytics for local dev
            -e AI__ENABLED=false \
            -e DATABASE__PROVIDER=sqlite \
-           policyengine/household-api
+           ghcr.io/policyengine/policyengine-household-api:latest
 ```
 
 #### Template Variable Substitution
@@ -359,15 +360,15 @@ docker run -v /path/to/config.yaml:/app/config/custom.yaml \
            -v /path/to/values.env:/app/config/values.env \
            -e CONFIG_FILE=/app/config/custom.yaml \
            -e CONFIG_VALUE_SETTINGS=/app/config/values.env \
-           policyengine/household-api
+           ghcr.io/policyengine/policyengine-household-api:latest
 ```
 
 Or with Docker Compose:
 ```yaml
 version: '3.13'
 services:
   household-api:
-    image: policyengine/household-api
+    image: ghcr.io/policyengine/policyengine-household-api:latest
     volumes:
       - ./my-config.yaml:/app/config/custom.yaml
       - ./my-values.env:/app/config/values.env

gcp/policyengine_household_api/Dockerfile.production

@@ -34,9 +34,19 @@ COPY ./config/default.yaml /app/config/default.yaml
 # Copy startup script
 COPY ./gcp/policyengine_household_api/start.sh /app/start.sh
 RUN chmod +x /app/start.sh
-  
+
+# Drop root privileges in the runtime image.
+RUN groupadd policyapi && \
+    useradd --gid policyapi --create-home policyapi && \
+    chown -R policyapi:policyapi /app /opt/venv
+ 
 # Configure environment (runs as root by default)
 ENV PATH="/opt/venv/bin:$PATH"
 EXPOSE 8080
-  
-CMD ["/app/start.sh"]
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl --fail --silent http://127.0.0.1:8080/liveness_check || exit 1
+
+USER policyapi
+ 
+CMD ["/app/start.sh"]

policyengine_household_api/endpoints/home.py

@@ -1,7 +1,28 @@
-def get_home() -> str:
-    """Get the home page of the PolicyEngine household API.
+import json
 
-    Returns:
-        str: The home page.
-    """
-    return f"<h1>PolicyEngine household API</h1><p>Use this API to compute the impact of public policy upon households.</p>"
+from flask import Response
+
+
+def get_home() -> Response:
+    """Return service metadata for self-serve and hosted API users."""
+
+    response_body = {
+        "status": "ok",
+        "message": "PolicyEngine household API",
+        "result": {
+            "docs_url": "https://www.policyengine.org/us/api",
+            "container_image": "ghcr.io/policyengine/policyengine-household-api",
+            "hosted_calculate_url": "https://household.api.policyengine.org/us/calculate",
+            "local_calculate_url": "http://localhost:8080/us/calculate",
+            "health_checks": {
+                "liveness": "/liveness_check",
+                "readiness": "/readiness_check",
+            },
+        },
+    }
+
+    return Response(
+        json.dumps(response_body),
+        status=200,
+        mimetype="application/json",
+    )

policyengine_household_api/openapi_spec.yaml

@@ -13,16 +13,39 @@ servers:
 paths:
   /:
     get:
-      summary: Get the home page of the PolicyEngine API
+      summary: Get service metadata for the PolicyEngine household API
       operationId: get_home
-      description: Returns the home page of the PolicyEngine API as an HTML string.
+      description: Returns service metadata, documentation links, and self-hosting hints.
       responses:
         200:
-          description: The home page.
+          description: Service metadata.
           content:
-            text/html:
+            application/json:
               schema:
-                type: string
+                type: object
+                properties:
+                  status:
+                    type: string
+                  message:
+                    type: string
+                  result:
+                    type: object
+                    properties:
+                      docs_url:
+                        type: string
+                      container_image:
+                        type: string
+                      hosted_calculate_url:
+                        type: string
+                      local_calculate_url:
+                        type: string
+                      health_checks:
+                        type: object
+                        properties:
+                          liveness:
+                            type: string
+                          readiness:
+                            type: string
   /{country_id}/metadata:
     get:
       summary: Get metadata for a country
@@ -841,4 +864,4 @@ paths:
                   paths:
                     type: object
                   servers:
-                    type: array
+                    type: array

tests/unit/endpoints/test_home.py

@@ -0,0 +1,29 @@
+import json
+
+
+class TestHomeEndpoint:
+    def test_returns_json_service_metadata(self, client):
+        response = client.get("/")
+
+        assert response.status_code == 200
+        assert response.mimetype == "application/json"
+
+        payload = json.loads(response.data)
+
+        assert payload["status"] == "ok"
+        assert payload["message"] == "PolicyEngine household API"
+
+        result = payload["result"]
+        assert result["docs_url"] == "https://www.policyengine.org/us/api"
+        assert (
+            result["container_image"]
+            == "ghcr.io/policyengine/policyengine-household-api"
+        )
+        assert result["hosted_calculate_url"] == (
+            "https://household.api.policyengine.org/us/calculate"
+        )
+        assert result["local_calculate_url"] == "http://localhost:8080/us/calculate"
+        assert result["health_checks"] == {
+            "liveness": "/liveness_check",
+            "readiness": "/readiness_check",
+        }