From 10abd87a93abf698923a8776811d0991dfde10c6 Mon Sep 17 00:00:00 2001 From: Thomas Varney Date: Wed, 26 Feb 2025 12:09:50 -0500 Subject: [PATCH 1/7] Add what is it for doc --- internal/dev_server/README.md | 2 +- internal/dev_server/using-dev-server.md | 7 +++++++ 2 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 internal/dev_server/using-dev-server.md diff --git a/internal/dev_server/README.md b/internal/dev_server/README.md index 4466b8ae..6fe1e0ac 100644 --- a/internal/dev_server/README.md +++ b/internal/dev_server/README.md @@ -1,4 +1,4 @@ # dev server -The dev server is a go server that ldcli can run. It provides a local-only version of all the APIs that support LaunchDarkly SDKs. You can use it to serve flags to local and ephemeral environments. It copies flag _values_ for a project from a source environment and serves those. There are also APIs that let you override those values so that you can enable a feature just in your dev environment, e.g. +The dev server is a go server that ldcli can run. It provides a local-only version of all the APIs that support LaunchDarkly SDKs. You can use it to serve flags to local and ephemeral environments. It copies flag _values_ for a project from a source environment and serves those. There are also APIs that let you override those values so that you can enable a feature just in your dev environment. The build of the dev server is incorporated into the ldcli build itself. The UI provided by the dev server has a [manual build](./ui/README.md). diff --git a/internal/dev_server/using-dev-server.md b/internal/dev_server/using-dev-server.md new file mode 100644 index 00000000..e36b2b83 --- /dev/null +++ b/internal/dev_server/using-dev-server.md @@ -0,0 +1,7 @@ +## What should I use it for? + +`dev-server` is intended as a replacement for creating certain kinds of environments in the LD app itself that are not part of a flag's release path e.g. Staging, UAT, QA, Production. The most common examples of this are local development environments and ephemeral CI environments. It can also be used for environments that do not need complex targeting rules and are mostly a snapshot of your staging environment equivalent, such as environments for live testing vendor integrations. + +## What should I not use this for? + +You should refrain from using `dev-server` for any release path critical environments, as well as environments where complex targeting logic is required. Currently, `dev-server` only supports serving a single variation and supports no targeting logic. From 129b89fda6587af07113097eccc84236423785b4 Mon Sep 17 00:00:00 2001 From: Thomas Varney Date: Wed, 26 Feb 2025 12:14:46 -0500 Subject: [PATCH 2/7] remove crazy bit --- internal/dev_server/using-dev-server.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/dev_server/using-dev-server.md b/internal/dev_server/using-dev-server.md index e36b2b83..93ff0a2a 100644 --- a/internal/dev_server/using-dev-server.md +++ b/internal/dev_server/using-dev-server.md @@ -1,6 +1,6 @@ ## What should I use it for? -`dev-server` is intended as a replacement for creating certain kinds of environments in the LD app itself that are not part of a flag's release path e.g. Staging, UAT, QA, Production. The most common examples of this are local development environments and ephemeral CI environments. It can also be used for environments that do not need complex targeting rules and are mostly a snapshot of your staging environment equivalent, such as environments for live testing vendor integrations. +`dev-server` is intended as a replacement for creating certain kinds of environments in the LD app itself that are not part of a flag's release path e.g. Staging, UAT, QA, Production. The most common examples of this are local development environments and ephemeral CI environments. ## What should I not use this for? From 4b0b27b948f6ff0069c573ea0effa88578bec115 Mon Sep 17 00:00:00 2001 From: Thomas Varney Date: Thu, 27 Feb 2025 11:49:59 -0500 Subject: [PATCH 3/7] rename and re-draft doc --- internal/dev_server/manifesto.md | 17 +++++++++++++++++ internal/dev_server/using-dev-server.md | 7 ------- 2 files changed, 17 insertions(+), 7 deletions(-) create mode 100644 internal/dev_server/manifesto.md delete mode 100644 internal/dev_server/using-dev-server.md diff --git a/internal/dev_server/manifesto.md b/internal/dev_server/manifesto.md new file mode 100644 index 00000000..6722be24 --- /dev/null +++ b/internal/dev_server/manifesto.md @@ -0,0 +1,17 @@ +# Dev Server Vision Doc + +This doc lays out our vision for what `dev-server` is supposed to do, and why this is the case. + +## Purpose of the Dev Server + +First and foremost, `dev-server` is meant as a replacement for local dev and CI environments. Other use cases may exist (and don't hestitate to ask if you think you have one!), but since a `dev-server` environment lacks any targeting, it is best suited to situations where there is only 1 user for the whole environment. + +We implemented it this way in order to solve a problem common both internally and amongst our userbase where an environment would get created per developer on a project as well as per CI build. As you could expect, this becomes exponentially harder to maintain as the number of environments scales both technically and from a process perspective - something has to clear out those environments after all! + +Another intentional design decision was the choice not to allow the creation of local-only flags. A running `dev-server` can only pull from a real environment. From there, you can override the served value for your local environment. + +We chose to do this in order to minimize any surprises as your code moves from local / CI to a prod / prod-like environment. In our experience, the greatest source of such surprises has been drift between the configuration of a developer's LD environment and our Staging environment. Unless a developer is constantly making sure their flag state matches higher environments as closely as possible, flag state drifts until their local development environment starts to break, neccessitating a painful process of reconciling flag state. + +Lastly, we highly recommend not using `dev-server` for environments with prod-level traffic. As we designed this with local dev in mind, something will definitely break if you try to use this for that level of load. + +With that said, it's our hope that you enjoy using the `dev-server`, and feedback is more than welcome! \ No newline at end of file diff --git a/internal/dev_server/using-dev-server.md b/internal/dev_server/using-dev-server.md deleted file mode 100644 index 93ff0a2a..00000000 --- a/internal/dev_server/using-dev-server.md +++ /dev/null @@ -1,7 +0,0 @@ -## What should I use it for? - -`dev-server` is intended as a replacement for creating certain kinds of environments in the LD app itself that are not part of a flag's release path e.g. Staging, UAT, QA, Production. The most common examples of this are local development environments and ephemeral CI environments. - -## What should I not use this for? - -You should refrain from using `dev-server` for any release path critical environments, as well as environments where complex targeting logic is required. Currently, `dev-server` only supports serving a single variation and supports no targeting logic. From c0250ab9814146e2066d369657d0e0737ac6dde9 Mon Sep 17 00:00:00 2001 From: Thomas Varney Date: Thu, 27 Feb 2025 11:51:17 -0500 Subject: [PATCH 4/7] i hate linters --- internal/dev_server/manifesto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/dev_server/manifesto.md b/internal/dev_server/manifesto.md index 6722be24..13a8a55c 100644 --- a/internal/dev_server/manifesto.md +++ b/internal/dev_server/manifesto.md @@ -14,4 +14,4 @@ We chose to do this in order to minimize any surprises as your code moves from l Lastly, we highly recommend not using `dev-server` for environments with prod-level traffic. As we designed this with local dev in mind, something will definitely break if you try to use this for that level of load. -With that said, it's our hope that you enjoy using the `dev-server`, and feedback is more than welcome! \ No newline at end of file +With that said, it's our hope that you enjoy using the `dev-server`, and feedback is more than welcome! From ec324668862187b1bb832efd4c0fe6493494a1a4 Mon Sep 17 00:00:00 2001 From: Thomas Varney <70972175+tvarney13@users.noreply.github.com> Date: Thu, 27 Feb 2025 15:42:06 -0500 Subject: [PATCH 5/7] Update internal/dev_server/manifesto.md Co-authored-by: Mike Zorn --- internal/dev_server/manifesto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/dev_server/manifesto.md b/internal/dev_server/manifesto.md index 13a8a55c..38360388 100644 --- a/internal/dev_server/manifesto.md +++ b/internal/dev_server/manifesto.md @@ -4,7 +4,7 @@ This doc lays out our vision for what `dev-server` is supposed to do, and why th ## Purpose of the Dev Server -First and foremost, `dev-server` is meant as a replacement for local dev and CI environments. Other use cases may exist (and don't hestitate to ask if you think you have one!), but since a `dev-server` environment lacks any targeting, it is best suited to situations where there is only 1 user for the whole environment. +First and foremost, `dev-server` is meant as a replacement for local dev and CI environments managed in the LaunchDarkly service. Other use cases may exist (and don't hesitate to ask if you think you have one!), but since a `dev-server` environment lacks any targeting, it is best suited to situations where there is only 1 user for the whole environment. We implemented it this way in order to solve a problem common both internally and amongst our userbase where an environment would get created per developer on a project as well as per CI build. As you could expect, this becomes exponentially harder to maintain as the number of environments scales both technically and from a process perspective - something has to clear out those environments after all! From b813981c7fb47d68147d6cfde2027ab2cdecd022 Mon Sep 17 00:00:00 2001 From: Thomas Varney <70972175+tvarney13@users.noreply.github.com> Date: Thu, 27 Feb 2025 15:42:20 -0500 Subject: [PATCH 6/7] Update internal/dev_server/manifesto.md Co-authored-by: Mike Zorn --- internal/dev_server/manifesto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/internal/dev_server/manifesto.md b/internal/dev_server/manifesto.md index 38360388..0fa85cd8 100644 --- a/internal/dev_server/manifesto.md +++ b/internal/dev_server/manifesto.md @@ -12,6 +12,6 @@ Another intentional design decision was the choice not to allow the creation of We chose to do this in order to minimize any surprises as your code moves from local / CI to a prod / prod-like environment. In our experience, the greatest source of such surprises has been drift between the configuration of a developer's LD environment and our Staging environment. Unless a developer is constantly making sure their flag state matches higher environments as closely as possible, flag state drifts until their local development environment starts to break, neccessitating a painful process of reconciling flag state. -Lastly, we highly recommend not using `dev-server` for environments with prod-level traffic. As we designed this with local dev in mind, something will definitely break if you try to use this for that level of load. +Lastly, do not use the `dev-server` for environments with prod-level traffic. As we designed this with local dev in mind, production throughput has never been tested. With that said, it's our hope that you enjoy using the `dev-server`, and feedback is more than welcome! From ecc682f5ca5f617df7b3c3acbd0de0b4064f61f4 Mon Sep 17 00:00:00 2001 From: Thomas Varney Date: Thu, 27 Feb 2025 15:46:53 -0500 Subject: [PATCH 7/7] minor edit --- internal/dev_server/manifesto.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/internal/dev_server/manifesto.md b/internal/dev_server/manifesto.md index 0fa85cd8..b0e4ca3a 100644 --- a/internal/dev_server/manifesto.md +++ b/internal/dev_server/manifesto.md @@ -8,9 +8,7 @@ First and foremost, `dev-server` is meant as a replacement for local dev and CI We implemented it this way in order to solve a problem common both internally and amongst our userbase where an environment would get created per developer on a project as well as per CI build. As you could expect, this becomes exponentially harder to maintain as the number of environments scales both technically and from a process perspective - something has to clear out those environments after all! -Another intentional design decision was the choice not to allow the creation of local-only flags. A running `dev-server` can only pull from a real environment. From there, you can override the served value for your local environment. - -We chose to do this in order to minimize any surprises as your code moves from local / CI to a prod / prod-like environment. In our experience, the greatest source of such surprises has been drift between the configuration of a developer's LD environment and our Staging environment. Unless a developer is constantly making sure their flag state matches higher environments as closely as possible, flag state drifts until their local development environment starts to break, neccessitating a painful process of reconciling flag state. +Another intentional restriction is that flags must first exist in the source environment. We chose to do this in order to minimize any surprises as your code moves from local / CI to a prod / prod-like environment. In our experience, the greatest source of such surprises has been drift between the configuration of a developer's LD environment and our Staging environment. Unless a developer is constantly making sure their flag state matches higher environments as closely as possible, flag state drifts until their local development environment starts to break, neccessitating a painful process of reconciling flag state. Lastly, do not use the `dev-server` for environments with prod-level traffic. As we designed this with local dev in mind, production throughput has never been tested.