diff --git a/.eslintrc.json b/.eslintrc.json
index 050fcd04..e419209c 100644
--- a/.eslintrc.json
+++ b/.eslintrc.json
@@ -10,6 +10,7 @@
},
"rules": {
"no-undef": "off",
+ "no-unused-vars": "off",
"no-unused-expressions": "off"
}
}
diff --git a/cloud/architecture.mdx b/cloud/architecture.mdx
index 0632c297..e8d8e124 100644
--- a/cloud/architecture.mdx
+++ b/cloud/architecture.mdx
@@ -20,11 +20,11 @@ This allows Flipt Cloud to work for both mono-repo and multi-repo architectures.
## Control Plane
@@ -53,11 +53,11 @@ Flipt Cloud supports evaluation for our [client-side SDKs](/integration/client)
[Server-side SDKs](/integration/server) including [OpenFeature SDKs](/integration/openfeature) are also supported but currently require you to run your own Flipt instances.
@@ -72,11 +72,11 @@ To scale evaluation requests and serve feature flag evaluations via our server-s
### Client-Side Evaluation
@@ -85,11 +85,11 @@ You can also run your own Flipt Open Source instances and configure our client-s
For more information on how to deploy Flipt Open Source and how to configure it to source flag data from your Git repository, please refer to the [Moving to Production](/cloud/guides/production) guide.
diff --git a/cloud/features/approval-workflows.mdx b/cloud/features/approval-workflows.mdx
index 366a74cf..cd2d31d0 100644
--- a/cloud/features/approval-workflows.mdx
+++ b/cloud/features/approval-workflows.mdx
@@ -6,7 +6,7 @@ mode: "wide"
Flipt Cloud provides a built-in approval workflow system that allows you to easily manage and track the proposal and approval process for your flags, ensuring that they are approved by the appropriate stakeholders before they are released to production.
-
+
## Overview
@@ -28,7 +28,7 @@ The approval workflow system is designed to fit into this process, and to make i
When you create an environment in Flipt Cloud, you can choose to protect the environment. This will require that all flag and other configuration changes go through a review and approval process before they are served from the environment.
-
+
In our Git backed storage model, all environments have a default branch. If you chose an existing repository and branch when creating the environment and that branch is protected, the environment itself will be protected by default.
@@ -39,17 +39,17 @@ In our Git backed storage model, all environments have a default branch. If you
Protected environments are read-only and can only be changed by going through the proposal/approval process. If you are in a protected environment, you will see the 'Protected' badge in the top right of the environment.
-
+
## Approval Process
To make a change for a protected environment, you will need to put the environment into 'editing mode' by clicking on the 'Protected' badge. This will prompt a confirmation dialog asking you to confirm that you want to create a proposal branch to make your changes.
-
+
Once you click 'Create Branch', you will be redirected to a new environment that is no longer protected. This environment is a full read/write replica of the protected environment, but any changes you make will not be deployed to the protected environment until they are approved and merged.
-
+
You can make changes to the unprotected environment, and they will be captured in the proposal branch. Once you are ready to deploy your changes, you can create a pull request into the protected environment.
@@ -57,25 +57,25 @@ You can make changes to the unprotected environment, and they will be captured i
After making the changes you want to propose, you can create a proposal by clicking on the 'Propose' button in the top right of the screen. This will again prompt a confirmation dialog asking you to confirm that you want to create a new pull request in your repository and add it to the approval workflow.
-
+
Once you click 'Create Proposal', you will see a badge in the top right of the screen indicating that a proposal is pending, with a link to the proposal pull request.
-
+
Clicking on the badge will take you to the proposal pull request.
-
+
## Approve and Merge
Your team can review the proposal and approve it by clicking on the 'Approve' button in the pull request. Once the proposal is approved, you will be able to merge the pull request into the protected environment.
-
+
Once the pull request is merged, the changes will be deployed to the protected environment.
-
+
You can leverage GitHub's existing [Code
diff --git a/cloud/features/authentication.mdx b/cloud/features/authentication.mdx
index 33bbfff9..7e2ee1e9 100644
--- a/cloud/features/authentication.mdx
+++ b/cloud/features/authentication.mdx
@@ -10,7 +10,7 @@ You get social login, passwordless authentication, and multi-factor authenticati
We also support custom authentication providers, so you can integrate with your existing identity management system.
-
+
This flexibility allows you to choose the authentication method that best fits your organization's needs, whether you're a small startup or a large enterprise.
@@ -18,7 +18,7 @@ This flexibility allows you to choose the authentication method that best fits y
Flipt Cloud supports Single Sign-On (SSO) with popular identity providers like Okta, Microsoft Active Directory, and Google Workspace. With SSO, your team members can log in to Flipt using their existing credentials, making it easy to manage access and permissions.
-
+
SSO also enhances security by reducing the number of passwords your team members need to remember and ensuring that access is granted only to authorized users.
@@ -28,8 +28,8 @@ You can even set up custom SAML and OIDC providers, so you can use your existing
To access the Flipt API for evaluation requests, you can generate API keys for each environment that you create. This key is used to authenticate your requests to the API and is available in the environment settings.
-
+
API keys are securely stored in Flipt Cloud and are used to authenticate requests made through our SDKs.
-
+
diff --git a/cloud/features/custom-domains.mdx b/cloud/features/custom-domains.mdx
index b1d84c05..7492a99e 100644
--- a/cloud/features/custom-domains.mdx
+++ b/cloud/features/custom-domains.mdx
@@ -17,11 +17,11 @@ This is useful if you want to use a domain (or subdomain) that you already own i
@@ -76,11 +76,11 @@ Using custom domains with Flipt Cloud is a simple three step process:
1. **Configure the Domain**: Once enabled, you can add your custom domain to your Flipt Cloud environment in the Flipt Cloud UI.
-
+
2. **Configure the DNS**: You'll need to configure the DNS for your custom domain to point to your existing Flipt Cloud environment.
-
+
3. **Update Your SDKs**: Once the DNS has propagated, you simply need to update your SDKs to use the new domain.
diff --git a/cloud/features/git-backed-storage.mdx b/cloud/features/git-backed-storage.mdx
index 0c3e147a..ca33b929 100644
--- a/cloud/features/git-backed-storage.mdx
+++ b/cloud/features/git-backed-storage.mdx
@@ -8,7 +8,7 @@ mode: "wide"
Flipt Cloud is unique in that it uses your existing Git repositories for your feature flags and configurations. This means that your feature flag data is stored in a Git repository of your choosing, which allows you to use your existing Git workflow and tools.
-
+
Flipt Cloud manages your feature flags in what we call [Environments](/cloud/concepts#environments).
@@ -34,7 +34,7 @@ As developers ourselves, we understand the power of Git. It allows you to review
Because we mirror your flag data in Git, you always have the ability to 'break the glass' and make changes directly to the Git repository if needed.
-
+
We believe that Git is the best way to manage configuration data. We also believe that feature flags are a type of configuration data, and as such, they should be in the same way.
diff --git a/cloud/features/rbac.mdx b/cloud/features/rbac.mdx
index fba91991..98612423 100644
--- a/cloud/features/rbac.mdx
+++ b/cloud/features/rbac.mdx
@@ -6,7 +6,7 @@ mode: "wide"
Role-based access control allows you to define custom roles and permissions for your team members.
-
+
You can create roles with specific permissions, such as read-only access to feature flags or the ability to create new flags. This gives you fine-grained control over who can do what in Flipt Cloud and your Flipt instances.
@@ -24,7 +24,7 @@ Flipt Cloud comes with several built-in roles that you can assign to your team m
- **Editor**: Can create and update most resources, but cannot delete them. Cannot access organization settings.
- **Viewer**: Read-only access to most resources, cannot create or update them. Cannot access organization settings.
-
+
Built-in roles cannot be modified or deleted, but you can create custom roles with specific permissions to meet your organization's needs.
@@ -32,7 +32,7 @@ Built-in roles cannot be modified or deleted, but you can create custom roles wi
You can create custom roles with any permissions you need. For example, you can create a role that allows users to create and update feature flags and segments, but not delete them.
-
+
## Assigning Roles
@@ -43,7 +43,7 @@ You can assign roles to team members after you invite them to your organization
invited to your organization.
-
+
## Role Scope
diff --git a/cloud/features/user-management.mdx b/cloud/features/user-management.mdx
index bbc0cc16..0dc0012d 100644
--- a/cloud/features/user-management.mdx
+++ b/cloud/features/user-management.mdx
@@ -6,11 +6,11 @@ mode: "wide"
Flipt Cloud makes it easy to manage your team members and their permissions. You can invite users in your organization, assign roles, and control access to features and data.
-
+
With features like [Role-Based Access Control](/cloud/features/rbac), you can ensure that team members have the right level of access to the features they need, while keeping sensitive data secure.
-
+
## Just in Time User Provisioning
diff --git a/cloud/features/verified-commits.mdx b/cloud/features/verified-commits.mdx
index 199d33cd..04e38575 100644
--- a/cloud/features/verified-commits.mdx
+++ b/cloud/features/verified-commits.mdx
@@ -8,7 +8,7 @@ Verify Flipt's commits to your GitHub repository with SSH signing keys. This ens
You can learn more about GitHub's commit verification in the [GitHub documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification).
-
+
Verified Commits are only available on our Team plan and above. See our
@@ -21,11 +21,11 @@ To verify commits with Flipt Cloud, we'll need to create a
signing key, as Flipt needs to be able to sign the commits it
creates itself.
-
+
To do this, head to your user settings in Flipt Cloud, and click 'Generate Key'.
-
+
Copy the key as you'll need to add it to GitHub in the next step.
@@ -38,7 +38,7 @@ It must be a signing key, rather than an authentication
key, as we don't want this key to be able to push to your repositories, just to
verify commits.
-
+
## How We Store Your Key
diff --git a/cloud/guides/getting-started.mdx b/cloud/guides/getting-started.mdx
index f80b1601..e85641c9 100644
--- a/cloud/guides/getting-started.mdx
+++ b/cloud/guides/getting-started.mdx
@@ -26,7 +26,7 @@ Before you get started with Flipt Cloud, you need to have the following:
Once you are logged in, you will see the Flipt Cloud dashboard. Click on `Create Environment`.
-
+
@@ -34,7 +34,7 @@ Once you are logged in, you will see the Flipt Cloud dashboard. Click on `Create
Give your environment a name and description to help you identify it later.
-
+
@@ -42,7 +42,7 @@ Give your environment a name and description to help you identify it later.
If you haven't already connected your GitHub account, you'll be prompted to install our GitHub App in your organization.
-
+
Select the repositories you want to allow Flipt Cloud to access, or select all repositories.
@@ -52,7 +52,7 @@ Select the repositories you want to allow Flipt Cloud to access, or select all r
Select the repository you want to store your feature flags and configurations in, or create a new one.
-
+
You can also specify a branch or use the default branch.
@@ -69,7 +69,7 @@ Optionally choose a path for your feature flags and configurations.
You can choose to store your feature flags and configurations in the root of your repository, or in a subdirectory. If it doesn't exist, it will be created.
-
+
@@ -77,7 +77,7 @@ You can choose to store your feature flags and configurations in the root of you
Finally, click on `Done` to create your environment.
-
+
@@ -87,7 +87,7 @@ You will be redirected to the environment dashboard.
Click on your new environment to open up the Flipt UI.
-
+
@@ -95,7 +95,7 @@ Click on your new environment to open up the Flipt UI.
Create a new feature flag by clicking on the `Flags` menu and then clicking on the `New Flag` button.
- 
+ 
See the [Getting Started](/introduction#create-a-flag) guide in Open Source for more information on how to create a feature flag.
@@ -107,7 +107,7 @@ Click on your new environment to open up the Flipt UI.
Go to your repository in GitHub and you will see the feature flag you created.
- 
+ 
The feature flag will be stored in the path you specified, or in the root of your repository if you didn't specify a path.
@@ -116,7 +116,7 @@ Click on your new environment to open up the Flipt UI.
in your repository.
- 
+ 
diff --git a/cloud/guides/production.mdx b/cloud/guides/production.mdx
index 66a1e801..8d211474 100644
--- a/cloud/guides/production.mdx
+++ b/cloud/guides/production.mdx
@@ -34,7 +34,7 @@ From the Flipt Cloud dashboard, find the environment you want to create an API k
Click on the `Edit` link.
-
+
@@ -42,7 +42,7 @@ Click on the `Edit` link.
Click on the `Security` tab and then click on the `Create API Key` button.
-
+
@@ -50,11 +50,11 @@ Click on the `Security` tab and then click on the `Create API Key` button.
Give your API a name to help you identify it later and click on the `Create` button.
-
+
Copy the API key to your clipboard and save it in a secure location. You will not be able to access the API key after you leave this page.
-
+
diff --git a/images/cloud/architecture/client-evaluation-cloud-dark.svg b/cloud/images/architecture/client-evaluation-cloud-dark.svg
similarity index 100%
rename from images/cloud/architecture/client-evaluation-cloud-dark.svg
rename to cloud/images/architecture/client-evaluation-cloud-dark.svg
diff --git a/images/cloud/architecture/client-evaluation-cloud-light.svg b/cloud/images/architecture/client-evaluation-cloud-light.svg
similarity index 100%
rename from images/cloud/architecture/client-evaluation-cloud-light.svg
rename to cloud/images/architecture/client-evaluation-cloud-light.svg
diff --git a/images/cloud/architecture/client-evaluation-cloud.d2 b/cloud/images/architecture/client-evaluation-cloud.d2
similarity index 100%
rename from images/cloud/architecture/client-evaluation-cloud.d2
rename to cloud/images/architecture/client-evaluation-cloud.d2
diff --git a/images/cloud/architecture/client-evaluation-self-hosted-dark.svg b/cloud/images/architecture/client-evaluation-self-hosted-dark.svg
similarity index 100%
rename from images/cloud/architecture/client-evaluation-self-hosted-dark.svg
rename to cloud/images/architecture/client-evaluation-self-hosted-dark.svg
diff --git a/images/cloud/architecture/client-evaluation-self-hosted-light.svg b/cloud/images/architecture/client-evaluation-self-hosted-light.svg
similarity index 100%
rename from images/cloud/architecture/client-evaluation-self-hosted-light.svg
rename to cloud/images/architecture/client-evaluation-self-hosted-light.svg
diff --git a/images/cloud/architecture/client-evaluation-self-hosted.d2 b/cloud/images/architecture/client-evaluation-self-hosted.d2
similarity index 100%
rename from images/cloud/architecture/client-evaluation-self-hosted.d2
rename to cloud/images/architecture/client-evaluation-self-hosted.d2
diff --git a/images/cloud/architecture/overview-dark.svg b/cloud/images/architecture/overview-dark.svg
similarity index 100%
rename from images/cloud/architecture/overview-dark.svg
rename to cloud/images/architecture/overview-dark.svg
diff --git a/images/cloud/architecture/overview-light.svg b/cloud/images/architecture/overview-light.svg
similarity index 100%
rename from images/cloud/architecture/overview-light.svg
rename to cloud/images/architecture/overview-light.svg
diff --git a/images/cloud/architecture/overview.d2 b/cloud/images/architecture/overview.d2
similarity index 100%
rename from images/cloud/architecture/overview.d2
rename to cloud/images/architecture/overview.d2
diff --git a/images/cloud/architecture/server-evaluation-self-hosted-dark.svg b/cloud/images/architecture/server-evaluation-self-hosted-dark.svg
similarity index 100%
rename from images/cloud/architecture/server-evaluation-self-hosted-dark.svg
rename to cloud/images/architecture/server-evaluation-self-hosted-dark.svg
diff --git a/images/cloud/architecture/server-evaluation-self-hosted-light.svg b/cloud/images/architecture/server-evaluation-self-hosted-light.svg
similarity index 100%
rename from images/cloud/architecture/server-evaluation-self-hosted-light.svg
rename to cloud/images/architecture/server-evaluation-self-hosted-light.svg
diff --git a/images/cloud/architecture/server-evaluation-self-hosted.d2 b/cloud/images/architecture/server-evaluation-self-hosted.d2
similarity index 100%
rename from images/cloud/architecture/server-evaluation-self-hosted.d2
rename to cloud/images/architecture/server-evaluation-self-hosted.d2
diff --git a/images/cloud/features/approval/approve-pull-request.png b/cloud/images/features/approval/approve-pull-request.png
similarity index 100%
rename from images/cloud/features/approval/approve-pull-request.png
rename to cloud/images/features/approval/approve-pull-request.png
diff --git a/images/cloud/features/approval/create-branch-dialog.png b/cloud/images/features/approval/create-branch-dialog.png
similarity index 100%
rename from images/cloud/features/approval/create-branch-dialog.png
rename to cloud/images/features/approval/create-branch-dialog.png
diff --git a/images/cloud/features/approval/create-proposal-dialog.png b/cloud/images/features/approval/create-proposal-dialog.png
similarity index 100%
rename from images/cloud/features/approval/create-proposal-dialog.png
rename to cloud/images/features/approval/create-proposal-dialog.png
diff --git a/images/cloud/features/approval/deployed-changes.png b/cloud/images/features/approval/deployed-changes.png
similarity index 100%
rename from images/cloud/features/approval/deployed-changes.png
rename to cloud/images/features/approval/deployed-changes.png
diff --git a/images/cloud/features/approval/proposal-merged.png b/cloud/images/features/approval/proposal-merged.png
similarity index 100%
rename from images/cloud/features/approval/proposal-merged.png
rename to cloud/images/features/approval/proposal-merged.png
diff --git a/images/cloud/features/approval/proposal-pending.png b/cloud/images/features/approval/proposal-pending.png
similarity index 100%
rename from images/cloud/features/approval/proposal-pending.png
rename to cloud/images/features/approval/proposal-pending.png
diff --git a/images/cloud/features/approval/proposal-pull-request.png b/cloud/images/features/approval/proposal-pull-request.png
similarity index 100%
rename from images/cloud/features/approval/proposal-pull-request.png
rename to cloud/images/features/approval/proposal-pull-request.png
diff --git a/images/cloud/features/approval/protected-badge.png b/cloud/images/features/approval/protected-badge.png
similarity index 100%
rename from images/cloud/features/approval/protected-badge.png
rename to cloud/images/features/approval/protected-badge.png
diff --git a/images/cloud/features/approval/protected-environment.png b/cloud/images/features/approval/protected-environment.png
similarity index 100%
rename from images/cloud/features/approval/protected-environment.png
rename to cloud/images/features/approval/protected-environment.png
diff --git a/images/cloud/features/approval/unprotected-environment.png b/cloud/images/features/approval/unprotected-environment.png
similarity index 100%
rename from images/cloud/features/approval/unprotected-environment.png
rename to cloud/images/features/approval/unprotected-environment.png
diff --git a/images/cloud/features/auth/api-access.png b/cloud/images/features/auth/api-access.png
similarity index 100%
rename from images/cloud/features/auth/api-access.png
rename to cloud/images/features/auth/api-access.png
diff --git a/images/cloud/features/auth/api-key.png b/cloud/images/features/auth/api-key.png
similarity index 100%
rename from images/cloud/features/auth/api-key.png
rename to cloud/images/features/auth/api-key.png
diff --git a/images/cloud/features/auth/login.png b/cloud/images/features/auth/login.png
similarity index 100%
rename from images/cloud/features/auth/login.png
rename to cloud/images/features/auth/login.png
diff --git a/images/cloud/features/auth/sso.gif b/cloud/images/features/auth/sso.gif
similarity index 100%
rename from images/cloud/features/auth/sso.gif
rename to cloud/images/features/auth/sso.gif
diff --git a/images/cloud/features/domains/client-evaluation-cloud-dark.svg b/cloud/images/features/domains/client-evaluation-cloud-dark.svg
similarity index 100%
rename from images/cloud/features/domains/client-evaluation-cloud-dark.svg
rename to cloud/images/features/domains/client-evaluation-cloud-dark.svg
diff --git a/images/cloud/features/domains/client-evaluation-cloud-light.svg b/cloud/images/features/domains/client-evaluation-cloud-light.svg
similarity index 100%
rename from images/cloud/features/domains/client-evaluation-cloud-light.svg
rename to cloud/images/features/domains/client-evaluation-cloud-light.svg
diff --git a/images/cloud/features/domains/client-evaluation-cloud.d2 b/cloud/images/features/domains/client-evaluation-cloud.d2
similarity index 100%
rename from images/cloud/features/domains/client-evaluation-cloud.d2
rename to cloud/images/features/domains/client-evaluation-cloud.d2
diff --git a/images/cloud/features/domains/dns-configuration.png b/cloud/images/features/domains/dns-configuration.png
similarity index 100%
rename from images/cloud/features/domains/dns-configuration.png
rename to cloud/images/features/domains/dns-configuration.png
diff --git a/images/cloud/features/domains/environment-domain.png b/cloud/images/features/domains/environment-domain.png
similarity index 100%
rename from images/cloud/features/domains/environment-domain.png
rename to cloud/images/features/domains/environment-domain.png
diff --git a/images/cloud/features/git/feature-flag-in-repository.png b/cloud/images/features/git/feature-flag-in-repository.png
similarity index 100%
rename from images/cloud/features/git/feature-flag-in-repository.png
rename to cloud/images/features/git/feature-flag-in-repository.png
diff --git a/images/cloud/features/git/feature-flag-in-ui.png b/cloud/images/features/git/feature-flag-in-ui.png
similarity index 100%
rename from images/cloud/features/git/feature-flag-in-ui.png
rename to cloud/images/features/git/feature-flag-in-ui.png
diff --git a/images/cloud/features/rbac/roles-assign.png b/cloud/images/features/rbac/roles-assign.png
similarity index 100%
rename from images/cloud/features/rbac/roles-assign.png
rename to cloud/images/features/rbac/roles-assign.png
diff --git a/images/cloud/features/rbac/roles-built-in.png b/cloud/images/features/rbac/roles-built-in.png
similarity index 100%
rename from images/cloud/features/rbac/roles-built-in.png
rename to cloud/images/features/rbac/roles-built-in.png
diff --git a/images/cloud/features/rbac/roles-custom.png b/cloud/images/features/rbac/roles-custom.png
similarity index 100%
rename from images/cloud/features/rbac/roles-custom.png
rename to cloud/images/features/rbac/roles-custom.png
diff --git a/images/cloud/features/rbac/roles.png b/cloud/images/features/rbac/roles.png
similarity index 100%
rename from images/cloud/features/rbac/roles.png
rename to cloud/images/features/rbac/roles.png
diff --git a/images/cloud/features/users/invite.png b/cloud/images/features/users/invite.png
similarity index 100%
rename from images/cloud/features/users/invite.png
rename to cloud/images/features/users/invite.png
diff --git a/images/cloud/features/users/team.png b/cloud/images/features/users/team.png
similarity index 100%
rename from images/cloud/features/users/team.png
rename to cloud/images/features/users/team.png
diff --git a/images/cloud/features/verified-commits/add-signing-key.png b/cloud/images/features/verified-commits/add-signing-key.png
similarity index 100%
rename from images/cloud/features/verified-commits/add-signing-key.png
rename to cloud/images/features/verified-commits/add-signing-key.png
diff --git a/images/cloud/features/verified-commits/commits.png b/cloud/images/features/verified-commits/commits.png
similarity index 100%
rename from images/cloud/features/verified-commits/commits.png
rename to cloud/images/features/verified-commits/commits.png
diff --git a/images/cloud/features/verified-commits/generate-key.png b/cloud/images/features/verified-commits/generate-key.png
similarity index 100%
rename from images/cloud/features/verified-commits/generate-key.png
rename to cloud/images/features/verified-commits/generate-key.png
diff --git a/images/cloud/features/verified-commits/signing-key.png b/cloud/images/features/verified-commits/signing-key.png
similarity index 100%
rename from images/cloud/features/verified-commits/signing-key.png
rename to cloud/images/features/verified-commits/signing-key.png
diff --git a/images/cloud/guides/getting-started/authorize-github.png b/cloud/images/guides/getting-started/authorize-github.png
similarity index 100%
rename from images/cloud/guides/getting-started/authorize-github.png
rename to cloud/images/guides/getting-started/authorize-github.png
diff --git a/images/cloud/guides/getting-started/choose-path.png b/cloud/images/guides/getting-started/choose-path.png
similarity index 100%
rename from images/cloud/guides/getting-started/choose-path.png
rename to cloud/images/guides/getting-started/choose-path.png
diff --git a/images/cloud/guides/getting-started/create-flag.png b/cloud/images/guides/getting-started/create-flag.png
similarity index 100%
rename from images/cloud/guides/getting-started/create-flag.png
rename to cloud/images/guides/getting-started/create-flag.png
diff --git a/images/cloud/guides/getting-started/dashboard.png b/cloud/images/guides/getting-started/dashboard.png
similarity index 100%
rename from images/cloud/guides/getting-started/dashboard.png
rename to cloud/images/guides/getting-started/dashboard.png
diff --git a/images/cloud/guides/getting-started/done.png b/cloud/images/guides/getting-started/done.png
similarity index 100%
rename from images/cloud/guides/getting-started/done.png
rename to cloud/images/guides/getting-started/done.png
diff --git a/images/cloud/guides/getting-started/environment-form.png b/cloud/images/guides/getting-started/environment-form.png
similarity index 100%
rename from images/cloud/guides/getting-started/environment-form.png
rename to cloud/images/guides/getting-started/environment-form.png
diff --git a/images/cloud/guides/getting-started/feature-flag-in-repository.png b/cloud/images/guides/getting-started/feature-flag-in-repository.png
similarity index 100%
rename from images/cloud/guides/getting-started/feature-flag-in-repository.png
rename to cloud/images/guides/getting-started/feature-flag-in-repository.png
diff --git a/images/cloud/guides/getting-started/flipt-ui.png b/cloud/images/guides/getting-started/flipt-ui.png
similarity index 100%
rename from images/cloud/guides/getting-started/flipt-ui.png
rename to cloud/images/guides/getting-started/flipt-ui.png
diff --git a/images/cloud/guides/getting-started/repository.png b/cloud/images/guides/getting-started/repository.png
similarity index 100%
rename from images/cloud/guides/getting-started/repository.png
rename to cloud/images/guides/getting-started/repository.png
diff --git a/images/cloud/guides/getting-started/select-repository.png b/cloud/images/guides/getting-started/select-repository.png
similarity index 100%
rename from images/cloud/guides/getting-started/select-repository.png
rename to cloud/images/guides/getting-started/select-repository.png
diff --git a/images/cloud/guides/production/api-key-created.png b/cloud/images/guides/production/api-key-created.png
similarity index 100%
rename from images/cloud/guides/production/api-key-created.png
rename to cloud/images/guides/production/api-key-created.png
diff --git a/images/cloud/guides/production/edit-environment.png b/cloud/images/guides/production/edit-environment.png
similarity index 100%
rename from images/cloud/guides/production/edit-environment.png
rename to cloud/images/guides/production/edit-environment.png
diff --git a/images/cloud/guides/production/name-api-key.png b/cloud/images/guides/production/name-api-key.png
similarity index 100%
rename from images/cloud/guides/production/name-api-key.png
rename to cloud/images/guides/production/name-api-key.png
diff --git a/images/cloud/guides/production/security.png b/cloud/images/guides/production/security.png
similarity index 100%
rename from images/cloud/guides/production/security.png
rename to cloud/images/guides/production/security.png
diff --git a/configuration/telemetry.mdx b/configuration/telemetry.mdx
index a49b8d9d..9d46345d 100644
--- a/configuration/telemetry.mdx
+++ b/configuration/telemetry.mdx
@@ -19,9 +19,9 @@ Telemetry is only collected when Flipt is running, **once at startup** and then
- Cache backend (i.e.: Redis)
- Authentication methods (i.e.: OIDC)
-We use [Segment](https://segment.com) to collect the data. Only the Flipt team has access to the raw data.
+We use [Jitsu](https://jitsu.com/) to collect the data. Only the Flipt team has access to the raw data.
-Here is an example of the telemetry data sent to Segment:
+Here is an example of the telemetry data sent to Jitsu:
```json
{
diff --git a/docs.json b/docs.json
index f6c328f2..c83aa86c 100644
--- a/docs.json
+++ b/docs.json
@@ -9,197 +9,326 @@
},
"favicon": "/favicon.svg",
"navigation": {
- "anchors": [
+ "versions": [
{
- "anchor": "Open Source",
- "icon": "book-open",
+ "version": "v1",
"tabs": [
{
"tab": "Open Source",
- "groups": [
- {
- "group": "Overview",
- "pages": ["introduction", "concepts"]
- },
- {
- "group": "Use Cases",
- "pages": [
- "usecases/overview",
- "usecases/cloudnative",
- "usecases/edge",
- "usecases/gitops"
- ]
- },
+ "anchors": [
{
- "group": "Installation",
- "pages": [
- "installation/overview",
- "installation/docker",
- "installation/kubernetes"
- ]
- },
- {
- "group": "Integration",
- "pages": [
- "integration/overview",
+ "anchor": "Documentation",
+ "icon": "book-open",
+ "groups": [
{
- "group": "Server-Side SDKs",
+ "group": "Overview",
+ "pages": ["introduction", "concepts"]
+ },
+ {
+ "group": "Use Cases",
"pages": [
- "integration/server/rest",
- "integration/server/grpc"
+ "usecases/overview",
+ "usecases/cloudnative",
+ "usecases/edge",
+ "usecases/gitops"
]
},
- "integration/client",
- "integration/openfeature",
- "integration/examples"
- ]
- },
- {
- "group": "Guides",
- "pages": [
{
- "group": "User Guides",
+ "group": "Installation",
"pages": [
- "guides/user/get-going-with-gitops",
- "guides/user/using-references"
+ "installation/overview",
+ "installation/docker",
+ "installation/kubernetes"
+ ]
+ },
+ {
+ "group": "Integration",
+ "pages": [
+ "integration/overview",
+ {
+ "group": "Server-Side SDKs",
+ "pages": [
+ "integration/server/rest",
+ "integration/server/grpc"
+ ]
+ },
+ "integration/client",
+ "integration/openfeature",
+ "integration/examples"
]
},
{
- "group": "Operations Guides",
+ "group": "Guides",
"pages": [
{
- "group": "Deployment",
+ "group": "User Guides",
"pages": [
- "guides/operation/deployment/deploy-to-flyio",
- "guides/operation/deployment/deploy-to-kubernetes"
+ "guides/user/get-going-with-gitops",
+ "guides/user/using-references"
]
},
{
- "group": "Authentication",
+ "group": "Operations Guides",
"pages": [
- "guides/operation/authentication/login-with-google",
- "guides/operation/authentication/login-with-github",
- "guides/operation/authentication/login-with-keycloak"
+ {
+ "group": "Deployment",
+ "pages": [
+ "guides/operation/deployment/deploy-to-flyio",
+ "guides/operation/deployment/deploy-to-kubernetes"
+ ]
+ },
+ {
+ "group": "Authentication",
+ "pages": [
+ "guides/operation/authentication/login-with-google",
+ "guides/operation/authentication/login-with-github",
+ "guides/operation/authentication/login-with-keycloak"
+ ]
+ },
+ {
+ "group": "Authorization",
+ "pages": [
+ "guides/operation/authorization/rbac-with-keycloak"
+ ]
+ }
]
},
{
- "group": "Authorization",
+ "group": "Migration Guides",
"pages": [
- "guides/operation/authorization/rbac-with-keycloak"
+ "guides/migration/launchdarkly/overview",
+ "guides/migration/launchdarkly/openfeature",
+ "guides/migration/launchdarkly/flipt"
]
}
]
},
{
- "group": "Migration Guides",
+ "group": "Configuration",
+ "pages": [
+ "configuration/overview",
+ "configuration/analytics",
+ {
+ "group": "Auditing",
+ "pages": [
+ "configuration/auditing/overview",
+ "configuration/auditing/webhooks"
+ ]
+ },
+ "configuration/authentication",
+ "configuration/authorization",
+ "configuration/observability",
+ "configuration/storage",
+ "configuration/caching",
+ "configuration/telemetry",
+ "configuration/experimental"
+ ]
+ },
+ {
+ "group": "CLI",
+ "pages": [
+ "cli/overview",
+ {
+ "group": "Commands",
+ "pages": [
+ {
+ "group": "config",
+ "pages": [
+ "cli/commands/config/init",
+ "cli/commands/config/edit"
+ ]
+ },
+ {
+ "group": "bundle",
+ "pages": [
+ "cli/commands/bundle/build",
+ "cli/commands/bundle/list",
+ "cli/commands/bundle/pull",
+ "cli/commands/bundle/push"
+ ]
+ },
+ "cli/commands/evaluate",
+ "cli/commands/export",
+ "cli/commands/import",
+ "cli/commands/migrate",
+ "cli/commands/validate"
+ ]
+ }
+ ]
+ },
+ {
+ "group": "Authentication",
+ "pages": [
+ "authentication/overview",
+ "authentication/methods",
+ "authentication/using-tokens",
+ "authentication/using-jwts"
+ ]
+ },
+ {
+ "group": "Authorization",
+ "pages": ["authorization/overview"]
+ },
+ {
+ "group": "Operations",
+ "pages": [
+ "operations/architecture",
+ "operations/deployment",
+ "operations/import-export",
+ "operations/production",
+ "operations/upgrading"
+ ]
+ },
+ {
+ "group": "Tooling",
"pages": [
- "guides/migration/launchdarkly/overview",
- "guides/migration/launchdarkly/openfeature",
- "guides/migration/launchdarkly/flipt"
+ "tooling/github-actions",
+ "tooling/model-context-protocol"
]
}
]
},
{
- "group": "Configuration",
- "pages": [
- "configuration/overview",
- "configuration/analytics",
+ "anchor": "API Reference",
+ "icon": "code",
+ "groups": [
+ {
+ "group": "Overview",
+ "pages": ["reference/overview"]
+ },
{
- "group": "Auditing",
+ "group": "Authentication",
"pages": [
- "configuration/auditing/overview",
- "configuration/auditing/webhooks"
+ "reference/authentication/list-tokens",
+ "reference/authentication/get-token",
+ "reference/authentication/delete-token",
+ "reference/authentication/create-token",
+ "reference/authentication/get-self",
+ "reference/authentication/expire-self"
]
},
- "configuration/authentication",
- "configuration/authorization",
- "configuration/observability",
- "configuration/storage",
- "configuration/caching",
- "configuration/telemetry",
- "configuration/experimental"
- ]
- },
- {
- "group": "CLI",
- "pages": [
- "cli/overview",
{
- "group": "Commands",
+ "group": "Evaluation",
"pages": [
- {
- "group": "config",
- "pages": [
- "cli/commands/config/init",
- "cli/commands/config/edit"
- ]
- },
- {
- "group": "bundle",
- "pages": [
- "cli/commands/bundle/build",
- "cli/commands/bundle/list",
- "cli/commands/bundle/pull",
- "cli/commands/bundle/push"
- ]
- },
- "cli/commands/evaluate",
- "cli/commands/export",
- "cli/commands/import",
- "cli/commands/migrate",
- "cli/commands/validate"
+ "reference/evaluation/boolean-evaluation",
+ "reference/evaluation/variant-evaluation",
+ "reference/evaluation/batch-evaluation"
+ ]
+ },
+ {
+ "group": "OpenFeature Evaluation",
+ "pages": [
+ "reference/openfeature/overview",
+ "reference/openfeature/configuration",
+ "reference/openfeature/flag-evaluation",
+ "reference/openfeature/bulk-evaluation"
+ ]
+ },
+ {
+ "group": "Namespaces",
+ "pages": [
+ "reference/namespaces/list-namespaces",
+ "reference/namespaces/create-namespace",
+ "reference/namespaces/get-namespace",
+ "reference/namespaces/delete-namespace",
+ "reference/namespaces/update-namespace"
+ ]
+ },
+ {
+ "group": "Flags",
+ "pages": [
+ "reference/flags/list-flags",
+ "reference/flags/create-flag",
+ "reference/flags/get-flag",
+ "reference/flags/delete-flag",
+ "reference/flags/update-flag"
+ ]
+ },
+ {
+ "group": "Variants",
+ "pages": [
+ "reference/variants/create-variant",
+ "reference/variants/delete-variant",
+ "reference/variants/update-variant"
+ ]
+ },
+ {
+ "group": "Segments",
+ "pages": [
+ "reference/segments/list-segment",
+ "reference/segments/create-segment",
+ "reference/segments/get-segment",
+ "reference/segments/delete-segment",
+ "reference/segments/update-segment"
+ ]
+ },
+ {
+ "group": "Constraints",
+ "pages": [
+ "reference/constraints/create-constraint",
+ "reference/constraints/delete-constraint",
+ "reference/constraints/update-constraint"
+ ]
+ },
+ {
+ "group": "Rollouts",
+ "pages": [
+ "reference/rollouts/list-rollouts",
+ "reference/rollouts/create-rollout",
+ "reference/rollouts/order-rollouts",
+ "reference/rollouts/get-rollout",
+ "reference/rollouts/delete-rollout",
+ "reference/rollouts/update-rollout"
+ ]
+ },
+ {
+ "group": "Rules",
+ "pages": [
+ "reference/rules/list-rules",
+ "reference/rules/create-rule",
+ "reference/rules/order-rules",
+ "reference/rules/get-rule",
+ "reference/rules/delete-rule",
+ "reference/rules/update-rule"
+ ]
+ },
+ {
+ "group": "Distributions",
+ "pages": [
+ "reference/distributions/create-distribution",
+ "reference/distributions/delete-distribution",
+ "reference/distributions/update-distribution"
]
}
]
},
{
- "group": "Authentication",
- "pages": [
- "authentication/overview",
- "authentication/methods",
- "authentication/using-tokens",
- "authentication/using-jwts"
- ]
+ "anchor": "Changelog",
+ "icon": "clock",
+ "pages": ["changelog/overview"]
},
{
- "group": "Authorization",
- "pages": ["authorization/overview"]
+ "anchor": "Blog",
+ "href": "https://blog.flipt.io",
+ "icon": "newspaper"
},
{
- "group": "Operations",
- "pages": [
- "operations/architecture",
- "operations/deployment",
- "operations/import-export",
- "operations/production",
- "operations/upgrading"
- ]
+ "anchor": "Community",
+ "href": "https://community.flipt.io",
+ "icon": "discourse"
},
{
- "group": "Tooling",
- "pages": [
- "tooling/github-actions",
- "tooling/model-context-protocol"
- ]
- }
- ]
- },
- {
- "tab": "Changelog",
- "groups": [
+ "anchor": "Discord",
+ "href": "https://flipt.io/discord",
+ "icon": "discord"
+ },
{
- "group": "Changelog",
- "pages": ["changelog/overview"]
+ "anchor": "GitHub",
+ "href": "https://git.new/flipt",
+ "icon": "github"
}
]
- }
- ]
- },
- {
- "anchor": "Flipt Cloud",
- "icon": "cloud",
- "tabs": [
+ },
{
"tab": "Flipt Cloud",
"groups": [
@@ -237,143 +366,94 @@
]
},
{
- "anchor": "API Reference",
- "icon": "code",
+ "version": "v2",
"tabs": [
{
- "tab": "API Reference",
- "groups": [
- {
- "group": "Overview",
- "pages": ["reference/overview"]
- },
- {
- "group": "Authentication",
- "pages": [
- "reference/authentication/list-tokens",
- "reference/authentication/get-token",
- "reference/authentication/delete-token",
- "reference/authentication/create-token",
- "reference/authentication/get-self",
- "reference/authentication/expire-self"
- ]
- },
- {
- "group": "Evaluation",
- "pages": [
- "reference/evaluation/boolean-evaluation",
- "reference/evaluation/variant-evaluation",
- "reference/evaluation/batch-evaluation"
- ]
- },
- {
- "group": "OpenFeature Evaluation",
- "pages": [
- "reference/openfeature/overview",
- "reference/openfeature/configuration",
- "reference/openfeature/flag-evaluation",
- "reference/openfeature/bulk-evaluation"
- ]
- },
+ "tab": "Open Source",
+ "icon": "book-open",
+ "anchors": [
{
- "group": "Namespaces",
- "pages": [
- "reference/namespaces/list-namespaces",
- "reference/namespaces/create-namespace",
- "reference/namespaces/get-namespace",
- "reference/namespaces/delete-namespace",
- "reference/namespaces/update-namespace"
+ "anchor": "Documentation",
+ "groups": [
+ {
+ "group": "Overview",
+ "pages": [
+ "/v2/introduction",
+ "/v2/quickstart",
+ "/v2/concepts"
+ ]
+ },
+ {
+ "group": "Configuration",
+ "pages": [
+ "v2/configuration/overview",
+ "v2/configuration/environments",
+ "v2/configuration/storage",
+ "v2/configuration/authentication",
+ "v2/configuration/authorization",
+ "v2/configuration/observability",
+ "v2/configuration/telemetry"
+ ]
+ }
]
},
{
- "group": "Flags",
- "pages": [
- "reference/flags/list-flags",
- "reference/flags/create-flag",
- "reference/flags/get-flag",
- "reference/flags/delete-flag",
- "reference/flags/update-flag"
- ]
+ "anchor": "Blog",
+ "href": "https://blog.flipt.io",
+ "icon": "newspaper"
},
{
- "group": "Variants",
- "pages": [
- "reference/variants/create-variant",
- "reference/variants/delete-variant",
- "reference/variants/update-variant"
- ]
+ "anchor": "Community",
+ "href": "https://community.flipt.io",
+ "icon": "discourse"
},
{
- "group": "Segments",
- "pages": [
- "reference/segments/list-segment",
- "reference/segments/create-segment",
- "reference/segments/get-segment",
- "reference/segments/delete-segment",
- "reference/segments/update-segment"
- ]
+ "anchor": "Discord",
+ "href": "https://flipt.io/discord",
+ "icon": "discord"
},
{
- "group": "Constraints",
- "pages": [
- "reference/constraints/create-constraint",
- "reference/constraints/delete-constraint",
- "reference/constraints/update-constraint"
- ]
- },
+ "anchor": "GitHub",
+ "href": "https://git.new/flipt",
+ "icon": "github"
+ }
+ ]
+ },
+ {
+ "tab": "Flipt Cloud",
+ "groups": [
{
- "group": "Rollouts",
+ "group": "Overview",
"pages": [
- "reference/rollouts/list-rollouts",
- "reference/rollouts/create-rollout",
- "reference/rollouts/order-rollouts",
- "reference/rollouts/get-rollout",
- "reference/rollouts/delete-rollout",
- "reference/rollouts/update-rollout"
+ "cloud/overview",
+ "cloud/benefits",
+ "cloud/concepts",
+ "cloud/architecture"
]
},
{
- "group": "Rules",
+ "group": "Features",
"pages": [
- "reference/rules/list-rules",
- "reference/rules/create-rule",
- "reference/rules/order-rules",
- "reference/rules/get-rule",
- "reference/rules/delete-rule",
- "reference/rules/update-rule"
+ "cloud/features/authentication",
+ "cloud/features/git-backed-storage",
+ "cloud/features/approval-workflows",
+ "cloud/features/rbac",
+ "cloud/features/user-management",
+ "cloud/features/verified-commits",
+ "cloud/features/custom-domains"
]
},
{
- "group": "Distributions",
+ "group": "Guides",
"pages": [
- "reference/distributions/create-distribution",
- "reference/distributions/delete-distribution",
- "reference/distributions/update-distribution"
+ "cloud/guides/getting-started",
+ "cloud/guides/production",
+ "cloud/guides/configuring-environments"
]
}
]
}
]
- },
- {
- "anchor": "Blog",
- "href": "https://blog.flipt.io",
- "icon": "newspaper"
- },
- {
- "anchor": "Community",
- "href": "https://community.flipt.io",
- "icon": "discourse"
- },
- {
- "anchor": "Discord",
- "href": "https://flipt.io/discord",
- "icon": "discord"
- },
- {
- "anchor": "GitHub",
- "href": "https://git.new/flipt",
- "icon": "github"
}
]
},
@@ -424,56 +504,12 @@
},
"redirects": [
{
- "source": "/experimental/filesystem-backends",
- "destination": "/configuration/storage"
- },
- {
- "source": "/self-hosted",
- "destination": "/installation"
- },
- {
- "source": "/self-hosted/overview",
- "destination": "/installation/overview"
- },
- {
- "source": "/self-hosted/docker",
- "destination": "/installation/docker"
- },
- {
- "source": "/self-hosted/kubernetes",
- "destination": "/installation/kubernetes"
- },
- {
- "source": "/integration/rest",
- "destination": "/integration/server/rest"
- },
- {
- "source": "/integration/grpc",
- "destination": "/integration/server/grpc"
- },
- {
- "source": "/guides/get-going-with-gitops",
- "destination": "/guides/user/get-going-with-gitops"
- },
- {
- "source": "/guides/using-references",
- "destination": "/guides/user/using-references"
- },
- {
- "source": "/guides/deploy-to-flyio",
- "destination": "/guides/operation/deployment/deploy-to-flyio"
- },
- {
- "source": "/guides/deploy-to-kubernetes",
- "destination": "/guides/operation/deployment/deploy-to-kubernetes"
- },
- {
- "source": "/guides/login-with-google",
- "destination": "/guides/operation/authentication/login-with-google"
+ "source": "/self-hosted/:slug*",
+ "destination": "/installation/:slug*"
},
{
- "source": "/guides/login-with-github",
- "destination": "/guides/operation/authentication/login-with-github"
+ "source": "/integration/:slug*",
+ "destination": "/integration/server/:slug*"
}
]
}
diff --git a/introduction.mdx b/introduction.mdx
index d22601ba..b89181d2 100644
--- a/introduction.mdx
+++ b/introduction.mdx
@@ -10,14 +10,9 @@ simulate an evaluation request from your applications.
For more information on any of the concepts described, please see the
[Concepts](/concepts) documentation.
-
- Flipt Cloud is a fully managed feature management platform that
- enables you to continue to use Flipt's feature management capabilities with
- zero maintenance.
+import Cloud from "/snippets/cloud.mdx";
-Own your feature data, backed by Git.
-
-
+
## Setup
diff --git a/scripts/linkreplace.py b/scripts/linkreplace.py
new file mode 100755
index 00000000..df5eba0a
--- /dev/null
+++ b/scripts/linkreplace.py
@@ -0,0 +1,36 @@
+import argparse
+import os
+import re
+
+def replace_links_in_file(filepath: str, from_path: str, to_path: str):
+ with open(filepath, 'r', encoding='utf-8') as f:
+ content = f.read()
+
+ pattern = re.compile(r'(!?\[.*?\])\((%s(?:/[^)]*)?)\)' % re.escape(from_path.rstrip('/')))
+ replaced = pattern.sub(lambda m: f'{m.group(1)}({to_path.rstrip("/")}{m.group(2)[len(from_path.rstrip("/")):]})', content)
+
+ if content != replaced:
+ with open(filepath, 'w', encoding='utf-8') as f:
+ f.write(replaced)
+ print(f"Updated: {filepath}")
+
+def walk_and_process(root_dir: str, from_path: str, to_path: str):
+ for dirpath, _, filenames in os.walk(root_dir):
+ for fname in filenames:
+ if fname.endswith('.mdx'):
+ replace_links_in_file(os.path.join(dirpath, fname), from_path, to_path)
+
+def main():
+ parser = argparse.ArgumentParser(description="Replace markdown links that start at a root path.")
+ parser.add_argument('--from', dest='from_path', required=True, help="Root-relative path to replace (e.g., /v1)")
+ parser.add_argument('--to', dest='to_path', required=True, help="Replacement path (e.g., /v2)")
+ parser.add_argument('--dir', dest='directory', default='.', help="Directory to process recursively (default: current)")
+ args = parser.parse_args()
+
+ walk_and_process(args.directory, args.from_path, args.to_path)
+
+if __name__ == '__main__':
+ main()
+
+
+# python linkreplace.py --from /v1 --to /v2 --dir ./docs
\ No newline at end of file
diff --git a/snippets/cloud.mdx b/snippets/cloud.mdx
new file mode 100644
index 00000000..b77a6eda
--- /dev/null
+++ b/snippets/cloud.mdx
@@ -0,0 +1,8 @@
+
+ Flipt Cloud is a fully managed feature management platform that
+ enables you to continue to use Flipt's feature management capabilities with
+ zero maintenance.
+
+Own your feature data, backed by Git.
+
+
diff --git a/snippets/v2-alpha.mdx b/snippets/v2-alpha.mdx
new file mode 100644
index 00000000..d3acc15b
--- /dev/null
+++ b/snippets/v2-alpha.mdx
@@ -0,0 +1,7 @@
+
+ Flipt v2 is currently in **Alpha** and is not recommended for production use.
+
+These docs are a work in progress and incomplete. We are working hard to
+improve the docs and make Flipt v2 available for production use.
+
+
diff --git a/v2/concepts.mdx b/v2/concepts.mdx
new file mode 100644
index 00000000..5da84547
--- /dev/null
+++ b/v2/concepts.mdx
@@ -0,0 +1,323 @@
+---
+title: Concepts
+description: This document describes the basic concepts of Flipt v2.
+---
+
+import V2Alpha from "/snippets/v2-alpha.mdx";
+
+
+
+More information on how to use Flipt is noted in the [Quickstart](/v2/quickstart) documentation.
+
+## Environments
+
+Environments are a new concept in Flipt v2. They are a way to organize your namespaces, feature flags and configurations and keep them separate from each other.
+
+By default, Flipt v2 will create a single environment called `default` along with the `default` namespace.
+
+
+Environments are managed via configuration files as they are also coupled to how you store your configuration data. See the [Environments](/v2/configuration#environments) documentation for more.
+
+
+All data created in one environment is only accessible within that environment, meaning namespaces, flags, segments, etc must be created in each environment in which they're to be used.
+
+If an environment isn't selected then the 'Default' environment is used.
+
+
+
+You can create as many environments as you want. Each environment can have its own namespaces, feature flags and configurations.
+
+## Namespaces
+
+Namespaces are a way to organize your feature flags and configurations within an environment.
+
+One common use-case of Namespaces is to separate Flipt data by internal team.
+
+
+All data created in one namespace is only accessible within that namespace, meaning flags, segments, etc must be created in each namespace in which they're to be used.
+
+If a namespace isn't selected then the 'Default' namespace is used.
+
+
+
+Namespaces can be managed within the `Settings` section of the Flipt UI:
+
+
+
+## Flags
+
+Flags are the basic unit in the Flipt ecosystem. Flags represent experiments or
+features that you want to be able to enable or disable for users of your
+applications.
+
+For example, a flag named `New Contact Page` could be used to determine whether
+or not a given user sees the latest version of a 'Contact Us' page that you are
+working on when they visit your homepage.
+
+Flags can be used as simple on/off toggles or with variants and rules to support
+more elaborate use cases.
+
+
+
+There are two types of flags:
+
+- **Variant** which allows you to return a single variant for a given flag given a set of evaluation rules. This is the default flag type.
+- **Boolean** which allows you to return a boolean value for a given flag.
+
+### Variant Flags
+
+Variants are options for flags. For example, if you have a flag `Colorscheme`
+that determines which main colors your users see when they login to your
+application, then possible variants could include `dark`, `light` or `auto`.
+
+
+
+#### Variant Attachments
+
+Variants can also have JSON attachments. This allows you to store additional
+data about a variant that can be used in your application at runtime.
+
+
+
+Variant attachments are not used for evaluation, they are only used for runtime configuration.
+
+The attachment size is limited to **1MB**.
+
+
+
+### Boolean Flags
+
+Boolean flags are a special type of flag that allow you to return a boolean value for a given flag.
+
+You can use boolean flags to determine if a feature is enabled or disabled for a given entity (user, device, etc) by returning `true` or `false` respectively. Boolean flags work well for simple use cases where you don't need to return multiple variants.
+
+Boolean flags can be configured with [rollout](#rollouts) rules to determine which entities receive `true` or `false` for a given flag.
+
+
+
+### Metadata
+
+All flags can have metadata associated with them. This metadata is stored in the Flipt backend and can be used to add additional information about a flag.
+
+Metadata is stored as a JSON object and is not used for evaluation. You can retrieve flag metadata using the [Get Flag](/reference/flags/get-flag) API.
+
+In the Flipt UI, metadata is displayed in the flag details section. The UI allows you to add, edit, and delete metadata and provides a more user-friendly interface for managing metadata by specifying key-value pairs and their data types.
+
+Currently, the following data types are supported:
+
+- Primitive types: `String`, `Number`, `Boolean`
+- Complex types: `Array`, `Object`
+
+
+
+## Segments
+
+Segments allow you to split your user base or audience up into predefined
+slices. This is a powerful feature that enables targeting groups to determine if
+a flag or variant applies to them.
+
+An example segment could be `new-users`.
+
+
+
+Segments are global within a Flipt namespace.
+
+### Match Types
+
+When configuring a segment you can choose a `Match Type` of either:
+
+- **Match All** which requires ALL constraints to match for the segment to apply
+ for evaluation.
+- **Match Any** which requires AT LEAST ONE constraint to match for the segment
+ to apply for evaluation.
+
+### Constraints
+
+Constraints allow you to determine which segment a given entity is a part of.
+
+For example, for a user to fall into the above `new-users` segment, you may want
+to check their `finished_onboarding` property.
+
+
+
+All constraints have a _property_, _type_, _operator_ and optionally a _value_.
+
+#### Constraint Types
+
+Currently 5 constraint types are available:
+
+- **String** which allows you to check a string property of an entity
+- **Number** which allows you to check a number property of an entity (integer or float)
+- **Boolean** which allows you to check a boolean property of an entity such as `true` or `false`
+- **DateTime** which allows you to check a date or datetime property of an entity such as `2020-01-01` or `2020-01-01T00:00:00Z` ([RFC3339](https://datatracker.ietf.org/doc/html/rfc3339))
+- **Entity** which allows you to check the `entityId` that was sent in the body of the `Variant` or `Boolean` request
+
+
+
+
+ The constraint value is represented as a string in transit and in storage,
+ however it's coerced into the appropriate type for evaluation.
+
+
+## Rules
+
+Rules allow you to tie your flags, variants and segments together by specifying
+which segments are targeted by which variants.
+
+Rules can be as simple as `IF IN segment THEN RETURN variant_a` or they can be
+richer by using distribution logic to roll out features on a percentage basis.
+
+Continuing our previous example, we may want to return the flag variant `dark`
+for all entities in the `new-users` segment. This would be configured like so:
+
+
+
+Rules are evaluated in order per their rank from 1-N. The first rule that
+matches wins. Once created, rules can be re-ordered to change how they're
+evaluated.
+
+### Default Rule
+
+If no rules match for a given flag, the default rule value is returned. This value is optional and can be set to any variant that exists for the flag.
+
+
+
+### Distributions
+
+Distributions allow you to return different variants of your flag to different
+percentages of your user base based on your rules.
+
+Let's say that instead of always showing the `dark` variant to your `new-users`
+segment, you want to show `dark` to **10%** of `new-users`, `light` to **30%**, and `auto`
+to the remaining **60%**. You would accomplish this using rules with distributions:
+
+
+
+The ability to manage distributions, as illustrated in the image above, is an extremely powerful feature of Flipt that can help you seamlessly deploy new features of your applications to your users while also limiting the reach of potential bugs.
+
+## Rollouts
+
+Rollouts allow you to potentially change the result of a boolean flag value at request time.
+
+Rollouts are a sequence of conditions which when one is matched for a request context, overrides the default rollout property.
+
+Current rollout types include:
+
+- **Threshold** which allows you to return `true` or `false` for a given percentage of entities.
+- **Segments Match** which allows you to return `true` or `false` if an entity matches a given segment.
+
+
+
+Rollouts work similar to [Rules](#rules) in that they're evaluated in order per their rank from 1-N. The first rollout that matches wins. Once created, rollouts can be re-ordered to change how they're evaluated.
+
+### Default Rollout
+
+If no rollouts match for a given flag, the default rollout value is returned. This value is the same as the 'enabled' value for the flag for backward compatibility reasons.
+
+## Evaluation
+
+Evaluation is the process of sending requests to the Flipt server to process and
+determine if that request matches any of your segments and if so which variant or boolean value
+to return depending on flag type.
+
+In the above example involving colors, evaluation is where you send information
+about your current user to determine if they're a `new-user`, and which color
+(`dark`, `auto`, or `light`) that they should see for their main color scheme.
+
+
+
+### Entities
+
+Evaluation works by uniquely identifying each _thing_ that you want to compare
+against your segments and flags. We call this an `entity` in the Flipt
+ecosystem. More often than not this will be a user, but we didn't want to make
+any assumptions about how your application works, which is why `entity` was chosen.
+
+
+**Entity**
+
+What you want to test against in your application
+
+
+
+For Flipt to successfully determine which _bucket_ your entities fall into, it
+must have a way to uniquely identify them. This is the `entityId` and it's a
+simple string. It's up to you what that `entityId` is.
+
+It could be a:
+
+- email address
+- userID
+- IP address
+- physical address
+- etc
+
+Anything that's unique enough for your application and its requirements.
+
+### Context
+
+The final piece of the puzzle is context. Context allows Flipt to determine
+which segment your entity falls into by comparing it to all the possible
+constraints that you defined.
+
+
+**Context**
+
+Metadata associated with your entity used to determine which if any segments
+that entity is a member of
+
+
+
+Examples of context include:
+
+```
+- isAdmin
+- favoriteColor
+- country
+- freeUser
+```
+
+Think of these as pieces of information that are usually not unique, but that
+can be used to split your entities into your segments.
+
+You can include as much or as little context for each entity as you want,
+however, the more context that you provide, the more likely it's that an entity
+will match one of your segments.
+
+In Flipt, `context` is a simple map of key-value pairs where the key is the
+property to match against all constraints, and the value is what's compared.
+
+### Bucketing
+
+Bucketing is the process of determining which variant to return for a given evaluation request.
+
+Flipt uses a hashing algorithm to determine which variant to return for a given `flagKey`, `entityID` and `context`. This is what allows Flipt to return the same variant every time (also sometimes referred to as **stickiness**).
+
+
+Flipt never persists any information about your entities or context or which
+variant was returned for a given evaluation request. This is all done at
+runtime and is ephemeral.
+
+This allows Flipt to be used in a wide variety of
+applications and use cases without having to worry about inadvertently storing
+personally identifiable information (PII) or other privacy concerns.
+
+
+
+**Let's look at how it works:**
+
+1. Flipt takes the `flagKey` and `entityID` and concatenates them together to
+ form a string that looks like `flagKey:entityID`. This is called the key.
+2. Flipt then takes this new key and uses a hashing algorithm ([CRC-32 ChecksumIEEE](https://pkg.go.dev/hash/crc32#ChecksumIEEE)) to create a 32-bit integer called the hash.
+3. Flipt then creates a set of buckets from 0‐999 (1000 total buckets), mapping them with a sorted set of the [distributions](#distributions) for the flag.
+4. Finally, Flipt takes the hash and uses the modulo operator to determine which bucket the hashed value falls into. The distribution that maps to that bucket is then returned.
+
+**Consider an example:**
+
+Imagine that you have a flag with two [distributions](#distributions) `A` and `B`.
+
+If `distribution A` has a 30% 'rollout', then it would 'take up' buckets 0‐299 (out of the 1000 buckets). `Distribution B` would take up the remaining buckets 300‐999.
+
+The `flagKey/entityID` hashed value is a 32bit integer on which Flipt performs a [modulo](https://en.wikipedia.org/wiki/Modulo) operation (% 1000) so that it 's guaranteed to return a number between 0‐999.
+
+The result of the modulo operation is then used to determine which distribution to return via the bucket mapping. If the result is between 0‐299, then `distribution A` is returned, otherwise `distribution B` is returned.
diff --git a/v2/configuration/analytics.mdx b/v2/configuration/analytics.mdx
new file mode 100644
index 00000000..f5d79115
--- /dev/null
+++ b/v2/configuration/analytics.mdx
@@ -0,0 +1,117 @@
+---
+title: Analytics
+description: This document describes various configuration mechanisms for controlling analytics for Flipt v2.
+---
+
+## Analytics
+
+Flipt includes functionality for reporting analytical data to a configurable storage engine.
+
+Currently, Flipt has support for collecting data into the following storage engines:
+
+- [ClickHouse](https://clickhouse.com/)
+- [Prometheus](https://prometheus.io/)
+
+The data that gets collected currently includes:
+
+- Flag Evaluation Count
+
+Once a storage engine is configured, these analytics are viewable in the UI allowing users to visualize up to 24 hours of data for each metric.
+
+
+
+The image above shows the past 30 minutes of the flag `flag1` evaluation counts.
+
+### Origin
+
+Analytics are currently only collected as they pass through the evaluation server. This means that analytics will be captured if you are using the REST or GRPC APIs via one of our [Server SDKs](/integration/server/rest) or [GRPC SDKs](/integration/server/grpc) for evaluations.
+
+We have plans to support collecting analytics for [Client-Side](/integration/client) evaluations in the future.
+
+## ClickHouse
+
+You can use a self-hosted ClickHouse instance or a [managed instance](https://clickhouse.com/cloud/) to store your analytics data.
+
+We highly **recommend** using a separate database for analytics produced by Flipt. This ensures that Flipt analytic data can be logically isolated from the rest of your Clickhouse data.
+
+
+ The analytics database must be created before Flipt will be able to write
+ analytical data and run any migrations. See our
+ [migration](/configuration/storage#migrations) section for more info.
+
+
+To create a database for Flipt analytics, you can use the following SQL:
+
+```sql
+CREATE DATABASE IF NOT EXISTS flipt_analytics;
+```
+
+See the [ClickHouse documentation](https://clickhouse.com/docs) for more information on how to get started with ClickHouse.
+
+### Configuration
+
+To configure Flipt to use ClickHouse for analytics, you will need to add the following configuration to your `config.yml` file or environment variables:
+
+
+
+
+ ```bash
+ FLIPT_ANALYTICS_STORAGE_CLICKHOUSE_ENABLED=true
+ FLIPT_ANALYTICS_STORAGE_CLICKHOUSE_URL=clickhouse://clickhouse:9000/flipt_analytics
+ ```
+
+
+
+
+ ```yaml
+ analytics:
+ storage:
+ clickhouse:
+ enabled: true
+ url: clickhouse://clickhouse:9000/flipt_analytics
+ ```
+
+
+
+
+## Prometheus
+
+You can use any [Prometheus](https://prometheus.io/docs/introduction/overview/) server to store your analytics data.
+
+### Configuration
+
+To configure Flipt to use Prometheus for analytics, you will need to add the following configuration to your `config.yml` file or environment variables:
+
+
+
+
+ ```bash
+ FLIPT_ANALYTICS_STORAGE_PROMETHEUS_ENABLED=true
+ FLIPT_ANALYTICS_STORAGE_PROMETHEUS_URL=http://prometheus:9090
+ ```
+
+
+
+
+ ```yaml
+ analytics:
+ storage:
+ prometheus:
+ enabled: true
+ url: http://prometheus:9090
+ ```
+
+
+
+
+### Custom Headers
+
+You can also add custom headers to the Prometheus requests by setting the `analytics.storage.prometheus.headers` configuration property. This can be useful if you are using a proxy or need to add additional authentication headers.
+
+```yaml
+analytics:
+ storage:
+ prometheus:
+ headers:
+ "Authorization": "Bearer "
+```
diff --git a/v2/configuration/authentication.mdx b/v2/configuration/authentication.mdx
new file mode 100644
index 00000000..a90315ae
--- /dev/null
+++ b/v2/configuration/authentication.mdx
@@ -0,0 +1,527 @@
+---
+title: Authentication
+description: This document describes how to configure the authentication mechanisms for Flipt v2.
+---
+
+Flipt supports the ability to secure its core API routes by setting the `required` field to `true` on the `authentication` configuration object.
+
+```yaml config.yaml
+authentication:
+ required: true
+```
+
+When authentication is set to `required`, the API will ensure valid credentials are present on all API requests.
+
+
+Once authentication has been set to `required: true` all API routes will require a client token to be present.
+
+The UI will require a session-compatible authentication method (e.g. [OIDC](#method-oidc)) to be enabled.
+
+
+
+## Exclusions
+
+Exclusions allow you to disable authentication for sections of the API.
+The Flipt API is made up of several top-level API sections, each with its own unique prefix.
+
+For example:
+
+- `/evaluate/v1` is the application facing flag state evaluation API
+
+Several of these API sections can be optionally omitted from requiring authentication.
+A common use case is to allow the evaluation API to be publicly accessible while still requiring authenticated users to manage feature-flag configuration and state.
+
+By default, when authentication is configured as `required: true`, the effective configuration for the exclusions looks like this:
+
+```yaml config.yaml
+authentication:
+ required: true
+ exclude:
+ evaluation: false
+```
+
+This means every part of the Flipt API is required for authentication.
+However, taking the example from before, we could skip authentication for the evaluation section of the Flipt API like so:
+
+```yaml config.yaml
+authentication:
+ required: true
+ exclude:
+ evaluation: true
+```
+
+## Session
+
+This section contains common properties for establishing browser sessions via a "session compatible" authentication method. Session-compatible methods enable support for login in the UI. The methods below state whether or not they're session compatible (e.g. [OIDC](#method-oidc) is session compatible).
+
+In order to establish a browser session over HTTP (via a `Cookie` header) some configuration is required.
+
+```yaml config.yaml
+authentication:
+ required: true
+ session:
+ domain: "flipt.yourorg.com"
+ secure: true
+ csrf:
+ key: "some_secret_string"
+```
+
+When a "session compatible" authentication method is enabled the `domain` property is **required**.
+It should be configured with the public domain your Flipt instance is hosted on.
+The other properties aren't required to be explicitly configured.
+
+To best secure your instance of Flipt, we advise that you run Flipt with `secure: true`.
+This will require you to expose Flipt over HTTPS.
+Additionally, we advise that you configure a `csrf.key` with a 32 or 64-byte random string of data.
+
+
+
+```
+openssl rand -base64 64
+```
+
+
+
+### Session Storage
+
+Session storage allows you to configure where the session data is stored. All session enabled authentication methods will use the same configured session storage backend.
+
+Currently, Flipt v2 supports the following session storage backends:
+
+- `memory`
+- `redis`
+
+#### Memory
+
+The `memory` backend is the default and will store session data in memory. This means that the session data will be lost when the Flipt server restarts.
+
+```yaml config.yaml
+authentication:
+ required: true
+ session:
+ storage:
+ type: memory
+```
+
+#### Redis
+
+The `redis` backend will store session data in a Redis instance. This means that the session data will be persisted across Flipt server restarts and can be shared across multiple Flipt servers.
+
+```yaml config.yaml
+authentication:
+ required: true
+ session:
+ storage:
+ type: redis
+ redis:
+ host: localhost
+ port: 6379
+ db: 0
+ password: password
+```
+
+### Session Cleanup
+
+Session cleanup is a feature that allows you to configure the periodic deletion of _expired_ authentications created with the associated method.
+
+```yaml config.yaml
+authentication:
+ required: true
+ session:
+ cleanup:
+ grace_period: 24h
+```
+
+`grace_period` is used to ensure that _expired_ tokens are preserved for at least this configured duration.
+
+This allows you to keep authentications around for auditing purposes after expiration.
+
+Expired tokens are instances where the `expires_at` timestamp occurs before the current time.
+The grace period is added onto this timestamp as a predicate when the delete operation is made.
+
+Tokens that have expired (`expires_at` is before `now()`) will begin immediately failing authentication when presented as a credential to the API.
+The `grace_period` is simply for the cleanup process.
+
+## Methods
+
+Each key within the `methods` section is a particular authentication method.
+These methods are disabled (`enabled: false`) by default.
+Enabling and configuring a method allows for different ways to establish client token credentials within Flipt.
+
+### Static Token
+
+
+ The `token` method is NOT a `session compatible` authentication method.
+
+
+The `token` method provides the ability to create client tokens statically, defined in the configuration file.
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ token:
+ enabled: true
+ storage:
+ tokens:
+ "some_token_id":
+ credential: "some_token_credential"
+ metadata:
+ some_key: "some_value"
+```
+
+### OIDC
+
+The `OIDC` method is a `session compatible` authentication method.
+
+The `oidc` method provides the ability to establish client tokens via OAuth 2.0 with OIDC flow.
+Once enabled and configured, the UI will automatically leverage it and present any configured providers as login options.
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ oidc:
+ enabled: true
+ email_matches:
+ - ^.*@flipt.io$
+ providers:
+ some_provider: # insert your provider name
+ issuer_url: "https://some.oidc.issuer.com"
+ client_id: "some_client_identifier"
+ client_secret: "some_client_secret_credential"
+ redirect_address: "https://your.flipt.instance.url.com"
+ scopes:
+ - email
+ - profile
+```
+
+Multiple providers can be configured simultaneously. Each provider will result in a login option being presented in the UI, along with a configured endpoint to support the provider flow.
+
+Flipt v2 has been tested with each of the following providers:
+
+- [Google](https://developers.google.com/identity/openid-connect/openid-connect)
+- [Auth0](https://auth0.com/docs/get-started/applications/application-settings)
+- [GitLab](https://docs.gitlab.com/ee/integration/openid_connect_provider.html)
+- [Dex](https://dexidp.io/docs/openid-connect/)
+- [Okta](https://developer.okta.com/docs/concepts/oauth-openid/#oauth-2-0)
+- [AzureAD](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-protocols-oidc)
+- [Keycloak](https://www.keycloak.org/docs/latest/server_admin/index.html#_identity_broker_oidc)
+
+Though the intention is that it should work with all OIDC providers, these are just the handful the Flipt team has validated.
+
+Following any of the links above should take you to the relevant documentation for each of these providers' OIDC client setups.
+You can use the credentials and client configuration obtained using those steps as configuration for your Flipt instance.
+
+#### Callback URL
+
+When configuring your OIDC provider, you will need to provide a callback URL for the provider to redirect back to Flipt after a successful login.
+
+The callback URL will be in the form of `https://your.flipt.instance.url.com/auth/v1/method/oidc/{provider}/callback`.
+
+You can find the callback URL for each provider that you configure in your Flipt instance by querying the API.
+
+```bash
+curl --request GET \
+ --url https://your.flipt.instance.url.com/auth/v1/method \
+ --header 'Accept: application/json'
+```
+
+```json
+{
+ "methods": [
+ {
+ "method": "METHOD_TOKEN",
+ "enabled": true,
+ "sessionCompatible": false,
+ "metadata": null
+ },
+ {
+ "method": "METHOD_OIDC",
+ "enabled": true,
+ "sessionCompatible": true,
+ "metadata": {
+ "providers": {
+ "google": {
+ "authorize_url": "/auth/v1/method/oidc/google/authorize",
+ "callback_url": "/auth/v1/method/oidc/google/callback"
+ }
+ }
+ }
+ }
+ ]
+}
+```
+
+#### Email Matches
+
+Flipt operators may wish to lock down access to the Flipt API and UI to a specific group of users within their organization behind OIDC.
+Since OIDC has the ability to retrieve email addresses, Flipt also provides a configuration option of using `email_matches` which are [regular expressions](https://github.com/google/re2/wiki/Syntax) that can be used to match against the OIDC email.
+
+
+ You must request the `email` scope from your OIDC provider in order for this
+ feature to work.
+
+
+You can see an example of that above in the [sample configuration](#method-oidc).
+
+#### PKCE
+
+A good amount of OIDC providers support the PKCE (Proof Key for Code Exchange) flow and the implicit OAuth flow. Flipt allows for a configuration to enable PKCE for all the legs of the OIDC authentication flow.
+
+To enable this, you must set the [`use_pkce`](/v2/configuration/overview#authentication-methods-oidc) property to `true` for each provider you would like to leverage PKCE with.
+
+#### Example: OIDC With Google
+
+Given we're running our instance of Flipt on the public internet at `https://flipt.myorg.com`.
+
+Using Google as an example and the documentation linked above, we obtained the following credentials for a Google OAuth client:
+
+```yaml
+client_id: "CyJcdvQMadOjSEx7ArArom0ytrbIHWd2Fb3N59oh8NQ="
+client_secret: "WGgJmfQqN7cf17dFyZKXDL5S445/qhp+hfDAC0Mnl7oBrxgdAgiMyuwCkPiwfgQy"
+```
+
+We could create a provider definition in our configuration like so:
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ oidc:
+ enabled: true
+ providers:
+ google:
+ issuer_url: "https://accounts.google.com"
+ client_id: "CyJcdvQMadOjSEx7ArArom0ytrbIHWd2Fb3N59oh8NQ="
+ client_secret: "WGgJmfQqN7cf17dFyZKXDL5S445/qhp+hfDAC0Mnl7oBrxgdAgiMyuwCkPiwfgQy"
+ redirect_address: "https://flipt.myorg.com"
+ scopes:
+ - email
+ - profile
+```
+
+
+ The redirect URL for this provider would be
+ `https://flipt.myorg.com/auth/v1/method/oidc/google/callback`.
+
+
+Additional `scopes` such as `profile` aren't 100% necessary, however, adding
+them will result in Flipt being able to identify more details about your users
+such as personalized greeting messages and user profile pictures in the UI.
+
+Once this configuration has been enabled a `Login with Google` option will be presented in the UI.
+Clicking this button will navigate the user to a Google consent screen.
+Once the user has authenticated with Google, they will be redirected to the address defined in the `redirect_address` section of the provider configuration.
+
+
+Google's consent screen can be configured to only accept accounts that are within your Google Workspace organization.
+
+Other providers have similar mechanisms for attenuating who can leverage this authentication flow.
+
+
+
+### GitHub
+
+
+ The `GitHub` method is a `session compatible` authentication method.
+
+
+The `github` method provides the ability to establish client tokens via OAuth 2.0 with GitHub as the identity provider.
+Once enabled and configured, the UI will automatically leverage it and present a "Login with GitHub" button.
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ github:
+ enabled: true
+ client_id: "some_client_identifier"
+ client_secret: "some_client_secret_credential"
+ redirect_address: "https://your.flipt.instance.url.com"
+ scopes:
+ - user:email
+```
+
+-- TODO: add screenshot
+
+#### Allowed Organizations
+
+The GitHub authentication method supports the ability to restrict access to a set of GitHub organizations. This is important if you want to limit access to Flipt to only members of a specific organization as opposed to all GitHub users.
+
+To enable this feature, set the `github.allowed_organizations` configuration value to a list of GitHub organizations. For example:
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ github:
+ enabled: true
+ scopes:
+ - read:org
+ allowed_organizations:
+ - my-org
+ - my-other-org
+```
+
+
+ The `read:org` scope is required to retrieve the list of organizations that
+ the user is a member of.
+
+
+#### Allowed Teams
+
+The GitHub authentication method also supports the ability to restrict access to a set of GitHub teams. This is important if you want to limit access to Flipt to only members of a specific team within an organization as opposed to all members of the organization.
+
+To enable this feature, set the `github.allowed_teams` configuration value to a list of GitHub teams within existing allowed organizations. For example:
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ github:
+ enabled: true
+ scopes:
+ - read:org
+ allowed_organizations:
+ - my-org
+ - my-other-org
+ allowed_teams:
+ my-org:
+ - my-team
+ my-other-org:
+ - my-other-team
+```
+
+
+ The organizations to check for team membership must be included in the
+ `allowed_organizations` list.
+
+
+### Kubernetes
+
+The `kubernetes` method provides the ability to exchange Kubernetes service account tokens for client tokens.
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ kubernetes:
+ enabled: true
+ discovery_url: https://kubernetes.default.svc.cluster.local
+ ca_path: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+ service_account_token_path: /var/run/secrets/kubernetes.io/serviceaccount/token
+```
+
+Once enabled, client tokens can be retrieved by sending a Kubernetes pod's service account token to the `VerifyServiceAccount` operation in the API.
+
+Further explanation for using this method can be found in the [Authentication: Kubernetes](/authentication/methods#kubernetes) documentation.
+
+#### Troubleshooting
+
+**verifying service account: failed to verify signature: fetching keys oidc**
+
+In some managed Kubernetes cluster environments, the default cluster OIDC provider is replaced with the platform's managed alternative.
+For example, EKS clusters leverage this so that they can issue service account tokens which can assume the capabilities of AWS IAM roles.
+
+In this situation, the default OIDC discovery URL isn't appropriate for fetching key material from.
+Instead, you should locate your clusters OIDC URL and use that instead.
+
+
+ Your cluster's OIDC URL will vary between Kubernetes providers. For example,
+ here is some documentation which should help for EKS: [EKS troubleshoot OIDC
+ and IRSA](https://repost.aws/knowledge-center/eks-troubleshoot-oidc-and-irsa).
+
+
+It's also important to note that custom OIDC providers likely will use HTTPS which has been signed with certificates not authorized by the cluster TLS certificate authority.
+In this situation, you can override the `kubernetes` auth providers `ca_path` field with relevant key material.
+The `flipt` distributed Docker image has valid and trusted certificates in `/etc/ssl/certs/ca-certificates.crt`, which can be appropriate if your OIDC provider has certificates granted by a valid public certificate authority.
+
+```yaml example-config-for-eks.yaml
+authentication:
+ required: true
+ methods:
+ kubernetes:
+ enabled: true
+ discovery_url: https://oidc.eks.us-west-2.amazonaws.com/id/EXAMPLED539D4633E53DE1B716D3041E # note: yours will be different
+ ca_path: /etc/ssl/certs/ca-certificates.crt # this can be enough if your OIDC provider TLS certificates have been signed by a public certificate authority
+```
+
+See [this issue](https://github.com/flipt-io/flipt/issues/2942) for more context.
+
+### JSON Web Token
+
+The `jwt` method provides the ability to authenticate with Flipt using an externally issued JSON Web Token. This method is useful for integrating with other authentication systems that can issue JWTs (e.g. [Auth0](https://auth0.com/docs/tokens/json-web-tokens)) or by generating your own signed JWTs on the fly.
+
+Flipt supports asymmetrically signed JWTs using the following algorithms:
+
+- RS256
+- RS512
+- ES256
+- ES512
+- EdDSA
+
+This means that the JWT must be signed using a private key leveraging one of these algorithms and Flipt must be configured with the corresponding public key.
+
+Flipt supports key verification using the following methods:
+
+- [JWKS](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets) URL (JSON Web Key Set URL)
+- PEM (Privacy Enhanced Mail) encoded public key
+
+
+ These methods are mutually exclusive, meaning that only one of them can be
+ configured at a time.
+
+
+#### JWKS URL
+
+The `jwks_url` configuration value is a URL that points to a JWKS (JSON Web Key Set) endpoint. This endpoint must return a JSON object that contains a list of public keys that can be used to verify the JWT signature.
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ jwt:
+ enabled: true
+ jwks_url: https://auth0.com/.well-known/jwks.json
+```
+
+#### PEM Encoded Public Key
+
+The `public_key_file` configuration value is the path to a PEM encoded public key that can be used to verify the JWT signature.
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ jwt:
+ enabled: true
+ public_key_file: /path/to/public_key.pem
+```
+
+#### Claim Validation
+
+Flipt supports validating the following claims:
+
+- `iss` (issuer)
+- `aud` (audience)
+- `sub` (subject)
+- `exp` (expiration time)
+- `nbf` (not before)
+- `iat` (issued at)
+
+The `exp`, `nbf`, and `iat` claims are validated by default.
+
+To enable claim validation, configure the values in the `validate_claims` configuration option to the expected values.
+
+```yaml config.yaml
+authentication:
+ required: true
+ methods:
+ jwt:
+ enabled: true
+ validate_claims:
+ issuer: https://auth0.com/
+ subject: user@domain.com
+ audiences: https://flipt.io/, https://flipt.com/ # at least one audience must match
+```
diff --git a/v2/configuration/authorization.mdx b/v2/configuration/authorization.mdx
new file mode 100644
index 00000000..a75a068f
--- /dev/null
+++ b/v2/configuration/authorization.mdx
@@ -0,0 +1,94 @@
+---
+title: Authorization
+description: This document describes how to configure the authorization mechanisms for Flipt v2.
+---
+
+Flipt supports the ability to secure its core API routes by setting the `required` field to `true` on the `authorization` configuration object.
+
+```yaml config.yaml
+authorization:
+ required: true
+```
+
+When authorization is set to `required`, the API will ensure valid credentials are present on all management API requests.
+
+
+Once authorization has been set to `required: true` all management API routes will require a valid authentication session as well.
+
+The UI will require a session-compatible authentication method (e.g. OIDC) to be enabled.
+
+
+
+## Backends
+
+Flipt uses [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) to enforce authorization policies. OPA is a general-purpose policy engine that can be used to enforce policies across the stack.
+
+Flipt supports sourcing policies and external data from various backends. Currently, Flipt supports the following backends:
+
+- [Local](#local)
+
+## Local
+
+Flipt supports loading policy and external data from the local filesystem.
+
+### Policies
+
+For configuring policies, the files must be valid [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) files.
+
+You can specify the path to the policy file in the `policy` object in the `authorization` configuration object.
+
+```yaml
+authorization:
+ required: true
+ local:
+ policy:
+ path: "policy.rego"
+```
+
+The policy **must** have the following package declaration:
+
+```rego policy.rego
+package flipt.authz.v2
+```
+
+#### Polling Interval
+
+Flipt will poll the policy file for changes at a regular interval. By default, Flipt will poll the policy file every 5 minutes. You can adjust this interval by setting the `poll_interval` field in the `policy` object.
+
+```yaml
+authorization:
+ required: true
+ local:
+ policy:
+ path: "policy.rego"
+ poll_interval: "1m"
+```
+
+### External Data
+
+In addition to policies that can be used to enforce authorization rules, Flipt also provides a way to pass external data to the policy evaluation from the local filesystem. These data objects **must be valid JSON objects**.
+
+This can be done by setting the `data` object in the `authorization` configuration object.
+
+```yaml
+authorization:
+ required: true
+ local:
+ policy:
+ path: "policy.rego"
+ data:
+ path: "data.json"
+```
+
+#### Polling Interval
+
+Like policies, Flipt will poll data files for changes at a regular interval. By default, Flipt will poll the data file every 30 seconds. You can adjust this interval by setting the `poll_interval` field in the `data` object.
+
+```yaml
+authorization:
+ required: true
+ local:
+ data:
+ path: "data.json"
+ poll_interval: "1m"
+```
diff --git a/v2/configuration/environments.mdx b/v2/configuration/environments.mdx
new file mode 100644
index 00000000..bb78c327
--- /dev/null
+++ b/v2/configuration/environments.mdx
@@ -0,0 +1,87 @@
+---
+title: Environments
+description: This document describes how environments are configured for Flipt v2.
+---
+
+Flipt v2 supports the ability to configure multiple environments, allowing the user to switch between them in the UI as well as at evaluation time.
+
+Environments are unique to other Flipt resources in that they are not created or managed via the Flipt API or UI. Instead, they are defined in the Flipt server configuration file as they are tightly coupled to the [storage configuration](/v2/configuration/storage).
+
+## Identifiers
+
+Each environment has an identifier that is used to reference the environment in the configuration and in the UI/API and is used to determine the environment that will be used when evaluating flags.
+
+Identifiers can be any string value but must be unique. Flipt creates a `default` identifier and environment for you automatically if you don't specify one.
+
+```yaml
+environments:
+ local: # id
+ name: "local"
+ default: true
+
+ staging: # id
+ name: "staging"
+ storage: "staging"
+```
+
+## Storage
+
+Each environment has a storage configuration field that is used to determine the storage backend that will be used for the environment.
+
+The storage configuration is a reference to the [storage backend](/v2/configuration/storage) that will be used for the environment.
+
+```yaml
+environments:
+ local:
+ storage: "local"
+```
+
+In the above configuration, the `local` environment will use the `local` storage backend as defined in the [storage configuration](/v2/configuration/storage).
+
+
+This mapping between environments and storage backends means that multiple environments can share the same storage backend.
+
+For example you could have all environments share the same storage which syncs to a single git repository.
+
+
+
+
+
+
+### Directories
+
+Each environment has an optional `directory` configuration field that is used to determine the directory that will be used to store the environment's resources.
+
+This is only required if multiple environments share the same storage backend, as Flipt needs to know where to ultimately store the state without conflicting with other environments.
+
+```yaml
+environments:
+ foo:
+ directory: "foo"
+ storage: "local"
+ bar:
+ directory: "bar"
+ storage: "local"
+```
+
+In the above configuration, the `foo` and `bar` environments will use the same `local` storage backend but will store their resources in different directories.
+
+## Default
+
+Each environment has a default configuration field that is used to determine if the environment is the default environment.
+
+The default environment is the environment that will be used when no other environment is specified.
+
+```yaml
+environments:
+ local:
+ default: true
+```
+
+This means that if no environment is specified when performing actions such as flag evaluation, creation, or updates, the `local` environment will be used. This will also be the environment that is selected in the UI by default.
diff --git a/v2/configuration/observability.mdx b/v2/configuration/observability.mdx
new file mode 100644
index 00000000..0bd3cb51
--- /dev/null
+++ b/v2/configuration/observability.mdx
@@ -0,0 +1,161 @@
+---
+title: Observability
+description: This document describes how to configure observability mechanisms including metrics, logging, and tracing for Flipt v2.
+---
+
+## Metrics
+
+### Prometheus
+
+Flipt exposes [Prometheus](https://prometheus.io/) metrics by default at the `/metrics`
+HTTP endpoint. To see which metrics are currently supported, point your browser
+to `FLIPT_HOST/metrics` (ex: `localhost:8080/metrics`).
+
+You should see a bunch of metrics being recorded such as:
+
+```yaml
+flipt_cache_hit_total{cache="memory",type="flag"} 1
+flipt_cache_miss_total{cache="memory",type="flag"} 1
+---
+go_gc_duration_seconds{quantile="0"} 8.641e-06
+go_gc_duration_seconds{quantile="0.25"} 2.499e-05
+go_gc_duration_seconds{quantile="0.5"} 3.5359e-05
+go_gc_duration_seconds{quantile="0.75"} 6.6594e-05
+go_gc_duration_seconds{quantile="1"} 0.00026651 go_gc_duration_seconds_sum
+0.000402094 go_gc_duration_seconds_count 5
+```
+
+
+ You can disable the Prometheus metrics collection by setting the
+ `metrics.enabled` configuration option to `false`.
+
+
+### OTLP
+
+Flipt supports sending metrics to an [OTLP](https://opentelemetry.io/docs/concepts/data-collection/) collector.
+
+OTLP supports additional configuration such as specifying the protocol to use (gRPC or HTTP) as well as providing custom headers to send with the request.
+
+Custom headers can be used to provide authentication information to the collector which may be required if you are using a hosted collector such as [NewRelic](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-set-up-your-app/), [DataDog](https://docs.datadoghq.com/opentelemetry/otlp_ingest_in_the_agent/?tab=host), or [Honeycomb](https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/#instrumenting-with-opentelemetry).
+
+OpenTelemetry OTLP metrics are configured via the default OpenTelemetry Environment Variables. See the [OpenTelemetry Environment Variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/) documentation for more details.
+
+For example, to configure the OTLP metrics endpoint, you can set the `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4317
+```
+
+To configure the OTLP headers, you can set the `OTEL_EXPORTER_OTLP_METRICS_HEADERS` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_METRICS_HEADERS="Authorization=Bearer "
+```
+
+## Logging
+
+Flipt writes logs to STDOUT in two formats:
+
+- [JSON](#json)
+- [Console](#console)
+
+The format can be configured via the `log.encoding` configuration option.
+
+```yaml
+log:
+ encoding: json
+```
+
+For production deployments, we recommend using the JSON format as it's easier to parse and ingest into log aggregation systems such as Elasticsearch, Splunk, Loki, or Datadog.
+
+### JSON
+
+```json
+{
+ "L": "INFO",
+ "T": "2024-01-20T21:59:49-05:00",
+ "M": "finished unary call with code OK",
+ "server": "grpc",
+ "grpc.start_time": "2024-01-20T21:59:49-05:00",
+ "system": "grpc",
+ "span.kind": "server",
+ "grpc.service": "flipt.evaluation.EvaluationService",
+ "grpc.method": "Boolean",
+ "peer.address": "127.0.0.1:52635",
+ "grpc.code": "OK",
+ "grpc.time_ms": 0.146
+}
+```
+
+#### Log Key Descriptions
+
+- `L`: Level (log level). Possible values include: debug, info, warn, error, fatal, and panic.
+- `T`: Timestamp. The timestamp is in ISO 8601 format, widely used for representing date and time. It includes the date, time, and time zone information. For example, "2024-01-20T21:59:49-05:00" represents the date and time in the Eastern Time Zone (UTC-5).
+- `M`: Message. The message describes the log event. It can include information about the operation, errors encountered, or other relevant details.
+
+### Console
+
+```text
+2024-01-20T22:04:18-05:00 INFO finished unary call with code OK {"server": "grpc", "grpc.start_time": "2024-01-20T22:04:18-05:00", "system": "grpc", "span.kind": "server", "grpc.service": "flipt.evaluation.EvaluationService", "grpc.method": "Boolean", "peer.address": "127.0.0.1:53714", "grpc.code": "OK", "grpc.time_ms": 0.373}
+```
+
+More information about the available configuration options can be found in the [Logging configuration](/configuration/overview#logging) section.
+
+### OTLP
+
+Flipt v2 supports the new [OpenTelemetry OTLP logging specification](https://opentelemetry.io/docs/specs/otel/logs/). To enable OTLP logging, set the `OTLP_LOGS_EXPORTER` environment variable
+
+```console
+export OTLP_LOGS_EXPORTER=otlp
+```
+
+
+ OpenTelemetry logging is in addition to the existing logging configuration. It
+ does not replace the ability to log to a file or stdout/stderr.
+
+
+OpenTelemetry OTLP logging is configured via the default OpenTelemetry Environment Variables. See the [OpenTelemetry Environment Variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/) documentation for more details.
+
+For example, to configure the OTLP logging endpoint, you can set the `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4317
+```
+
+## Tracing
+
+Flipt supports distributed tracing via the [OpenTelemetry](https://opentelemetry.io/) project using the [OTLP](https://opentelemetry.io/docs/reference/specification/protocol/) protocol.
+
+### OTLP
+
+
+
+OTLP supports additional configuration such as specifying the protocol to use (gRPC or HTTP) as well as providing custom headers to send with the request.
+
+Custom headers can be used to provide authentication information to the collector which may be required if you are using a hosted collector such as [NewRelic](https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/get-started/opentelemetry-set-up-your-app/), [Datadog](https://docs.datadoghq.com/opentelemetry/otlp_ingest_in_the_agent/?tab=host), or [Honeycomb](https://docs.honeycomb.io/getting-data-in/opentelemetry-overview/#instrumenting-with-opentelemetry).
+
+OpenTelemetry OTLP tracing is configured via the default OpenTelemetry Environment Variables. See the [OpenTelemetry Environment Variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/) documentation for more details.
+
+For example, to configure the OTLP tracing endpoint, you can set the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317
+```
+
+To configure the OTLP headers, you can set the `OTEL_EXPORTER_OTLP_TRACES_HEADERS` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer "
+```
+
+#### Environment Variables
+
+Flipt supports all OTLP environment variables that are part of the [OTLP spec](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/).
+
+Here are a few of the most commonly used environment variables supported by Flipt:
+
+- `OTEL_SERVICE_NAME` - Sets the value of the `service.name` resource attribute (default: `flipt`)
+- `OTEL_RESOURCE_ATTRIBUTES` - Key-value pairs to be used as [resource attributes](https://opentelemetry.io/docs/specs/semconv/resource/#semantic-attributes-with-dedicated-environment-variable).
+- `OTEL_EXPORTER_OTLP_ENDPOINT` - The OTLP endpoint to any signal data (metrics, traces, logs) to
+- `OTEL_EXPORTER_OTLP_HEADERS` - Key-value pairs to be used as [OTLP headers](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#otel_exporter_otlp_headers) for any signal data (metrics, traces, logs).
+- `OTEL_EXPORTER_OTLP_PROTOCOL` - The protocol to use for the OTLP endpoint (grpc, http/protobuf, http/json)
diff --git a/v2/configuration/overview.mdx b/v2/configuration/overview.mdx
new file mode 100644
index 00000000..ee7448cb
--- /dev/null
+++ b/v2/configuration/overview.mdx
@@ -0,0 +1,429 @@
+---
+title: Overview
+description: This document describes how to configure the Flipt v2 server.
+mode: "wide"
+---
+
+Configuration precedence is as follows:
+
+1. [Environment Variables](#environment-variables)
+1. [Configuration File](#configuration-file)
+
+## Configuration File
+
+The default way that Flipt is configured is with the use of a configuration file
+[default.yml](https://github.com/flipt-io/flipt/blob/v2/config/default.yml).
+
+This file is read when Flipt starts up and configures several important
+properties for the server.
+
+
+ You can generate a default configuration file by running `flipt config init`.
+ See the [CLI](/cli) documentation for more information.
+
+
+The server will check in a few different locations for server configuration (in order):
+
+1. `--config` flag as an override
+2. `{{ USER_CONFIG_DIR }}/flipt/config.yml` (the `USER_CONFIG_DIR` value is based on your architecture and specified in the [Go documentation](https://pkg.go.dev/os#UserConfigDir))
+3. `/etc/flipt/config/default.yml`
+
+
+ We provide both a [JSON
+ schema](https://raw.githubusercontent.com/flipt-io/flipt/v2/config/flipt.schema.json)
+ and a [Cue
+ schema](https://raw.githubusercontent.com/flipt-io/flipt/v2/config/flipt.schema.cue)
+ that you can use to validate your configuration file and its properties.
+
+
+You can edit any of these properties to your liking, and on restart, Flipt will
+pick up the new changes.
+
+### Environment Substitution
+
+The configuration file also supports environment variable substitution.
+
+This allows you to use environment variables in your configuration file. For example, you can use the `FLIPT_CUSTOM_AUTH_REQUIRED` environment variable in the configuration file like this:
+
+```yaml
+authentication:
+ required: ${FLIPT_CUSTOM_AUTH_REQUIRED}
+```
+
+This will replace `${FLIPT_CUSTOM_AUTH_REQUIRED}` with the value of the `FLIPT_CUSTOM_AUTH_REQUIRED` environment variable. The format for environment variable substitution is `${ENV_VAR}`.
+
+
+ This can be used to provide sensitive information to Flipt without storing it
+ in the configuration file. For example, you can use environment variables to
+ store the database URL, API keys, or other sensitive information without
+ having to conform to the pre-defined Flipt [environment variable
+ format](#environment-variables).
+
+
+### Remote Configuration
+
+Flipt supports fetching configuration from a remote source. This is useful for managing configuration across multiple instances of Flipt. The remote configuration source can be a URL to a configuration file stored in one of the following object storage services:
+
+- S3 (e.g.: `s3://bucket-name/path/to/config.yml`)
+- Azure Blob Storage (e.g.: `azblob://container-name/path/to/config.yml`)
+- Google Cloud Storage (e.g.: `googlecloud://bucket-name/path/to/config.yml`)
+
+To load Flipt configuration from a remote source, replace the `config.yml` file with the URL to the remote configuration file in the `--config` flag when starting the server.
+
+```console
+flipt server --config s3://bucket-name/path/to/config.yml
+```
+
+For authenticating with the object storage service, you can use the following environment variables depending on the service:
+
+- `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
+- `AZURE_STORAGE_ACCOUNT` and `AZURE_STORAGE_KEY` or `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, and `AZURE_CLIENT_SECRET`
+- `GOOGLE_APPLICATION_CREDENTIALS`
+
+## Environment Variables
+
+All options in the configuration file can be overridden using environment
+variables using the syntax:
+
+```yaml
+FLIPT__
+```
+
+Environment variables **MUST** have `FLIPT_` prefix and be in `UPPER_SNAKE_CASE` format.
+
+
+ Using environment variables to override defaults is especially helpful when
+ running with Docker.
+
+
+Keys should be uppercase and `.` should be replaced by `_`. For example,
+given these configuration settings:
+
+```yaml
+server:
+ grpc_port: 9000
+```
+
+You can override them using:
+
+```console
+export FLIPT_SERVER_GRPC_PORT=9001
+```
+
+### Multiple Values
+
+Some configuration options can have a list of values. For example, the `cors.allowed_origins` option can have multiple origins.
+
+In this case, you can use a space separated list of values for the environment variable override:
+
+```console
+export FLIPT_CORS_ALLOWED_ORIGINS="http://localhost:3000 http://localhost:3001"
+```
+
+## Configuration Parameters
+
+| Property | Description | Default | Since |
+| ----------------------------- | ------------------------------------------------------------------------------ | ------------------- | ------ |
+| cors.enabled | Enable CORS support | false | v2.0.0 |
+| cors.allowed_origins | Sets Access-Control-Allow-Origin header on server | "\*" (all domains) | v2.0.0 |
+| meta.check_for_updates | Enable check for newer versions of Flipt on startup | true | v2.0.0 |
+| meta.telemetry_enabled | Enable anonymous telemetry data (see [Telemetry](/v2/configuration/telemetry)) | true | v2.0.0 |
+| meta.state_directory | Directory on the host to store local state | $HOME/.config/flipt | v2.0.0 |
+| diagnostics.profiling.enabled | Enable profiling endpoints for pprof | true | v2.0.0 |
+
+### User Interface
+
+| Property | Description | Default | Since |
+| ---------------- | ----------------------------------- | ------- | ------ |
+| ui.default_theme | Sets the default UI theme for users | system | v2.0.0 |
+
+### Server
+
+| Property | Description | Default | Since |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------- | ------ |
+| server.protocol | http or https | http | v2.0.0 |
+| server.host | The host address on which to serve the Flipt application | 0.0.0.0 | v2.0.0 |
+| server.http_port | The HTTP port on which to serve the Flipt REST API and UI | 8080 | v2.0.0 |
+| server.https_port | The HTTPS port on which to serve the Flipt REST API and UI | 443 | v2.0.0 |
+| server.grpc_port | The port on which to serve the Flipt GRPC server | 9000 | v2.0.0 |
+| server.grpc_conn_max_idle_time | Maximum amount of time a GRPC connection can be idle | unlimited | v2.0.0 |
+| server.grpc_conn_max_age | Maximum amount of time a GRPC connection can live | unlimited | v2.0.0 |
+| server.grpc_conn_max_age_grace | Maximum amount of time a GRPC connection can live for outstanding RPCs after exceeding `grpc_conn_max_age ` | unlimited | v2.0.0 |
+| server.cert_file | Path to the certificate file (if protocol is set to https) | | v2.0.0 |
+| server.cert_key | Path to the certificate key file (if protocol is set to https) | | v2.0.0 |
+
+### Environments
+
+| Property | Description | Default | Since |
+| --------------------------- | --------------------------------------------------------------- | ------- | ------ |
+| environments.[id].name | The canonical name of the environment | default | v2.0.0 |
+| environments.[id].default | Whether the environment is the default environment | false | v2.0.0 |
+| environments.[id].storage | The id of the storage to use for the environment | | v2.0.0 |
+| environments.[id].directory | The directory to use for the environment with the given storage | | v2.0.0 |
+
+### Storage
+
+| Property | Description | Default | Since |
+| ------------------------------ | ------------------------------------------------------------------- | ------------------- | ------ |
+| storage.[id].name | The canonical name of the storage instance | default | v2.0.0 |
+| storage.[id].backend.type | The type of backend to use (options: memory, local) | memory | v2.0.0 |
+| storage.[id].backend.path | The path to the local storage directory for git backend | temporary directory | v2.0.0 |
+| storage.[id].remote | The remote URL to sync storage to/from | | v2.0.0 |
+| storage.[id].branch | The branch to use for git backend | main | v2.0.0 |
+| storage.[id].poll_interval | The interval to poll the git repository and ref for changes | 30s | v2.0.0 |
+| storage.[id].ca_cert_bytes | The CA certificate bytes for the remote URL | | v2.0.0 |
+| storage.[id].ca_cert_path | The CA certificate path for the remote URL | | v2.0.0 |
+| storage.[id].insecure_skip_tls | Skip verifying the server's certificate chain (avoid in production) | false | v2.0.0 |
+| storage.[id].credentials | The id of the credentials to use for the remote URL | | v2.0.0 |
+| storage.[id].signature.name | The name of the author to use from the commit signature | | v2.0.0 |
+| storage.[id].signature.email | The email of the author to use from the commit signature | | v2.0.0 |
+
+### Credentials
+
+| Property | Description | Default | Since |
+| --------------------------------------------- | ------------------------------------------------------------------ | ------- | ------ |
+| credentials.[id].type | The type of credentials to use (options: basic, ssh, access_token) | basic | v2.0.0 |
+| credentials.[id].basic.username | The username to use for basic authentication | | v2.0.0 |
+| credentials.[id].basic.password | The password to use for basic authentication | | v2.0.0 |
+| credentials.[id].ssh.user | The username to use for SSH authentication | git | v2.0.0 |
+| credentials.[id].ssh.password | Password used to generate the SSH key pair | | v2.0.0 |
+| credentials.[id].ssh.private_key_path | Path to private key on the filesystem | | v2.0.0 |
+| credentials.[id].ssh.private_key_bytes | (Alternative) Raw private key bytes | | v2.0.0 |
+| credentials.[id].ssh.insecure_ignore_host_key | Skip verifying the known hosts key (avoid in production) | false | v2.0.0 |
+| credentials.[id].access_token | The token to use for authentication | | v2.0.0 |
+
+### Authentication
+
+
+ Authentication is configured slightly differently in v2 compared to v1. See
+ the [Authentication](/v2/configuration/authentication) documentation for more
+ details.
+
+
+| Property | Description | Default | Since |
+| --------------------------------- | ------------------------------------------------------- | ------- | ------ |
+| authentication.required | Enable or disable authentication validation on requests | false | v2.0.0 |
+| authentication.exclude.evaluation | Exclude authentication for /evaluation/v1 API prefix | false | v2.0.0 |
+| authentication.exclude.ofrep | Exclude authentication for /ofrep API prefix | false | v2.0.0 |
+
+#### Authentication Session
+
+| Property | Description | Default | Since |
+| ------------------------------------- | ------------------------------------------------------------- | ------- | ------ |
+| authentication.session.domain | Public domain on which Flipt instance is hosted | | v2.0.0 |
+| authentication.session.secure | Configures the `Secure` property on created session cookies | false | v2.0.0 |
+| authentication.session.token_lifetime | Configures the lifetime of the session token (login duration) | 24h | v2.0.0 |
+| authentication.session.state_lifetime | Configures the lifetime of state parameters during OAuth flow | 10m | v2.0.0 |
+| authentication.session.csrf.key | Secret credential used to sign CSRF prevention tokens | | v2.0.0 |
+| authentication.session.token_lifetime | Configures the lifetime of the session token (login duration) | 24h | v2.0.0 |
+| authentication.session.state_lifetime | Configures the lifetime of state parameters during OAuth flow | 10m | v2.0.0 |
+
+#### Authentication Session Storage
+
+| Property | Description | Default | Since |
+| --------------------------------------------------- | -------------------------------------------------------------- | ------- | ------ |
+| authentication.session.storage.type | The type of storage to use for session storage (memory, redis) | memory | v2.0.0 |
+| authentication.session.storage.cleanup.grace_period | The grace period for the cleanup of expired sessions | 30m | v2.0.0 |
+
+#### Authentication Session Storage: Redis
+
+| Property | Description | Default | Since |
+| ------------------------------------------------------- | ------------------------------------------------------------------- | --------- | ------ |
+| authentication.session.storage.redis.host | Host to access the Redis database | localhost | v2.0.0 |
+| authentication.session.storage.redis.port | Port to access the Redis database | 6379 | v2.0.0 |
+| authentication.session.storage.redis.db | Redis database to use | 0 | v2.0.0 |
+| authentication.session.storage.redis.username | Username to access the Redis database | | v2.0.0 |
+| authentication.session.storage.redis.password | Password to access the Redis database | | v2.0.0 |
+| authentication.session.storage.redis.require_tls | Require TLS to access the Redis database | false | v2.0.0 |
+| authentication.session.storage.redis.pool_size | Max number of socket connections per CPU | 10 | v2.0.0 |
+| authentication.session.storage.redis.min_idle_conn | Minimum number of idle connections in the pool | 0 | v2.0.0 |
+| authentication.session.storage.redis.conn_max_idle_time | Maximum amount of time a connection can be idle | 30m | v2.0.0 |
+| authentication.session.storage.redis.net_timeout | Network timeout for Redis connections | 0 | v2.0.0 |
+| authentication.session.storage.redis.ca_cert_path | Path to custom certificate authority (CA) certificate | | v2.0.0 |
+| authentication.session.storage.redis.ca_cert_bytes | (Alternative) Raw certificate authority (CA) certificate bytes | | v2.0.0 |
+| authentication.session.storage.redis.insecure_skip_tls | Skip verifying the server's certificate chain (avoid in production) | false | v2.0.0 |
+
+#### Authentication Methods: Static Token
+
+| Property | Description | Default | Since |
+| ------------------------------------------------------ | ----------------------------------------------- | ------- | ------ |
+| authentication.methods.token.enabled | Enable static token authentication | false | v2.0.0 |
+| authentication.methods.token.tokens | List of static tokens to use for authentication | | v2.0.0 |
+| authentication.methods.token.tokens.[token].credential | The credential to use for the token | | v2.0.0 |
+| authentication.methods.token.tokens.[token].metadata | The metadata to use for the token | | v2.0.0 |
+
+#### Authentication Methods: OIDC
+
+| Property | Description | Default | Since |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------- | ------- | ------ |
+| authentication.methods.oidc.enabled | Enable OIDC authentication | false | v2.0.0 |
+| authentication.methods.oidc.providers.[provider].issuer_url | Provider specific OIDC issuer URL (see your providers docs) | | v2.0.0 |
+| authentication.methods.oidc.providers.[provider].client_id | Provider specific OIDC client ID (see your providers docs) | | v2.0.0 |
+| authentication.methods.oidc.providers.[provider].client_secret | Provider specific OIDC client secret (see your providers docs) | | v2.0.0 |
+| authentication.methods.oidc.providers.[provider].redirect_address | Public URL on which this Flipt instance is reachable | | v2.0.0 |
+| authentication.methods.oidc.providers.[provider].scopes | Scopes to request from the provider | | v2.0.0 |
+| authentication.methods.oidc.providers.[provider].use_pkce | Option for enabling PKCE for OIDC authentication flow | false | v2.0.0 |
+| authentication.methods.oidc.email_matches | List of email addresses (regex) of users allowed to authenticate | | v2.0.0 |
+
+#### Authentication Methods: GitHub
+
+| Property | Description | Default | Since |
+| --------------------------------------------------- | ------------------------------------------------------------------ | ---------------------- | ------ |
+| authentication.methods.github.enabled | Enable GitHub authentication | false | v2.0.0 |
+| authentication.methods.github.client_id | GitHub client ID | | v2.0.0 |
+| authentication.methods.github.client_secret | GitHub client secret | | v2.0.0 |
+| authentication.methods.github.redirect_address | Public URL on which this Flipt instance is reachable | | v2.0.0 |
+| authentication.methods.github.scopes | Scopes to request from GitHub | | v2.0.0 |
+| authentication.methods.github.allowed_organizations | List of GitHub organizations allowed to authenticate | | v2.0.0 |
+| authentication.methods.github.allowed_teams | Map of GitHub organizations to teams that users must be members of | | v2.0.0 |
+| authentication.methods.github.server_url | GitHub Server URL (to support GHES) | https://github.com | v2.0.0 |
+| authentication.methods.github.api_url | GitHub API URL (to support GHES) | https://api.github.com | v2.0.0 |
+
+#### Authentication Methods: Kubernetes
+
+| Property | Description | Default | Since |
+| ------------------------------------------------------------ | ---------------------------------------------------------- | ---------------------------------------------------- | ------ |
+| authentication.methods.kubernetes.enabled | Enable Kubernetes service account token authentication | false | v2.0.0 |
+| authentication.methods.kubernetes.discovery_url | Kubernetes API server URL for OIDC configuration discovery | https://kubernetes.default.svc.cluster.local | v2.0.0 |
+| authentication.methods.kubernetes.ca_path | Kubernetes API CA certification path | /var/run/secrets/kubernetes.io/serviceaccount/ca.crt | v2.0.0 |
+| authentication.methods.kubernetes.service_account_token_path | Path to Flipt service account token | /var/run/secrets/kubernetes.io/serviceaccount/token | v2.0.0 |
+
+#### Authentication Methods: JWT
+
+| Property | Description | Default | Since |
+| ---------------------------------------------------- | --------------------------------------------------- | ------- | ------ |
+| authentication.methods.jwt.enabled | Enable JWT authentication | false | v2.0.0 |
+| authentication.methods.jwt.jwks_url | URL to retrieve JWKS for JWT validation | | v2.0.0 |
+| authentication.methods.jwt.public_key_file | Path to public key file for JWT validation | | v2.0.0 |
+| authentication.methods.jwt.validate_claims.issuer | The issuer claim to validate on JWT tokens | | v2.0.0 |
+| authentication.methods.jwt.validate_claims.audiences | The audience claim (list) to validate on JWT tokens | | v2.0.0 |
+| authentication.methods.jwt.validate_claims.subject | The subject claim to validate on JWT tokens | | v2.0.0 |
+
+### Authorization
+
+| Property | Description | Default | Since |
+| ---------------------- | ------------------------------------------------------ | ------- | ------ |
+| authorization.required | Enable or disable authorization validation on requests | false | v2.0.0 |
+
+#### Authorization Backend: Local
+
+| Property | Description | Default | Since |
+| ---------------------------------------- | -------------------------------------------- | ------- | ------ |
+| authorization.local.policy.path | Path to the local policy file | | v2.0.0 |
+| authorization.local.policy.poll_interval | Interval to poll the policy file for changes | 5m | v2.0.0 |
+| authorization.local.data.path | Path to the local data file | | v2.0.0 |
+| authorization.local.data.poll_interval | Interval to poll the data file for changes | 30s | v2.0.0 |
+
+### Analytics
+
+| Property | Description | Default | Since |
+| ----------------------------- | ----------------------------------------------- | ------- | ------ |
+| analytics.buffer.flush_period | Duration to wait before sending events to sinks | 10s | v2.0.0 |
+
+#### Analytics: Clickhouse
+
+| Property | Description | Default | Since |
+| ------------------------------------ | ----------------------------------- | ------- | ------ |
+| analytics.storage.clickhouse.enabled | Enable Clickhouse support | false | v2.0.0 |
+| analytics.storage.clickhouse.url | URL to connect to clickhouse server | | v2.0.0 |
+
+#### Analytics: Prometheus
+
+| Property | Description | Default | Since |
+| ------------------------------------ | ----------------------------------------------------------------------- | ------- | ------ |
+| analytics.storage.prometheus.enabled | Enable Prometheus support | false | v2.0.0 |
+| analytics.storage.prometheus.url | URL to connect to prometheus server | | v2.0.0 |
+| analytics.storage.prometheus.headers | Additional headers to send with Prometheus requests (map[string]string) | | v2.0.0 |
+
+### Logging
+
+| Property | Description | Default | Since |
+| ---------------- | -------------------------------------------------------------------------------- | ------- | ------ |
+| log.level | Level at which messages are logged (debug, info, warn, error, fatal, panic) | info | v2.0.0 |
+| log.grpc_level | Level at which gRPC messages are logged (debug, info, warn, error, fatal, panic) | error | v2.0.0 |
+| log.file | File to log to instead of STDOUT | | v2.0.0 |
+| log.encoding | Encoding to use for logging (json, console) | console | v2.0.0 |
+| log.keys.time | Structured logging key used when outputting log timestamp | T | v2.0.0 |
+| log.keys.level | Structured logging key used when outputting log level | L | v2.0.0 |
+| log.keys.message | Structured logging key used when outputting log message | M | v2.0.0 |
+
+#### Logging: OTLP
+
+Flipt v2 supports the new [OpenTelemetry OTLP logging specification](https://opentelemetry.io/docs/specs/otel/logs/). To enable OTLP logging, set the `OTLP_LOGS_EXPORTER` environment variable
+
+```console
+export OTLP_LOGS_EXPORTER=otlp
+```
+
+
+ OpenTelemetry logging is in addition to the existing logging configuration. It
+ does not replace the ability to log to a file or stdout/stderr.
+
+
+OpenTelemetry OTLP logging is configured via the default OpenTelemetry Environment Variables. See the [OpenTelemetry Environment Variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/) documentation for more details.
+
+For example, to configure the OTLP logging endpoint, you can set the `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4317
+```
+
+### Metrics
+
+| Property | Description | Default | Since |
+| ---------------- | -------------------------------------- | ---------- | ------ |
+| metrics.enabled | Enable metrics support | true | v2.0.0 |
+| metrics.exporter | The exporter to use (prometheus, otlp) | prometheus | v2.0.0 |
+
+#### Metrics: OTLP
+
+OpenTelemetry OTLP metrics are configured via the default OpenTelemetry Environment Variables. See the [OpenTelemetry Environment Variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/) documentation for more details.
+
+For example, to configure the OTLP metrics endpoint, you can set the `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4317
+```
+
+To configure the OTLP headers, you can set the `OTEL_EXPORTER_OTLP_METRICS_HEADERS` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_METRICS_HEADERS="Authorization=Bearer "
+```
+
+### Tracing
+
+| Property | Description | Default | Since |
+| --------------- | ---------------------- | ------- | ------ |
+| tracing.enabled | Enable tracing support | false | v2.0.0 |
+
+The only supported tracing backend is OTLP.
+
+#### Tracing: OTLP
+
+OpenTelemetry OTLP tracing is configured via the default OpenTelemetry Environment Variables. See the [OpenTelemetry Environment Variables](https://opentelemetry.io/docs/reference/specification/sdk-environment-variables/) documentation for more details.
+
+For example, to configure the OTLP tracing endpoint, you can set the `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317
+```
+
+To configure the OTLP headers, you can set the `OTEL_EXPORTER_OTLP_TRACES_HEADERS` environment variable.
+
+```console
+export OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer "
+```
+
+## Deprecations
+
+From time to time configuration options will need to be deprecated and
+eventually removed. Deprecated configuration options will be removed after \~6
+months from the time they were deprecated.
+
+All deprecated configuration options will be removed from the documentation,
+however, they will still work as expected until they're removed. A warning will
+be logged in the Flipt logs when a deprecated configuration option is used.
+
+All deprecated options are listed in the [DEPRECATIONS](https://github.com/flipt-io/flipt/blob/v2/DEPRECATIONS.md) file
+in the Flipt repository as well as the [CHANGELOG](https://github.com/flipt-io/flipt/blob/v2/CHANGELOG.md).
diff --git a/v2/configuration/storage.mdx b/v2/configuration/storage.mdx
new file mode 100644
index 00000000..a5f3449d
--- /dev/null
+++ b/v2/configuration/storage.mdx
@@ -0,0 +1,178 @@
+---
+title: Storage
+description: This document describes how to configure the storage backend mechanisms for Flipt v2.
+---
+
+Flipt v2 stores all of its resources in git repositories. This section describes how those git repositories are persisted and managed.
+
+## Identifiers
+
+Each storage backend has an identifier that is used to reference the storage backend in the configuration, such as when specifying the storage backend for an environment.
+
+Identifiers can be any string value but must be unique. Flipt creates a `default` identifier and storage backend for you automatically if you don't specify one.
+
+In the following example, we've defined two storage backends:
+
+- `staging` is a local storage backend that will serve Flipt flag state from a local directory.
+- `development` is a memory storage backend that will serve Flipt flag state from an in-memory store.
+
+```yaml
+storage:
+ staging: # id
+ name: "staging"
+ backend:
+ type: local
+ path: "/path/to/staging/repository"
+ development: # id
+ name: "development"
+ backend:
+ type: memory
+```
+
+## Backends
+
+Flipt v2 supports the following storage backends:
+
+- [Local](#local)
+- [Memory](#memory)
+
+### Local
+
+The purpose of this backend type is to support serving Flipt flag state directly from your local filesystem in a git repository.
+
+This allows the the data to be persisted between server restarts.
+
+Flipt will periodically rebuild its state from the local disk every 10 seconds.
+
+```yaml
+storage:
+ backend:
+ type: local
+ path: "."
+```
+
+The above configuration will create a local storage backend with the identifier `default` and serve Flipt flag state from the current working directory.
+
+### Memory
+
+The purpose of this backend type is to support serving Flipt flag state from an in-memory store.
+
+This is useful for development and testing purposes where you don't want to persist flag state to disk.
+
+```yaml
+storage:
+ backend:
+ type: memory
+```
+
+The above configuration will create a memory storage backend with the identifier `default` and serve Flipt flag state from an in-memory store.
+
+## Git Remotes
+
+Flipt v2 supports syncing flag state to and from a remote git repository.
+
+```yaml
+storage:
+ staging:
+ backend:
+ type: memory
+ remote: "https://github.com/flipt-io/example.git"
+ branch: "main"
+ poll_interval: "30s"
+ credentials: "github"
+```
+
+This configuration will create a git storage backend with the identifier `staging` in memory and will sync flag state to and from the remote repository.
+
+### Conflict Resolution
+
+Conflicts can occur when syncing flag state to and from a remote repository. The conflict resolution strategy in Flipt v2 is currently rudimentary and we aim to improve this in future releases.
+
+When syncing flag state to and from a remote repository, Flipt will behave as follows:
+
+- Remote state is synced to the local storage backend using the configured `poll_interval`
+- On writes to the Flipt server, the local storage backend will create a new commit and push it to the remote repository
+- Flipt keeps track of the last commit hash for each storage backend
+- If a write is made to a flag state file that has been modified since the last commit, Flipt will refuse to push the changes to the remote repository and will instead return an error
+- If a write is made to a flag state file that has not been modified since the last commit, Flipt will push the changes to the remote repository
+
+### Credentials
+
+Credentials enable the ability to authenticate with remote repositories.
+
+Supported authentication schemes are:
+
+- `basic`
+- `ssh`
+- `access_token`
+
+Credentials are configured using the `credentials` configuration section and use identifiers to reference the credentials in the configuration.
+
+
+ This means that you can use the same credentials for multiple storage backends
+ if needed.
+
+
+
+
+
+#### Basic
+
+Basic authentication is a username and password pair.
+
+
+ When using GitHub and their [PATs (Personal Access
+ Tokens)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens),
+ `basic` authentication should be used. GitHub expects you to supply a valid
+ `username` and provide your PAT as the `password` parameter.
+
+
+```yaml
+credentials:
+ github:
+ type: basic
+ username: < username >
+ password: < github-personal-access-token >
+```
+
+#### SSH
+
+In order to configure a git remote with SSH, you will need to generate an SSH key-pair and configure your repository provider with the public key.
+
+GitHub has some excellent documentation regarding how to generate and install your credentials [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).
+
+Once you have your private key credentials you will need to configure Flipt to use them.
+This can be done via the `storage.git.authentication.ssh` configuration section:
+
+```yaml
+credentials:
+ github:
+ type: ssh
+ user: git
+ private_key_path: ~/.ssh/id_rsa
+ private_key_bytes: # alternatively pass the raw bytes inline
+```
+
+
+ `insecure_ignore_host_key` is not encouraged for production use, and is
+ `false` by default. Instead, you are advised to put the key fingerprint in the
+ known hosts file where you are running Flipt. For example, for GitHub you can
+ do `ssh-keyscan github.com >> ~/.ssh/known_hosts` on the Flipt host.
+
+
+#### Access Token
+
+Access tokens are a type of credential that are used to authenticate with a remote repository. These can be used for any remote repository provider that supports access tokens.
+
+```yaml
+credentials:
+ gitlab:
+ type: access_token
+ token: < gitlab-access-token >
+```
diff --git a/v2/configuration/telemetry.mdx b/v2/configuration/telemetry.mdx
new file mode 100644
index 00000000..dc4305be
--- /dev/null
+++ b/v2/configuration/telemetry.mdx
@@ -0,0 +1,60 @@
+---
+title: Telemetry
+description: This document describes how to configure telemetry outputs as well as what data is captured for Flipt v2.
+---
+
+Flipt developers rely on anonymous usage data to help prioritize new features and improve the product. The information collected is completely anonymous,
+never shared with external entities, and you can opt-out at any time.
+
+The telemetry data is collected by default, but you can disable it by following the instructions below.
+
+Telemetry is only collected when Flipt is running, **once at startup** and then every **4 hours**.
+
+### What Kind of Data is Collected?
+
+- Flipt version (i.e.: v2.0.0)
+- Operating system (i.e.: Linux)
+- Architecture (i.e.: amd64)
+
+We use [Jitsu](https://jitsu.com/) to collect the data. Only the Flipt team has access to the raw data.
+
+Here is an example of the telemetry data sent to Jitsu:
+
+```json
+{
+ "version": "2.0",
+ "uuid": "1545d8a8-7a66-4d8d-a158-0a1c576c68a6",
+ "lastTimestamp": "2023-04-25T01:01:51Z",
+ "flipt": {
+ "version": "v2.0.0",
+ "os": "linux",
+ "arch": "amd64"
+ }
+}
+```
+
+You can always view the current schema of the telemetry data and see how it's collected on
+[GitHub](https://github.com/flipt-io/flipt/blob/main/internal/telemetry/telemetry.go).
+
+### How To Disable Telemetry
+
+Telemetry collection can be disabled in several ways:
+
+#### Configuration File
+
+```yaml
+meta:
+ telemetry_enabled: false
+```
+
+#### Environment Variables
+
+```shell
+export FLIPT_META_TELEMETRY_ENABLED=false
+```
+
+Telemetry can also be disabled by setting the [DO_NOT_TRACK](https://consoledonottrack.com/) environment variable to `true` or `1`:
+
+```shell
+export DO_NOT_TRACK=true
+```
diff --git a/v2/images/concepts/constraints.png b/v2/images/concepts/constraints.png
new file mode 100644
index 00000000..2904434d
Binary files /dev/null and b/v2/images/concepts/constraints.png differ
diff --git a/v2/images/concepts/constraints_types.png b/v2/images/concepts/constraints_types.png
new file mode 100644
index 00000000..ece6e8f5
Binary files /dev/null and b/v2/images/concepts/constraints_types.png differ
diff --git a/v2/images/concepts/environments.png b/v2/images/concepts/environments.png
new file mode 100644
index 00000000..1077f0e1
Binary files /dev/null and b/v2/images/concepts/environments.png differ
diff --git a/v2/images/concepts/evaluation.png b/v2/images/concepts/evaluation.png
new file mode 100644
index 00000000..03409b75
Binary files /dev/null and b/v2/images/concepts/evaluation.png differ
diff --git a/v2/images/concepts/flags.png b/v2/images/concepts/flags.png
new file mode 100644
index 00000000..7d48344a
Binary files /dev/null and b/v2/images/concepts/flags.png differ
diff --git a/v2/images/concepts/flags_boolean.png b/v2/images/concepts/flags_boolean.png
new file mode 100644
index 00000000..a52ed357
Binary files /dev/null and b/v2/images/concepts/flags_boolean.png differ
diff --git a/v2/images/concepts/flags_metadata.png b/v2/images/concepts/flags_metadata.png
new file mode 100644
index 00000000..d017e475
Binary files /dev/null and b/v2/images/concepts/flags_metadata.png differ
diff --git a/v2/images/concepts/flags_variant.png b/v2/images/concepts/flags_variant.png
new file mode 100644
index 00000000..e50e2a60
Binary files /dev/null and b/v2/images/concepts/flags_variant.png differ
diff --git a/v2/images/concepts/namespaces.png b/v2/images/concepts/namespaces.png
new file mode 100644
index 00000000..0ff78165
Binary files /dev/null and b/v2/images/concepts/namespaces.png differ
diff --git a/v2/images/concepts/rollouts.png b/v2/images/concepts/rollouts.png
new file mode 100644
index 00000000..c685d8f1
Binary files /dev/null and b/v2/images/concepts/rollouts.png differ
diff --git a/v2/images/concepts/rules.png b/v2/images/concepts/rules.png
new file mode 100644
index 00000000..390a60c9
Binary files /dev/null and b/v2/images/concepts/rules.png differ
diff --git a/v2/images/concepts/rules_default.png b/v2/images/concepts/rules_default.png
new file mode 100644
index 00000000..ea3f4c1e
Binary files /dev/null and b/v2/images/concepts/rules_default.png differ
diff --git a/v2/images/concepts/rules_distributions.png b/v2/images/concepts/rules_distributions.png
new file mode 100644
index 00000000..e7086199
Binary files /dev/null and b/v2/images/concepts/rules_distributions.png differ
diff --git a/v2/images/concepts/segments.png b/v2/images/concepts/segments.png
new file mode 100644
index 00000000..5ddbe8d0
Binary files /dev/null and b/v2/images/concepts/segments.png differ
diff --git a/v2/images/configuration/environments/storage-dark.svg b/v2/images/configuration/environments/storage-dark.svg
new file mode 100644
index 00000000..95cfc05d
--- /dev/null
+++ b/v2/images/configuration/environments/storage-dark.svg
@@ -0,0 +1,182 @@
+
diff --git a/v2/images/configuration/environments/storage-light.svg b/v2/images/configuration/environments/storage-light.svg
new file mode 100644
index 00000000..9a61d322
--- /dev/null
+++ b/v2/images/configuration/environments/storage-light.svg
@@ -0,0 +1,110 @@
+
diff --git a/v2/images/configuration/environments/storage.d2 b/v2/images/configuration/environments/storage.d2
new file mode 100644
index 00000000..694c7396
--- /dev/null
+++ b/v2/images/configuration/environments/storage.d2
@@ -0,0 +1,65 @@
+vars: {
+ d2-config: {
+ layout-engine: elk
+ }
+}
+
+direction: right
+
+style: {
+ fill: transparent
+}
+
+classes: {
+ github: {
+ shape: image
+ icon: https://icons.terrastruct.com/dev%2Fgithub.svg
+ style.font-size: 24
+ style.fill: transparent
+ style.stroke-width: 1
+ }
+ box: {
+ style.fill: transparent
+ }
+ solid: {
+ style.stroke-width: 1
+ }
+ dashed: {
+ style.stroke-width: 1
+ style.stroke-dash: 5
+ }
+}
+
+E1: "Environment A\n(path: /env-a)" {
+ class: box
+}
+E2: "Environment B\n(path: /env-b)" {
+ class: box
+}
+E3: "Environment C" {
+ class: box
+}
+
+FS: "Filesystem Backend" {
+ class: box
+}
+MEM: "In-Memory Backend" {
+ class: box
+}
+
+GitFS: "GitHub Repo A" {
+ class: github
+}
+
+GitMEM: "GitHub Repo B" {
+ class: github
+}
+
+# Environment to Storage mappings
+E1 -> FS { class: solid }
+E2 -> FS { class: solid }
+E3 -> MEM { class: solid }
+
+# Storage to Git remotes
+FS <-> GitFS: "optional sync" { class: dashed }
+MEM <-> GitMEM: "optional sync" { class: dashed }
diff --git a/v2/images/configuration/observability/datadog_otlp.png b/v2/images/configuration/observability/datadog_otlp.png
new file mode 100644
index 00000000..6bd022ac
Binary files /dev/null and b/v2/images/configuration/observability/datadog_otlp.png differ
diff --git a/v2/images/configuration/storage/credentials-dark.svg b/v2/images/configuration/storage/credentials-dark.svg
new file mode 100644
index 00000000..ceb8f05e
--- /dev/null
+++ b/v2/images/configuration/storage/credentials-dark.svg
@@ -0,0 +1,171 @@
+
diff --git a/v2/images/configuration/storage/credentials-light.svg b/v2/images/configuration/storage/credentials-light.svg
new file mode 100644
index 00000000..c479a7d2
--- /dev/null
+++ b/v2/images/configuration/storage/credentials-light.svg
@@ -0,0 +1,99 @@
+
diff --git a/v2/images/configuration/storage/credentials.d2 b/v2/images/configuration/storage/credentials.d2
new file mode 100644
index 00000000..8f517370
--- /dev/null
+++ b/v2/images/configuration/storage/credentials.d2
@@ -0,0 +1,58 @@
+vars: {
+ d2-config: {
+ layout-engine: elk
+ }
+}
+
+direction: right
+
+style: {
+ fill: transparent
+}
+
+classes: {
+ github: {
+ shape: image
+ icon: https://icons.terrastruct.com/dev%2Fgithub.svg
+ style.font-size: 24
+ style.fill: transparent
+ style.stroke-width: 1
+ }
+ box: {
+ style.fill: transparent
+ }
+ solid: {
+ style.stroke-width: 1
+ }
+ dashed: {
+ style.stroke-width: 1
+ style.stroke-dash: 5
+ }
+}
+
+SA: "Storage A" {
+ class: box
+}
+SB: "Storage B" {
+ class: box
+}
+
+GitA: "GitHub Repo A" {
+ class: github
+}
+
+GitB: "GitHub Repo B" {
+ class: github
+}
+
+Creds: "GitHub Credentials" {
+ class: box
+ near: center-right
+}
+
+# Storage to Git remotes
+SA <-> GitA { class: solid }
+SB <-> GitB { class: solid }
+
+Creds -> GitA { class: solid }
+Creds -> GitB { class: solid }
diff --git a/v2/images/quickstart/create_constraint.png b/v2/images/quickstart/create_constraint.png
new file mode 100644
index 00000000..145107e1
Binary files /dev/null and b/v2/images/quickstart/create_constraint.png differ
diff --git a/v2/images/quickstart/create_flag.png b/v2/images/quickstart/create_flag.png
new file mode 100644
index 00000000..2eac2626
Binary files /dev/null and b/v2/images/quickstart/create_flag.png differ
diff --git a/v2/images/quickstart/create_rule.png b/v2/images/quickstart/create_rule.png
new file mode 100644
index 00000000..2f777e7d
Binary files /dev/null and b/v2/images/quickstart/create_rule.png differ
diff --git a/v2/images/quickstart/create_segment.png b/v2/images/quickstart/create_segment.png
new file mode 100644
index 00000000..39a9e988
Binary files /dev/null and b/v2/images/quickstart/create_segment.png differ
diff --git a/v2/images/quickstart/create_variant.png b/v2/images/quickstart/create_variant.png
new file mode 100644
index 00000000..39ae01f7
Binary files /dev/null and b/v2/images/quickstart/create_variant.png differ
diff --git a/v2/images/quickstart/default.png b/v2/images/quickstart/default.png
new file mode 100644
index 00000000..da75ab72
Binary files /dev/null and b/v2/images/quickstart/default.png differ
diff --git a/v2/images/quickstart/evaluation_console.png b/v2/images/quickstart/evaluation_console.png
new file mode 100644
index 00000000..c4b21a44
Binary files /dev/null and b/v2/images/quickstart/evaluation_console.png differ
diff --git a/v2/introduction.mdx b/v2/introduction.mdx
new file mode 100644
index 00000000..012aa809
--- /dev/null
+++ b/v2/introduction.mdx
@@ -0,0 +1,60 @@
+---
+title: Introduction
+description: This document describes the features and benefits of Flipt v2.
+mode: "wide"
+---
+
+import V2Alpha from "/snippets/v2-alpha.mdx";
+
+
+
+Flipt v2 is a major new version of Flipt that is built to be Git-native and
+support a more flexible and powerful feature management platform.
+
+## Differences from v1
+
+Flipt v2 introduces a number of new features and capabilities that are not available in v1 while maintaining backwards compatibility with v1.
+
+### Git-Native
+
+Flipt v2 is built to be Git-native, meaning that your feature flags and configurations are stored in your own Git repositories. This allows you to use your existing Git workflow and tools to manage your feature flags and configurations.
+
+We modeled Flipt v2 after our [Flipt Cloud](/cloud/overview) product, but with the ability to self-host.
+
+import Cloud from "/snippets/cloud.mdx";
+
+
+
+While Flipt v1 has the ability to read flag data from a Git repository, Flipt v2 takes this one step further by allowing you to write flag data to a Git repository using the Flipt v2 API and UI.
+
+We believe that Git is the best way to manage configuration data. We also believe that feature flags are a type of configuration data, and as such, they should be stored in the same way.
+
+By combining the power of Git with a user-friendly interface, Flipt v2 offers the best of both worlds: the robustness and version control of Git-backed storage, and the ease of use of a modern feature flag management system.
+
+### Real-Time Client Updates (In Development)
+
+Flipt v2 introduces a new streaming API that allows you to subscribe to changes on the Flipt server and update the state of the flags accordingly in real-time. This means you'll be able to see changes to flags and configurations as they are made, without having to poll the Flipt server for updates.
+
+### Multi-Environment
+
+Flipt v2 introduces the concept of environments, which are an additional layer above Flipt v1's concept of [Namespaces](/concepts#namespace).
+
+Environments allow you to manage your feature flags and configurations in different several ways including:
+
+- Different Git repositories
+- Different directories within the same Git repository
+- Different branches within the same directory
+
+Each environment has its own set of namespaces, feature flags and configurations, and is completely isolated from the others.
+
+### No External Dependencies
+
+Flipt v2 is a standalone binary that does not depend on any external services. This means that you can run Flipt v2 on any machine that has a compatible operating system.
+
+V2 does not require any database or cache by default. Even the git-backed storage is local by default either in memory or on disk. You can configure Flipt v2 to sync your local git-backed storage to a remote git repository such as GitHub, GitLab, or Bitbucket.
+
+### Declarative APIs
+
+Flipt v2 introduces a declarative API for managing feature flags and configurations. This allows you to manage your feature flags and configurations in a declarative way, using a simple JSON schema.
+
+Flipt v2 works on the principle of managing resources. A resource is a collection of related configurations that are managed together. Feature flags are just one type of resource and are managed through the Flipt v2 API.
diff --git a/v2/quickstart.mdx b/v2/quickstart.mdx
new file mode 100644
index 00000000..31add852
--- /dev/null
+++ b/v2/quickstart.mdx
@@ -0,0 +1,183 @@
+---
+title: Quickstart
+description: This document describes how to get started with Flipt v2.
+mode: "wide"
+---
+
+import V2Alpha from "/snippets/v2-alpha.mdx";
+
+
+
+## Setup
+
+Before getting started, make sure the Flipt server is up and running on your
+host on your chosen ports.
+
+
+ Our pre-release version is built on every merge to the `v2` branch and only available as a Docker image at the moment.
+
+Once we release a stable version, we'll update the installation instructions to include binary, Helm, and Homebrew installation options.
+
+
+
+
+
+```console Docker
+docker run -d \
+ -p 8080:8080 \
+ -p 9000:9000 \
+ -v $HOME/flipt:/var/opt/flipt \
+ docker.flipt.io/flipt/flipt:v2-alpha
+```
+
+
+
+In this example, we'll use the default location of http://localhost:8080.
+
+## Environments and Namespaces
+
+Flipt v2 introduces the concept of environments in addition to namespaces.
+
+By default, Flipt v2 will create a single environment called `default` along with the `default` namespace.
+
+
+
+Environments are managed via configuration files. See the [Environments](/v2/concepts#environments) documentation for more.
+
+## Flags and Variants
+
+First, we'll create a flag and variants that we will use to evaluate against in the default environment and namespace.
+
+### Create a Flag
+
+A flag is the basic entity in Flipt. Flags can represent features in your
+applications that you want to enable/disable for your users.
+
+To create a flag:
+
+1. Open the UI at http://localhost:8080.
+2. Click `New Flag`.
+3. Select the `Variant` type.
+4. Populate the details of the flag as shown.
+5. Click `Enabled` so the flag will be enabled once created.
+6. Click `Create`.
+
+
+
+### Create Variants
+
+Variants allow you to return different values for your flags based on rules that
+you define.
+
+To create a variant:
+
+1. On the page for the flag you just created, click `Create Variant`.
+2. Populate the details of the variant as shown.
+3. Click `Add`.
+4. Create one more variant populating the information as you wish.
+5. Click `Update` to save the flag and variants.
+
+
+
+Click `Flags` in the navigation menu and you should now see your newly created
+flag in the list.
+
+## Segments and Constraints
+
+Next, we'll create a segment with a constraint that will be used to determine the
+reach of your flag.
+
+### Create a Segment
+
+Segments are used to split your user base into subsets.
+
+To create a segment:
+
+1. From the navigation click `Segments`.
+2. Click `New Segment`.
+3. Populate the details of the segment as shown.
+4. Click `Create`.
+
+
+
+### Create a Constraint
+
+Constraints are used to target a specific segment.
+
+
+ Constraints aren't required to match a segment. A segment with no constraints
+ will match every request by default.
+
+
+To create a constraint:
+
+1. On the page for the segment you just created, click `Create Constraint`.
+2. Populate the details of the constraint as shown.
+3. Click `Add`.
+4. Click `Update` to save the segment and constraint.
+
+
+
+Click `Segments` in the navigation menu and you should now see your newly
+created segment in the list.
+
+## Rules and Distributions
+
+Finally, we'll create a rule defining a distribution for your flag and variants.
+Rules allow you to define which variant gets returned when you
+evaluate a specific flag that falls into a given segment.
+
+### Create a Rule
+
+To create a rule:
+
+1. Go back to the flag you created at the beginning.
+2. Scroll down and click the `Rules` tab.
+3. Click `New Rule`.
+4. Next to `Segment` choose or search for the segment you created earlier.
+5. Next to `Type` choose `Multi-Variate`.
+6. You should see the two variants that you created earlier, with a percentage
+ of `50%` each.
+7. Click `Add`.
+8. Click `Update` to save the rule.
+
+
+
+A distribution is a way of assigning a percentage for which entities evaluated
+get a specific variant. The higher the percentage assigned, the more likely it
+is that any entity will get that specific variant.
+
+
+ You could just as easily have picked `Single Variant` instead of
+ `Multi-Variate` when setting up your rule. This would effectively mean you
+ have a single distribution, a variant with `100%` chance of being returned.
+
+
+## Evaluation Console
+
+After creating the above flag, segment and targeting rule, you're now ready to
+test how this would work in your application.
+
+The Flipt UI contains an Evaluation Console to allow you to experiment
+with different requests to see how they would be evaluated.
+
+The main ideas behind how evaluation works are described in more detail in the
+[Concepts](/concepts#evaluation) documentation.
+
+To test evaluation:
+
+1. Navigate to the `Console` page from the main navigation.
+2. Select or search for the flag you created earlier.
+3. Notice that the `Entity ID` field is pre-populated with a random UUID. This represents
+ the ID that you would use to uniquely identify entities (ex: users) that you
+ want to test against your flags.
+4. Click `Evaluate`.
+5. Note the pane to the right has been populated with the evaluation
+ response from the server, informing you that this request would match the
+ segment that you created earlier, and return one of the variants defined.
+6. Experiment with different values for the `Request Context` and `Entity ID` fields.
+
+
+That's it! You're now ready to integrate Flipt into your applications and start
+defining your flags and segments that will enable you to seamlessly rollout
+new features to your users while reducing risk.
## Control Plane
@@ -53,11 +53,11 @@ Flipt Cloud supports evaluation for our [client-side SDKs](/integration/client)
[Server-side SDKs](/integration/server) including [OpenFeature SDKs](/integration/openfeature) are also supported but currently require you to run your own Flipt instances.
@@ -72,11 +72,11 @@ To scale evaluation requests and serve feature flag evaluations via our server-s
### Client-Side Evaluation
@@ -85,11 +85,11 @@ You can also run your own Flipt Open Source instances and configure our client-s
For more information on how to deploy Flipt Open Source and how to configure it to source flag data from your Git repository, please refer to the [Moving to Production](/cloud/guides/production) guide.
diff --git a/cloud/features/approval-workflows.mdx b/cloud/features/approval-workflows.mdx
index 366a74cf..cd2d31d0 100644
--- a/cloud/features/approval-workflows.mdx
+++ b/cloud/features/approval-workflows.mdx
@@ -6,7 +6,7 @@ mode: "wide"
Flipt Cloud provides a built-in approval workflow system that allows you to easily manage and track the proposal and approval process for your flags, ensuring that they are approved by the appropriate stakeholders before they are released to production.
-
+
## Overview
@@ -28,7 +28,7 @@ The approval workflow system is designed to fit into this process, and to make i
When you create an environment in Flipt Cloud, you can choose to protect the environment. This will require that all flag and other configuration changes go through a review and approval process before they are served from the environment.
-
+
In our Git backed storage model, all environments have a default branch. If you chose an existing repository and branch when creating the environment and that branch is protected, the environment itself will be protected by default.
@@ -39,17 +39,17 @@ In our Git backed storage model, all environments have a default branch. If you
Protected environments are read-only and can only be changed by going through the proposal/approval process. If you are in a protected environment, you will see the 'Protected' badge in the top right of the environment.
-
+
## Approval Process
To make a change for a protected environment, you will need to put the environment into 'editing mode' by clicking on the 'Protected' badge. This will prompt a confirmation dialog asking you to confirm that you want to create a proposal branch to make your changes.
-
+
Once you click 'Create Branch', you will be redirected to a new environment that is no longer protected. This environment is a full read/write replica of the protected environment, but any changes you make will not be deployed to the protected environment until they are approved and merged.
-
+
You can make changes to the unprotected environment, and they will be captured in the proposal branch. Once you are ready to deploy your changes, you can create a pull request into the protected environment.
@@ -57,25 +57,25 @@ You can make changes to the unprotected environment, and they will be captured i
After making the changes you want to propose, you can create a proposal by clicking on the 'Propose' button in the top right of the screen. This will again prompt a confirmation dialog asking you to confirm that you want to create a new pull request in your repository and add it to the approval workflow.
-
+
Once you click 'Create Proposal', you will see a badge in the top right of the screen indicating that a proposal is pending, with a link to the proposal pull request.
-
+
Clicking on the badge will take you to the proposal pull request.
-
+
## Approve and Merge
Your team can review the proposal and approve it by clicking on the 'Approve' button in the pull request. Once the proposal is approved, you will be able to merge the pull request into the protected environment.
-
+
Once the pull request is merged, the changes will be deployed to the protected environment.
-
+
+
+
+### Directories
+
+Each environment has an optional `directory` configuration field that is used to determine the directory that will be used to store the environment's resources.
+
+This is only required if multiple environments share the same storage backend, as Flipt needs to know where to ultimately store the state without conflicting with other environments.
+
+```yaml
+environments:
+ foo:
+ directory: "foo"
+ storage: "local"
+ bar:
+ directory: "bar"
+ storage: "local"
+```
+
+In the above configuration, the `foo` and `bar` environments will use the same `local` storage backend but will store their resources in different directories.
+
+## Default
+
+Each environment has a default configuration field that is used to determine if the environment is the default environment.
+
+The default environment is the environment that will be used when no other environment is specified.
+
+```yaml
+environments:
+ local:
+ default: true
+```
+
+This means that if no environment is specified when performing actions such as flag evaluation, creation, or updates, the `local` environment will be used. This will also be the environment that is selected in the UI by default.
diff --git a/v2/configuration/observability.mdx b/v2/configuration/observability.mdx
new file mode 100644
index 00000000..0bd3cb51
--- /dev/null
+++ b/v2/configuration/observability.mdx
@@ -0,0 +1,161 @@
+---
+title: Observability
+description: This document describes how to configure observability mechanisms including metrics, logging, and tracing for Flipt v2.
+---
+
+## Metrics
+
+### Prometheus
+
+Flipt exposes [Prometheus](https://prometheus.io/) metrics by default at the `/metrics`
+HTTP endpoint. To see which metrics are currently supported, point your browser
+to `FLIPT_HOST/metrics` (ex: `localhost:8080/metrics`).
+
+You should see a bunch of metrics being recorded such as:
+
+```yaml
+flipt_cache_hit_total{cache="memory",type="flag"} 1
+flipt_cache_miss_total{cache="memory",type="flag"} 1
+---
+go_gc_duration_seconds{quantile="0"} 8.641e-06
+go_gc_duration_seconds{quantile="0.25"} 2.499e-05
+go_gc_duration_seconds{quantile="0.5"} 3.5359e-05
+go_gc_duration_seconds{quantile="0.75"} 6.6594e-05
+go_gc_duration_seconds{quantile="1"} 0.00026651 go_gc_duration_seconds_sum
+0.000402094 go_gc_duration_seconds_count 5
+```
+
+
+
+
+#### Basic
+
+Basic authentication is a username and password pair.
+
+