• Document Up to Date
  • Updated On 4.0.0

Setup a Serverless Site

Warning

This document has been deprecated and is provided as a reference only. Please see :ref:` newIa-setup-serverless-delivery` for the updated version.

CrafterCMS can be configured to serve sites directly from AWS services, following this guide you will:

  • Configure the Crafter Deployer of an authoring environment to upload files to AWS S3 and index to AWS Elasticsearch.
  • Configure the Crafter Engine of a delivery environment to read files from AWS S3 and query to AWS Elasticsearch.

Prerequisites

  • An AWS account
  • A CrafterCMS authoring environment
  • A CrafterCMS delivery environment

Step 1: Create the site in the authoring environment

Note

You can skip this step if you already have an existing site.

  1. Start the authoring environment: AUTHORING_INSTALL_DIR/bin/startup.sh
  2. Login to Crafter Studio at http://localhost:8080/studio
  3. Click the Create Site button
  4. Choose the Editorial blueprint, enter the Site Id (e.g. editorial), and then review and create.

Step 2: Create the AWS resources

Important

You might need to wait several minutes before the CloudFront distribution and the Elasticsearch domain are available to continue with the next steps.

Important

If you already have a serverless site set up, and are in the process of setting up another one, you can reuse the S3 Bucket and Elasticsearch. You will need to create a new CloudFront distribution though, since each site needs its own distribution.

Login to the AWS Management Console to create the following resources:

S3 Bucket

  1. In the top navigation bar click the Services dropdown menu, and search for S3.

  2. Click on Create bucket.

  3. Enter the Bucket name (for example, craftercms-sites), choose the region, leave the defaults on the next 2 steps and finally click on Create.

    Serverless Site - Create S3 Bucket

  4. After the bucket is created, select the bucket, go to Permissions and in the CORS Configuration enter the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
      <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedMethod>HEAD</AllowedMethod>
        <MaxAgeSeconds>3000</MaxAgeSeconds>
        <AllowedHeader>*</AllowedHeader>
      </CORSRule>
    </CORSConfiguration>
    

    Important

    For production and to tighten up security, we recommend you specify a fixed origin in AllowedOrigin.

Elasticsearch

  1. In the top navigation bar click the Services dropdown menu, and search for Elasticsearch Service.

  2. Click on Create a new domain.

  3. Select a Deployment Type and on the Elasticsearch version, pick the latest 6.x (currently it’s 6.5).

    Serverless Site - Elasticsearch Deployment Type

  4. On the next screen, enter the domain name. Leave the defaults on the rest of the settings or change as needed, and then click on Next.

  5. On Network Configuration, we recommend you pick the VPC where your authoring and delivery nodes reside. If they’re not running on an Amazon VPC, then pick Public Access.

    Serverless Site - Elasticsearch Network Access

  6. Select the Access Policy that fits your Crafter environment, and click on Next.

    Serverless Site - Elasticsearch Access Policy

  7. Review the settings and click on Confirm.

  8. Wait for a few minutes until the domain is ready. Copy the Endpoint. You’ll need this URL later to configure the Deployer and Delivery Engine which will need access to the Elasticsearch.

    Serverless Site - Elasticsearch Endpoint

CloudFront Distribution

  1. In the top navigation bar click the Services dropdown menu, and search for CloudFront.

  2. Click on Create Distribution.

  3. In Select a delivery method for your content, click on Get Started under Web.

    Serverless Site - CloudFront Delivery Method

  4. In the Origin Settings section do the following:

    1. In Origin Domain Name, select the S3 bucket domain.
    2. In Origin Path, enter the site base path (e.g. /editorial)
    3. Select Yes in Restrict Bucket Access.
    4. Select Create a New Identity in Origin Access Identity.
    5. Select Yes, Update Bucket Policy in Grant Read Permissions on Bucket.
    Serverless Site - CloudFront Origin Settings

    1. Under the Default Cache Behavior Settings section, in Cache Based on Selected Request Headers, select Whitelist and add the following headers: Access-Control-Request-Headers, Access-Control-Request-Method and Origin.
    Serverless Site - CloudFront Whitelist Headers

  5. Leave or change the rest of the settings as you see fit, and finally click on Create Distribution.

  6. On the left sidebar, click on Distributions. You should see the distribution been created (In Progress status). Take note of the distribution ID and Domain Name for the next steps.

    Serverless Site - CloudFront ID and Domain Name

