From af88d935bcbc15f0c801085283c3c9793085a282 Mon Sep 17 00:00:00 2001
From: burnettk <burnettk@users.noreply.github.com>
Date: Wed, 3 Apr 2024 20:28:09 -0400
Subject: [PATCH] document path-based routing

---
 .../path_based_routing.md                     | 37 +++++++++++++++++++
 docs/index.md                                 |  1 +
 2 files changed, 38 insertions(+)
 create mode 100644 docs/DevOps_installation_integration/path_based_routing.md

diff --git a/docs/DevOps_installation_integration/path_based_routing.md b/docs/DevOps_installation_integration/path_based_routing.md
new file mode 100644
index 00000000..707bd945
--- /dev/null
+++ b/docs/DevOps_installation_integration/path_based_routing.md
@@ -0,0 +1,37 @@
+# Path-based Routing
+
+If you are using frontend, frontend and backend need to share cookies.
+Backend, in particular, sets a cookie, and frontend needs to read it.
+As such, you cannot run frontend and backend on different subdomains, like this:
+
+* frontend.example.com
+* backend.example.com
+
+Instead, we often run them like this:
+
+* example.com for frontend
+* api.example.com for backend
+
+This works, since backend can set a cookie for the entire domain, and frontend can read it.
+
+Another alternative that works well is to run them on the same host, but with different paths, like this:
+
+ * spiff.example.com for frontend
+ * spiff.example.com/api for backend
+
+To accomplish this path-based routing scenario, set environment variables like this in frontend:
+
+```sh
+SPIFFWORKFLOW_FRONTEND_RUNTIME_CONFIG_APP_ROUTING_STRATEGY=path_based
+```
+
+And in backend, you may need to set:
+
+```sh
+SPIFFWORKFLOW_BACKEND_URL_FOR_FRONTEND=https://spiff.example.com
+SPIFFWORKFLOW_BACKEND_URL=https://spiff.example.com/api
+# if you happen to be using the internal openid server. do not do this in production.
+SPIFFWORKFLOW_BACKEND_OPEN_ID_SERVER_URL=https://spiff.example.com/api/openid
+# if you can manage, use in-cluster DNS for connector. you may need a different host or port.
+SPIFFWORKFLOW_BACKEND_CONNECTOR_PROXY_URL=http://spiffworkflow-connector:8004
+```
diff --git a/docs/index.md b/docs/index.md
index aef19d70..d47f9349 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -48,6 +48,7 @@ DevOps_installation_integration/configure_connector_proxy.md
 DevOps_installation_integration/deploy_aws_lambda.md
 DevOps_installation_integration/Secrets.md
 DevOps_installation_integration/redis_celery_broker.md
+DevOps_installation_integration/path_based_routing.md
 ```
 
 ```{toctree}