Extracting common quickstart texts into components (#2846)

* ✨ Creating an `<Intro>` component for quickstarts

* ✨ refs #2846 Creating components for the General Architecture section

* ✨ refs #2846 Creating component for the "Run FusionAuth via Docker" section

* ✨ refs #2846 Creating components for the "Next Steps" section

* 🦺 refs #2846 Adding `codeRoot` as an optional frontmatter attribute and making them all camelCase

* ✏️ refs #2846 Fixing typo

* ♻️ refs #2846 Renaming `withTeller` prop to `api` at the `DockerSpinup` quickstart component

* ✏️ refs #2846 Rewording "add .env files to .gitignore" to ignore kickstart.json

astro/src/components/quickstarts/DockerSpinup.astro

@@ -0,0 +1,59 @@
+---
+import Aside from 'src/components/Aside.astro';
+import Code from 'astro/components/Code.astro';
+import { RemoteValue } from '@fusionauth/astro-components';
+
+export interface Props {
+  /**
+   * Full URI to extract values from kickstart.json
+   * e.g. https://raw.githubusercontent.com/FusionAuth/fusionauth-quickstart-ruby-on-rails-web/main/kickstart/kickstart.json
+   */
+  kickstartUri: string;
+
+  /**
+   * Flag that indicates whether this in API quickstart or not (default)
+   */
+  api?: boolean;
+}
+
+const { kickstartUri, api = false } = Astro.props as Props;
+---
+<p>You'll find a Docker Compose file (<code>docker-compose.yml</code>) and an environment variables configuration file (<code>.env</code>) in the root directory of the repo.</p>
+
+<p>Assuming you have Docker installed, you can stand up FusionAuth on your machine with the following.</p>
+
+<Code lang="shell" code="docker compose up -d" />
+
+<p>Here you are using a bootstrapping feature of FusionAuth called <a href="/docs/get-started/download-and-install/development/kickstart">Kickstart</a>. When FusionAuth comes up for the first time, it will look at the <code>kickstart/kickstart.json</code> file and configure FusionAuth to your specified state.</p>
+
+<Aside type="note">
+    <p>If you ever want to reset the FusionAuth application, you need to delete the volumes created by Docker Compose by executing <code style="white-space: nowrap">docker compose down -v</code>, then re-run <code>docker compose up -d</code>.</p>
+</Aside>
+
+<p>FusionAuth will be initially configured with these settings:</p>
+
+<ul>
+    <li>Your client Id is <code><RemoteValue url={kickstartUri} selector="$.variables.applicationId" /></code>.</li>
+    <li>Your client secret is <code><RemoteValue url={kickstartUri} selector={($) => $.variables.clientSecret || $.requests.find(r => r.url === '/api/application/#{applicationId}').body.application.oauthConfiguration.clientSecret} /></code>.</li>
+    {(api)
+      ? (
+        <li>Your example teller username is <code><RemoteValue url={kickstartUri} selector="$.variables.tellerEmail" /></code> and the password is <code><RemoteValue url={kickstartUri} selector="$.variables.tellerPassword" /></code>. They will have the role of <code>teller</code>.</li>
+        <li>Your example customer username is <code><RemoteValue url={kickstartUri} selector="$.variables.customerEmail" /></code> and the password is <code><RemoteValue url={kickstartUri} selector="$.variables.customerPassword" /></code>. They will have the role of <code>customer</code>.</li>
+      )
+      : (
+        <li>Your example username is <code><RemoteValue url={kickstartUri} selector="$.variables.userEmail" /></code> and the password is <code><RemoteValue url={kickstartUri} selector="$.variables.userPassword" /></code>.</li>
+      )
+    }
+    <li>Your admin username is <code><RemoteValue url={kickstartUri} selector="$.variables.adminEmail" /></code> and the password is <code><RemoteValue url={kickstartUri} selector="$.variables.adminPassword" /></code>.</li>
+    <li>The base URL of FusionAuth is <code>http://localhost:9011/</code>.</li>
+</ul>
+
+<p>You can log in to the <a href="http://localhost:9011/admin">FusionAuth admin UI</a> and look around if you want to, but with Docker and Kickstart, everything will already be configured correctly.</p>
+
+<Aside type="note">
+    <p>If you want to see where the FusionAuth values came from, they can be found in the <a href="http://localhost:9011/admin">FusionAuth app</a>. The tenant Id is found on the Tenants page. To see the Client Id and Client Secret, go to the Applications page and click the <code>View</code> icon under the actions for the ChangeBank application. You'll find the Client Id and Client Secret values in the <code>OAuth configuration</code> section.</p>
+</Aside>
+
+<Aside type="caution">
+    <p>The <code>.env</code> file contains passwords. In a real application, always add this file to your <code>.gitignore</code> file and never commit secrets to version control.</p>
+</Aside>

astro/src/components/quickstarts/Intro.astro

@@ -0,0 +1,49 @@
+---
+/**
+  * Using parenthesis due to @link https://github.com/withastro/compiler/issues/749
+  */
+type InnerProps = ({
+  /**
+   * Technology used to build the application.
+   */
+  technology: string;
+  /**
+   * Indicate that this intro is for API quickstarts.
+   * @default false
+   */
+  api?: boolean;
+} | {
+  /**
+   * If the default "you are going to build an application with <technology"> text doesn't apply, you can pass the
+   * entire text here.
+   */
+  fulltext: string;
+});
+
+export type Props = (InnerProps & {
+  /**
+   * URL for the source code location
+   */
+  repositoryUrl: string;
+});
+
+const { technology, fulltext, repositoryUrl, api = false } = Astro.props as Props;
+---
+{(api) ? (
+    <p>
+        In this quickstart, you are going to learn how to integrate a {technology} resource server with FusionAuth.
+        You will protect an API resource from unauthorized usage.
+        You’ll be building it for <a href="https://www.youtube.com/watch?v=CXDxNCzUspM">ChangeBank</a>, a global leader in converting dollars into coins.
+        <slot/>
+    </p>
+) : (
+    <p>
+        In this quickstart, you are going to build {fulltext || `an application with ${technology}`} and integrate it with FusionAuth.
+        You’ll be building it for <a href="https://www.youtube.com/watch?v=CXDxNCzUspM">ChangeBank</a>, a global leader in converting dollars into coins.
+        It’ll have areas reserved for users who have logged in as well as public facing sections.
+        <slot/>
+    </p>
+)}
+<p>
+    The Docker Compose file and source code for a complete application are available at <a href={repositoryUrl}>{repositoryUrl}</a>.
+</p>

astro/src/components/quickstarts/LoginArchitectureApi.astro

@@ -0,0 +1,8 @@
+---
+import Diagram from 'src/diagrams/quickstarts/resource-server.astro';
+---
+<p>A client wants access to an API resource at <code>/resource</code>. However, it is denied this resource until it acquires an access token from FusionAuth.</p>
+
+<Diagram />
+
+<p>While the access token is acquired via the Login API above, this is for simplicity of illustration. The token can be, and typically is, acquired through one of the <a href="/docs/lifecycle/authenticate-users/oauth/">OAuth grants</a>.</p>

astro/src/components/quickstarts/LoginArchitectureNative.astro

@@ -0,0 +1,15 @@
+---
+import LoginAfterNative from 'src/diagrams/quickstarts/login-after-native.astro';
+import LoginBeforeNative from 'src/diagrams/quickstarts/login-before-native.astro';
+---
+<p>While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth.</p>
+
+<p>In that case, the system might look like this before FusionAuth is introduced.</p>
+
+<LoginBeforeNative/>
+
+<p>The login flow will look like this after FusionAuth is introduced.</p>
+
+<LoginAfterNative/>
+
+<p>In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth.</p>

astro/src/components/quickstarts/LoginArchitectureSdk.astro

@@ -0,0 +1,14 @@
+---
+import LoginAfterSdk from 'src/diagrams/quickstarts/login-after-sdk.astro';
+import LoginBefore from 'src/diagrams/quickstarts/login-before.astro';
+---
+<p>While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth.</p>
+<p>In that case, the system might look like this before FusionAuth is introduced.</p>
+
+<LoginBefore/>
+
+<p>The login flow will look like this after FusionAuth is introduced.</p>
+
+<LoginAfterSdk/>
+
+<p>In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth.</p>

astro/src/components/quickstarts/LoginArchitectureWeb.astro

@@ -0,0 +1,29 @@
+---
+import LoginAfter from 'src/diagrams/quickstarts/login-after.astro';
+import LoginBefore from 'src/diagrams/quickstarts/login-before.astro';
+
+export interface Props {
+  /**
+   * Custom introduction text if the default one doesn't apply
+   */
+  intro?: string;
+}
+
+const { intro } = Astro.props;
+
+---
+{(intro)
+  ? (<p>{intro}</p>)
+  : (
+    <p>While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth.</p>
+    <p>In that case, the system might look like this before FusionAuth is introduced.</p>
+  )
+}
+
+<LoginBefore/>
+
+<p>The login flow will look like this after FusionAuth is introduced.</p>
+
+<LoginAfter/>
+
+<p>In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth.</p>

astro/src/components/quickstarts/NextSteps.astro

@@ -0,0 +1,27 @@
+<p>This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do.</p>
+
+<h3>FusionAuth Customization</h3>
+
+<p>FusionAuth gives you the ability to customize just about everything to do with the user's experience and the integration of your application. This includes:</p>
+
+<ul>
+    <li><a href="/docs/customize/look-and-feel/">Hosted pages</a> such as login, registration, email verification, and many more.</li>
+    <li><a href="/docs/customize/email-and-messages/email-templates">Email templates</a>.</li>
+    <li><a href="/articles/tokens/jwt-components-explained">User data and custom claims in access token JWTs</a>.</li>
+</ul>
+
+<h3>Security</h3>
+
+<ul>
+    <slot name="security"/>
+    <li>You may want to customize the <a href="/docs/lifecycle/authenticate-users/oauth/">token expiration times and policies</a> in FusionAuth.</li>
+    <li>Choose <a href="/docs/get-started/core-concepts/tenants#password">password rules</a> and a <a href="/docs/reference/password-hashes">hashing algorithm</a> that meet your security needs.</li>
+</ul>
+
+<h3>Tenant and Application Management</h3>
+
+<ul>
+    <li>Model your application topology using <a href="/docs/get-started/core-concepts/applications">Applications</a>, <a href="/docs/get-started/core-concepts/roles">Roles</a>, <a href="/docs/get-started/core-concepts/groups">Groups</a>, <a href="/docs/get-started/core-concepts/groups">Entities</a>, and more.</li>
+    <li>Set up <a href="/docs/lifecycle/authenticate-users/multi-factor-authentication">MFA</a>, <a href="/docs/lifecycle/authenticate-users/identity-providers/">Social login</a>, or <a href="/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2">SAML</a> integrations.</li>
+    <li>Integrate with external systems using <a href="/docs/extend/events-and-webhooks/">Webhooks</a>, <a href="/docs/lifecycle/migrate-users/scim/scim">SCIM</a>, and <a href="/docs/extend/code/lambdas/">Lambdas</a>.</li>
+</ul>

astro/src/components/quickstarts/NextStepsApi.astro

@@ -0,0 +1,16 @@
+<p>This quickstart is a great way to get a proof of concept up and running quickly, but to run your API in production, there are some things you're going to want to do.</p>
+
+<h3>FusionAuth Integration</h3>
+
+<ul>
+    <li>Rather than call the Login API, you're probably going to want to use the <a href="/docs/lifecycle/authenticate-users/oauth/#example-authorization-code-grant">Authorization Code grant</a>, which keeps all sensitive credentials within the bounds of FusionAuth. You can customize the <a href="/docs/customize/look-and-feel/">hosted login pages</a>.</li>
+    <li>You may want to generate a token using the <a href="/docs/lifecycle/authenticate-users/oauth/#example-client-credentials-grant">Client Credentials grant</a> if you are calling the API from another service.</li>
+</ul>
+
+<h3>Security</h3>
+
+<ul>
+    <li>Customize the <a href="/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings">token expiration times and policies</a> in FusionAuth</li>
+    <li><a href="/articles/tokens/building-a-secure-jwt#consuming-a-jwt">Make sure you know how to securely consume a token</a></li>
+    <li>Secure your API <a href="/docs/extend/examples/api-gateways/">using an API gateway</a> rather than at the framework layer.</li>
+</ul>

astro/src/content/config.js

@@ -43,6 +43,7 @@ const quickstartsCollection = defineCollection({
     featured: z.boolean().default(false),
     faIcon: z.string().optional(),
     color: z.string().optional(),
+    codeRoot: z.string().optional(),
   }),
 });
 

