Merge pull request #1119 from aligent/feature/DO-1545_prerender_farga…

…te_documentation

DO-1545: Prerender Fargate Readme update

packages/prerender-fargate/README.md

@@ -1,18 +1,139 @@
-# Prerender in Fargate
-
-A construct to host [Prerender](https://github.com/prerender/prerender) in Fargate.
-
-## Props
-
-- `prerenderName`: Name of the Prerender service
-- `domainName`: Domain name for Prerender
-- `vpcId`: VPC to host Prerender in
-- `bucketName`: Optional S3 bucket name
-- `expirationDays`: Optional days until items expire in bucket (default to 7 days)
-- `tokenList`: List of tokens to accept as authentication
-- `certificateArn`: Certificate arn to match the domain
-- `desiredInstanceCount`: Number of Prerender instances to run (default 1)
-- `maxInstanceCount`: Maximum number of Prerender instances to run (default 2)
-- `instanceCPU`: CPU to allocate to each instance (default 512)
-- `instanceMemory`: Amount of memory to allocate to each instance (default 1024)
-- `enableRedirectCache`: Cache 301 and 302 responses, too (default false)
+# PrerenderFargate Construct
+
+The PrerenderFargate construct sets up an AWS Fargate service to run a [Prerender] service in an ECS Fargate cluster.  
+
+The Prerender server listens for an HTTP request, takes the URL, and loads it in Headless Chrome, waits for the page to finish loading, and then returns your content to the requesting client.
+
+## AWS Resources Created/Configured by this Construct
+
+- **S3 Bucket:** For storing prerendered web pages.
+- **Fargate Service:** For running the Prerender service.
+- **ECR Asset:** For managing the Docker image of the Prerender service.
+- **VPC & VPC Endpoints:** For network configuration and enabling direct access to S3.
+- **Recache API:** (optional) To trigger recaching of URLs.
+
+## Usage and PrerenderFargateOptions
+
+To use the PrerenderFargate construct, you can instantiate it with suitable PrerenderFargateOptions and place it within a CDK stack. The PrerenderOptions parameter allows the developer to customize various aspects of the Prerender service.
+
+### `prerenderName` (string)
+
+- The name of the Prerender service.
+
+### `domainName` (string)
+
+- The domain name to prerender.
+
+### `vpcId` (string, optional)
+
+- The ID of the VPC to deploy the Fargate service in.
+
+### `bucketName` (string, optional)
+
+- The name of the S3 bucket to store prerendered pages in.
+
+### `expirationDays` (number, optional)
+
+- The number of days to keep prerendered pages in the S3 bucket before expiring them.
+
+### `tokenList` (Array of strings, deprecated)
+
+- A list of tokens to use for authentication with the Prerender service. (This parameter is deprecated and will be removed in a future release. Please use the `tokenUrlAssociation` parameter instead. If `tokenUrlAssociation` is provided, `tokenList` will be ignored.)
+
+### `certificateArn` (string)
+
+- The ARN of the SSL certificate to use for HTTPS connections.
+
+### `desiredInstanceCount` (number, optional)
+
+- The desired number of Fargate instances to run.
+
+### `maxInstanceCount` (number, optional)
+
+- The maximum number of Fargate instances to run.
+
+### `minInstanceCount` (number, optional)
+
+- The minimum number of Fargate instances to run.
+
+### `instanceCPU` (number, optional)
+
+- The amount of CPU to allocate to each Fargate instance.
+
+### `instanceMemory` (number, optional)
+
+- The amount of memory to allocate to each Fargate instance.
+
+### `enableRedirectCache` (string, optional)
+
+- Whether to enable caching of HTTP redirects.
+
+### `enableS3Endpoint` (boolean, optional)
+
+- Whether to enable the [VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html) for S3.
+
+### `tokenUrlAssociation` (PrerenderTokenUrlAssociationOptions, optional)
+
+- Configuration for associating tokens with specific domain URLs. During the recaching process, these tokens will be used to validate the request.
+
+### `prerenderFargateScalingOptions` (PrerenderFargateScalingOptions, optional)
+
+- This allows to alter the scaling behavior. The default configuration should be sufficient for most of the cases.
+
+### `prerenderFargateRecachingOptions` (PrerenderFargateRecachingOptions, optional)
+
+- This allows to alter the re-caching behavior. The default configuration should be sufficient.
+
+## Example
+
+Here's an example of how to use the PrerenderFargate construct in a TypeScript CDK application:
+
+```typescript
+import { Stack, StackProps } from "aws-cdk-lib";
+import { Construct } from "constructs";
+import { PrerenderFargate, PrerenderFargateOptions } from "@aligent/cdk-prerender-fargate";
+
+
+export class RagPrerenderStackStack extends Stack {
+  constructor(scope: Construct, id: string, props: StackProps) {
+    super(scope, id, props);
+
+    new PrerenderFargate(this, "PrerenderService", {
+      prerenderName: "myPrerender",
+      bucketName: "myPrerenderBucket",
+      expirationDays: 7,
+      vpcId: "vpc-xxxxxxxx",
+      desiredInstanceCount: 1,
+      instanceCPU: 512,
+      instanceMemory: 1024,
+      domainName: "prerender.mydomain.com",
+      certificateArn:
+        "arn:aws:acm:region:account:certificate/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+      enableRedirectCache: "false",
+      maxInstanceCount: 2,
+      enableS3Endpoint: true,
+      tokenUrlAssociation: {
+        token1: ["https://example.com", "https://acme.example.com"],
+        token2: ["https://example1.com", "https:acme.example1.com"],
+      },
+      ssmPathPrefix: "/prerender/recache/tokens",
+      prerenderFargateRecachingOptions: {
+        maxConcurrentExecutions: 1,
+      },
+      prerenderFargateScalingOptions: {
+        healthCheckGracePeriod: 20,
+        healthCheckInterval: 30,
+        unhealthyThresholdCount: 3,
+        scaleInCooldown: 120,
+        scaleOutCooldown: 60,
+      },
+    });
+  }
+}
+```
+
+## Acknowledgements
+
+- [prerender.io](https://prerender.io/) - The Prerender service.
+
+[Prerender]:https://github.com/prerender/prerender

packages/prerender-fargate/lib/prerender-fargate-options.ts

@@ -14,6 +14,7 @@ export interface PrerenderFargateOptions {
   domainName: string;
   /**
    * The ID of the VPC to deploy the Fargate service in.
+   * @default - The default VPC will be used
    */
   vpcId?: string;
   /**
@@ -22,6 +23,7 @@ export interface PrerenderFargateOptions {
   bucketName?: string;
   /**
    * The number of days to keep prerendered pages in the S3 bucket before expiring them.
+   * @default - 10 days
    */
   expirationDays?: number;
   /**
@@ -37,30 +39,37 @@ export interface PrerenderFargateOptions {
   certificateArn: string;
   /**
    * The minimum number of Fargate instances to run.
+   * @default - 1
    */
   minInstanceCount?: number;
   /**
    * The desired number of Fargate instances to run.
+   * @default - 1
    */
   desiredInstanceCount?: number;
   /**
    * The maximum number of Fargate instances to run.
+   * @default - 1
    */
   maxInstanceCount?: number;
   /**
    * The amount of CPU to allocate to each Fargate instance.
+   * @default - 0.5 vCPU
    */
   instanceCPU?: number;
   /**
    * The amount of memory to allocate to each Fargate instance.
+   * @default - 512MB
    */
   instanceMemory?: number;
   /**
    * Whether to enable caching of HTTP redirects.
+   * @default - false
    */
   enableRedirectCache?: string;
   /**
    * Whether to enable the S3 endpoint for the VPC.
+   * @default - false
    */
   enableS3Endpoint?: boolean;
   /**
@@ -91,6 +100,7 @@ export interface PrerenderFargateOptions {
   /**
    * Prerender Fargate Re-caching options
    * This allows to alter the re-caching behavior. The default configuration should be sufficient.
+   * @default - { maxConcurrentExecutions: 1 }
    */
   prerenderFargateRecachingOptions?: PrerenderFargateRecachingOptions;
 }