You need to set up a delivery configuration, or "property" to determine how your site or app will be delivered to requesting clients. We'll use ​a few operations in the Property Manager API (PAPI) to do this.

Before you begin

When you set up access, you worked with your ​Akamai​ account team to set everything up. You need the unique alphanumeric value assigned to your contract and primary group, prefaced by their PAPI prefixes — ctr_<value> and grp_<value>, respectively. If you don't have these values, you can use the Property Manager API (PAPI) to get them.

You'll also need the IPv4 address that was assigned to your ​Akamai​ Connected Cloud Services (ACCS) NodeBalancer. If you don't have it, you can run this operation:

📘

Which Ion version do you have?

You can have one of two versions of Ion on your contract. API operations use the codename values that ​​Akamai​ established for these versions during development:

• Ion Premier. SPM
• Ion Standard. FRESCA

Make note of the codename for your version, because you'll need this later, too.

1. Create an edge hostname

Here, we'll create the hostname that's used to redirect requests for your site or app to ​Akamai​ edge servers.

What's an edge hostname?

You provide us with a domain that your customers use to access your site or app and ​Akamai​ appends a specific domain to it. Here's an example:

You'll also apply the certificate you created to secure it. Later, you'll need to update your existing DNS record for your site or app to be a CNAME record that points to the edge hostname. As a result, a client request to your domain is rerouted to the edge hostname and securely sent to an optimal ​Akamai​ edge server, where your delivery configuration (property) is read. You'll set up this property later to determine how to best deliver your site or app to a client.

Get your domains

When you created your enrollment, you provided a domain to serve as your common name (cn). You'll need this exact value. If you added any other domains to your enrollment as subject alternative names (sans), you'll need them, too. If you don't have these values, you can use the list enrollments operation to get them.

👍

Wait for your certificate to finish

If your edge certificate hasn't gone through all of the phases for completion, you should wait until it does. The person you set as your certificate administrator will get a confirmation email when it's ready to go.

Create your edge hostname

To create the edge hostname, you can use a single operation in PAPI.

Check hostname status (optional)

The email address for your primary admin user will receive a confirmation message when your edge hostname is ready. But, you can also run an operation in PAPI to check its status.

2. Create your Ion property

To set up your delivery using Ion, you need to create an Ion property.

3. Add your edge hostnames

The edge hostnames you created for your site need to be added to your Ion property. If you didn't store their unique ID values, you can run the List edge hostnames operation to get them.

With the IDs stored, add your edge hostnames.

4. Get the rule tree

Get the baseline of your Ion property's rule tree. It includes all of the default rules and behaviors that ​​​Akamai​ adds.

5. Edit the rule tree

Your new rule tree includes several rules and behaviors by default. A lot of them are preset to help optimize the delivery of your site. There are a few that require additional settings. There are others you should ensure are enabled.

👍

Use the PAPI extension

​Akamai​ offers extensions for code editors that help simplify editing and validating your rule tree. Check out the tutorial here in this document.

Define your origin hostname

You need to establish a unique name for your origin server. Your Ion property will use it to contact your Linodes to get your site and cache it on the ​Akamai​​ edge network.

Use a random string for this value—for example, 1hkeh1g76—to conceal your origin server. Then, append it with your domain to create your origin server hostname:

1hkeh1g76.docassociates.com

You can only use alphanumeric characters in an origin server hostname.

Set your origin

Configure the origin behavior in the defaultRule to use your Linode as your origin servers. Look for the origin behavior in your rule tree and set the values as follows:

{
    "name": "origin",
    "options": {
        "originType": "CUSTOMER",
        "hostname": "1hkeh1g76.docsassociates.com",
        "forwardHostHeader": "REQUEST_HOST_HEADER",
        "cacheKeyHostname": "REQUEST_HOST_HEADER",
        "compress": true,
        "enableTrueClientIp": true,
        "trueClientIpHeader": "True-Client_IP",
        "httpPort": 80,
        "httpsPort": 443,
        "originSni": true,
        "ipVersion": "IPV4",
        "verificationMode": "CUSTOM",
        "originCertsToHonor": "CUSTOM_CERTIFICATES",
        "customValidCnValues": [
            "{{Origin Hostname}}",
            "{{Forward Host Header}}"
        ],
        "customCertificates": [
            {
                "sha1Fingerprint": "<SHA-1 fingerprint of fullchain.pem>", 
                "pemEncodedCert": "-----BEGIN CERTIFICATE-----\n<contents of fullchain.pem>\n-----END CERTIFICATE-----"
            }
        ]
    }
}

Apply your Ion cpCode

You should have had at least one content provider (CP) code set up when you originally worked with your account team. You need to add it to your Ion property to track the delivery of your website or app through the ​​Akamai​ edge network.

You can find it as a behavior in the Traffic Reporting child rule in your rule tree.

{
    "name": "cpCode",
    "options": {
        "value": {
            "id": 678901,
             "name": "docsassociates.com",
            "description": "The CP code for the Ion property for docsassociates.com",
            "products": [
                "SPM"
             ]
         }
     }
 }

Enable mPulse

mPulse is a real user monitoring (RUM) solution that collects and analyzes detailed information about your users' experience whenever they visit your site or app. It's used with other Ion features to help accelerate delivery. So, we want to make sure it's enabled. mPulse RUM is a sub-rule of the Augment insights child rule. Make sure it's set as follows:

{
    "name": "mPulse RUM",
    "children": [],
    "behaviors": [
        {
            "name": "mPulse",
            "options": {
                "apiKey": "",
                "bufferSize": "",
                "configOverride": "",
                "enabled": true,
                "loaderVersion": "V12",
                "requirePci": false,
                "titleOptional": ""
            }
        }
    ],
    "criteria": [],
    "criteriaMustSatisfy": "all",
    "comments": "Collect..."
},