astro/src/content/quickstarts/5-minute-docker.mdx

@@ -1,6 +1,6 @@
 ---
 title: Docker Install For the 5-Minute Guide
-description: Use Docker and docker compose for the 5-minute guide.
+description: Use Docker and Docker Compose for the 5-minute guide.
 section: five-minute
 icon: /img/icons/5minute-docker.svg
 faIcon: fa-gem
@@ -20,9 +20,9 @@ import FiveMinuteSummingUp from 'src/content/quickstarts/_5-minute-summing-up.md
 import { YouTube } from '@astro-community/astro-embed-youtube';
 
 
-You've chosen to install FusionAuth via docker and docker compose.
+You've chosen to install FusionAuth via Docker and Docker Compose.
 
-This is the best option if you have docker installed locally or you plan to run FusionAuth in a Docker compatible environment such as Kubernetes and want to learn more about how FusionAuth runs in Docker.
+This is the best option if you have Docker installed locally or you plan to run FusionAuth in a Docker compatible environment such as Kubernetes and want to learn more about how FusionAuth runs in Docker.
 
 If you've arrived here directly, start with the [5-Minute Setup Guide Overview](/docs/quickstarts/5-minute-setup-guide).
 
@@ -50,7 +50,7 @@ Here are steps to take to set up FusionAuth and configure it to provide login an
 
 ## 1. Install and Start FusionAuth
 