Step 3: Configure the Delivery Crafter Engine for Serverless Mode

  1. Edit the services override file to enable the Serverless S3 mode (DELIVERY_INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/engine/extension/services-context.xml):

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
      <import resource="classpath*:crafter/engine/mode/multi-tenant/simple/services-context.xml" />
      <!-- S3 Serverless Mode -->
      <import resource="classpath*:crafter/engine/mode/serverless/s3/services-context.xml" />
    </beans>
    

  2. Edit the properties override file to point the content store to the AWS services (DELIVERY_INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties). The properties you need to update are the following:

    • crafter.engine.site.default.rootFolder.path
    • crafter.engine.s3.region
    • crafter.engine.s3.accessKey
    • crafter.engine.s3.secretKey

    An example of how the server-config.properties would look with these properties configured (values in * are not displayed since they’re sensitive):

    DELIVERY_INSTALL_DIR/bin/apache-tomcat/shared/classes/crafter/engine/extension/server-config.properties
    # Content root folder when using S3 store. Format is s3://<BUCKET_NAME>/<SITES_ROOT>/{siteName}
    crafter.engine.site.default.rootFolder.path=s3://craftercms-sites/{siteName}
    # The URL of Crafter Search
    crafter.engine.search.server.url=${SEARCH_URL}
    # The URL of Crafter Profile
    crafter.profile.rest.client.url.base=${PROFILE_URL}
    # If the Security Provider is enabled
    crafter.security.enabled=true
    # The Elasticsearch hosts to use
    crafter.engine.elasticsearch.urls=${ES_URL}
    
    # S3 Serverless properties
    # S3 region
    crafter.engine.s3.region=us-east-1
    # AWS access key
    crafter.engine.s3.accessKey=**********
    # AWS secret key
    crafter.engine.s3.secretKey=********************
    

    You can also provide the AWS region, access key and secret key without having to edit the config file properties. Please see Set up AWS Credentials and Region for Development.

  3. Edit the ES_URL in DELIVERY_INSTALL_DIR/bin/crafter-setenv.sh to point to the Elasticsearch endpoint:

    export ES_URL=https://search-craftercms-sites-kvbatu2vr4nioxpwmktlpvq3jm.us-east-1.es.amazonaws.com
    

Step 4: Create the AWS Target in Authoring Crafter Deployer

The Deployer target you’re about to create will allow the authoring Deployer to push the content to the S3 bucket and index the files in the AWS Elasticsearch any time you do a publish in the site.

  1. Copy the following content in a file in the authoring node/server. Please also edit the values in <>.

    {
       "env": "aws",
       "site_name": "<SITE_NAME>",
       "template_name": "aws-s3",
       "local_repo_path": "${env:CRAFTER_DATA_DIR}/repos/aws/<SITE_NAME>",
       "elastic_search_url": "<ELASTICSEARCH_URL>",
       "repo_url": "${env:CRAFTER_DATA_DIR}/repos/sites/<SITE_NAME>/published",
       "aws": {
         "region": "<AWS_REGION>",
         "access_key": "<AWS_ACCESS_KEY>",
         "secret_key": "<AWS_SECRET_KEY",
         "s3": {
           "url": "s3://<BUCKET_NAME>/<SITES_ROOT>/{siteName}"
         },
         "distribution": {
           "url": "http://<CLOUDFRONT_DISTRIBUTION_DOMAIN_NAME>",
           "ids": [ "<CLOUDFRONT_DISTRIBUTION_ID>" ]
         }
       },
       "delay": 10
    }
    

  2. Call the Deployer create target API with the file you created in the previous step as the request body. You can do do this in curl with the following command (replace <> for the actual filename):

    curl --request POST --url http://localhost:9191/api/1/target/create --header 'content-type: application/json' --data '@<CREATE_TARGET_REQUEST_BODY_FILE>'
    

  3. If you tail the Deployer log file (AUTHORING_INSTALL_DIR/logs/deployer/crafter-deployer.out), after a minute, you should see indications that the site was uploaded to S3 and the files were indexed.

Step 4: Test the Delivery Site

  1. Start the delivery environment: DELIVERY_INSTALL_DIR/bin/startup.sh

  2. Open a browser and go to http://localhost:9080?crafterSite=editorial.

    Serverless Site - Editorial Screenshot
  3. Verify that the static-assets are being served from the CloudFront distribution (in Chrome, you can do this by

    right-clicking an image and then clicking on Inspect).

    Serverless Site - Static Asset Inspect