We're just looking to enable mPulse for now. Leave all of the empty values as they are. You can always create a new version of your rule tree later, and customize the mPulse settings.

Enable adaptiveAcceleration

Adaptive Acceleration improves HTML page load performance by prepositioning content. It uses ​​Akamai​'s learning engine that's powered by real user data gathered via mPulse. It provides site acceleration and can incrementally improve the rendering process by up to 5%. Adaptive acceleration is a sub-rule of the Accelerate delivery child rule. Make sure it's set as follows:

{
    "name": "Adaptive acceleration",
    "children": [],
    "behaviors": [
        {
            "name": "adaptiveAcceleration",
            "options": {
                "enableBrotliCompression": false,
                "enablePreconnect": true,
                "enablePush": true,
                "enableRo": false,
                "preloadEnable": true,
                "source": "mPulse",
                "titleHttp2ServerPush": "",
                "titlePreconnect": "",
                "titlePreload": "",
                "titleRo": "",
                "compression": "",
                "titleBrotli": "",
                "enableForNoncacheable": false
            }
        }
    ],
    "criteria": [],
    "criteriaMustSatisfy": "all",
    "comments": "Automatically..."
}

Similar to mPulse we're just looking to enable Adaptive Acceleration in your Ion property. You can always create a new version of your rule tree later and customize the adaptiveAcceleration settings.

Enable caching

Caching your website content on edge servers makes it closer to end users to help speed up delivery. You should add some form of caching to your Ion property.

1. In the Offload origin child rule, scroll past all of the children entries until you see the root behaviors array.

2. In the caching object, set its options:

   • behavior. Set this to "MAX_AGE" which enables caching for your site.
   • mustRevalidate. Set to false, stale content will be served to a request if it can't be validated on your Linodes. (This way, a 404 error isn't returned because the requested content can't be found.)
   • ttl. This is the number of seconds content should be kept in cache before checking to see if newer content is available on your origin. Set this to 600s (10 minutes). This gives your Linodes enough time to index and access your content if it's changed.

{
    "name": "caching",
    "options": {
        "behavior": "MAX_AGE",
        "mustRevalidate": false,
        "ttl": "600s"
    }
},

3. Scroll down to the cacheError object and set it's options:

   • enabled. Set this to true.
   • ttl. This is the number of seconds HTTP Error Responses should be kept in the cache. Set this to 30s to give your Linodes enough time to address and log errors.
   • preserveStale. Set to true, stale HTTP Error Responses will be served to a request if it can't be validated on your Linode.

{
    "name": "cacheError",
    "options": {
        "enabled": true,
        "ttl": "30s",
        "preserveStale": true
    }
},

4. Find the HTML pages child rule and configure the caching behavior entry to match other caching settings you've applied for the root caching behavior:
   • behavior. Set to MAX_AGE.
   • mustRevalidate. Set to false.
   • ttl. Set to 600s (10 minutes).

"name": "HTML pages",
    "children": [],
    "behaviors": [
        {
            "name": "caching",
            "options": {
                "behavior": "MAX_AGE",
                "mustRevalidate": false,
                "ttl": "600s"
            }
        },

Add autoDomainValidation (recommended)

Earlier, you set up a domain-validated certificate to protect the connection between a requesting client and the ​Akamai​ edge network via HTTPS. This certificate has a lifecycle of 90 days. After which, you need to renew it. You can add autoDomainValidation to your rule tree to automate this renewal.

1. Find the behaviors array in your rule tree that also includes the origin behavior.

2. Add the autoDomainValidation object below the origin object (adding a comma to the end of that object) to include this behavior in the Default Rule.

"behaviors": [
    {
        "name": "origin",
        "options": {
            "originType": "CUSTOMER",
            "hostname": "1hkeh1g76.docsassociates.com",
            "forwardHostHeader": "REQUEST_HOST_HEADER",
            "cacheKeyHostname": "REQUEST_HOST_HEADER",
            "compress": true,
            "enableTrueClientIp": true,
            "trueClientIpHeader": "True-Client_IP",
            "httpPort": 80,
            "httpsPort": 443,
            "originSni": true,
            "ipVersion": "IPV4",
            "verificationMode": "CUSTOM",
            "originCertsToHonor": "CUSTOM_CERTIFICATES",
            "customValidCnValues": [
                "{{Origin Hostname}}",
                "{{Forward Host Header}}"
            ],
            "customCertificates": [
                {
                    "sha1Fingerprint": "<SHA-1 fingerprint of fullchain.pem>", 
                    "pemEncodedCert": "-----BEGIN CERTIFICATE-----\n<contents of fullchain.pem>\n-----END CERTIFICATE-----"
                }
            ]
        }
    },
    {
        "name": "autoDomainValidation",
        "options": {
            "autodv": ""
        }
    }
],

📘

You don't need to set any options. Just include this object to enable this feature.

Set this way, the behavior applies to all of the edge hostnames you've set in your Ion property that use an Enhanced TLS, domain-validated certificate. Auto-renewal of your certificate will start 16 days before its 90-day lifecycle.

What about the rest of the rule tree?

Leave everything else in the tree at its default. A new Ion property includes several rules and behaviors that are preset as a best practice, and others are optional. You don't need to change any of them now. You can always create a new version of your property later and make changes.

6. Validate rule tree changes

Make sure your JSON file is correct and complete. You need to resolve returned errors, because they can prevent you from activating your Ion property.

If you've set up your property as we've covered here, you shouldn't run into any blocking errors.

👍

Use a PAPI extension for validation

You can also use one of our supported extensions to validate your rule tree.

7. Update the rule tree

Push your updated JSON rule tree to your Ion property.