-You are following the Docker 5 minute guide, so you'll use `docker-compose`.
+You are following the Docker 5 minute guide, so you'll use `docker compose`.
 
 <DockerComposeFiles with_elasticsearch />
 
@@ -93,4 +93,4 @@ And that's it! Docker makes standing up a FusionAuth instance a snap. Next, crea
 
 ## 9. Summing Up
 
-<FiveMinuteSummingUp />
+<FiveMinuteSummingUp />

astro/src/content/quickstarts/quickstart-android-java-native.mdx

@@ -12,17 +12,16 @@ color: indigo
 cta: EmailListCTA
 ---
 import Aside from '../../components/Aside.astro';
-import LoginAfter from '../../diagrams/quickstarts/login-after-native.astro';
-import LoginBefore from '../../diagrams/quickstarts/login-before-native.astro';
+import DockerSpinup from '/src/components/quickstarts/DockerSpinup.astro';
 import IconButton from '../../components/IconButton.astro';
+import Intro from '/src/components/quickstarts/Intro.astro';
+import LoginArchitectureWeb from '/src/components/quickstarts/LoginArchitectureWeb.astro';
+import NextSteps from '/src/components/quickstarts/NextSteps.astro';
 import {RemoteCode} from '@fusionauth/astro-components';
 
-In this quickstart you are going to build an Android app with Java and integrate it with FusionAuth.
-You'll be building it for [ChangeBank](https://www.youtube.com/watch?v=CXDxNCzUspM), a global leader in converting dollars into coins.
-It'll have areas reserved for users who have logged in as well as public facing sections.
+<Intro fulltext="an Android app with Java"
+       repositoryUrl="https://github.com/FusionAuth/fusionauth-quickstart-java-android-native"/>
 
-The docker compose file and source code for a complete application are available at
-[https://github.com/FusionAuth/fusionauth-quickstart-java-android-native](https://github.com/FusionAuth/fusionauth-quickstart-java-android-native).
 
 ## Prerequisites
 
@@ -35,17 +34,7 @@ This app was built on top of [AppAuth](https://github.com/openid/AppAuth-Android
 
 ## General Architecture
 
-While this sample application doesn't have login functionality without FusionAuth, a more typical integration will replace an existing login system with FusionAuth.
-
-In that case, the system might look like this before FusionAuth is introduced.
-
-<LoginBefore/>
-
-The login flow will look like this after FusionAuth is introduced.
-
-<LoginAfter/>
-
-In general, you are introducing FusionAuth in order to normalize and consolidate user data. This helps make sure it is consistent and up-to-date as well as offloading your login security and functionality to FusionAuth.
+<LoginArchitectureWeb />
 
 ## Getting Started
 
@@ -62,25 +51,7 @@ cd fusionauth-quickstart-java-android-native
 
 ### Run FusionAuth via Docker
 
-In the root directory of the repo you'll find a Docker compose file (`docker-compose.yml`) and an environment variables configuration file (`.env`). Assuming you have Docker installed on your machine, you can stand up FusionAuth up on your machine with:
-
-```
-docker compose up -d
-```
-
-Here you are using a bootstrapping feature of FusionAuth, called [Kickstart](/docs/get-started/download-and-install/development/kickstart). When FusionAuth comes up for the first time, it will look at the `kickstart/kickstart.json` file and configure FusionAuth to a certain initial state.
-
-<Aside type="note">
-    If you ever want to reset the FusionAuth system, delete the volumes created by docker compose by executing `docker compose down -v`, then re-run `docker compose up -d`.
-</Aside>
-
-FusionAuth will be initially configured with these settings:
-
-* Your client Id is `e9fdb985-9173-4e01-9d73-ac2d60d1dc8e`.
-* Your client secret is `super-secret-secret-that-should-be-regenerated-for-production`.
-* Your example username is `[email protected]` and the password is `password`.
-* Your admin username is `[email protected]` and the password is `password`.
-* The base URL of FusionAuth `http://localhost:9011/`.
+<DockerSpinup kickstartUri={frontmatter.codeRoot + "/kickstart/kickstart.json"} />
 
 ### Expose FusionAuth Instance
 
@@ -197,24 +168,12 @@ You can either [connect a hardware device](https://developer.android.com/studio/
 
 ## Next Steps
 
-This quickstart is a great way to get a proof of concept up and running quickly, but to run your application in production, there are some things you're going to want to do.
-
-### FusionAuth Customization
-
-FusionAuth gives you the ability to customize just about everything with the user's experience and your application's integration. This includes
-* [Hosted pages](/docs/customize/look-and-feel/) such as login, registration, email verification, and many more
-* [Email templates](/docs/customize/email-and-messages/email-templates)
-* [User data and custom claims in access token JWTs](/articles/tokens/jwt-components-explained)
-
-### Security
-* Implement refresh tokens using [AppAuth](https://github.com/openid/AppAuth-Android)
-* You may want to customize the [token expiration times and policies](/docs/lifecycle/authenticate-users/oauth/#configure-application-oauth-settings) in FusionAuth
-* Choose [password rules](/docs/get-started/core-concepts/tenants#password) and a [hashing algorithm](/docs/reference/password-hashes) that meet your security needs
+<NextSteps>
+  <Fragment slot="security">
+    <li>Implement refresh tokens using [AppAuth](https://github.com/openid/AppAuth-Android).</li>
+  </Fragment>
+</NextSteps>
 
-### Tenant and Application Management
-* Model your application topology using [Applications](/docs/get-started/core-concepts/applications), [Roles](/docs/get-started/core-concepts/roles), [Groups](/docs/get-started/core-concepts/groups), [Entities](/docs/get-started/core-concepts/groups), and more
-* Set up [MFA](/docs/lifecycle/authenticate-users/multi-factor-authentication), [Social login](/docs/lifecycle/authenticate-users/identity-providers/), and/or [SAML](/docs/lifecycle/authenticate-users/identity-providers/overview-samlv2) integrations
-* Integrate with external systems using [Webhooks](/docs/extend/events-and-webhooks/), [SCIM](/docs/lifecycle/migrate-users/scim/scim), and [Lambdas](/docs/extend/code/lambdas/)
 
 ## Troubleshooting