Getting started

Creating your first Edge Content Delivery deploment is quick and easy. This guide will walk you through the setup and configuration.

To get started, head over to Edge Services and either sign in with your existing Edge account, or sign up if you haven't done so already.

Note: If you previously managed your deployments in Console, these will now appear in Edge Services.

Creating a deployment

When you sign in to Edge Services, if you don't already have an active deployment, you will be presented with the deployment screen. Here you will see a list of plans to select from, a configuration section, a payment method section (if you've chosen a paid plan), and a summary.

Let's take a look at each section in more detail.

1. Choosing a plan

The first choice to make will be to select a plan. Edge offers a free plan consisting of 5.00 GB of data transfer and 20,000 requests per month to every user, more than enough to try out the service or run a personal site. Upgrading is quick and easy, with plans that grow as you scale your business or project.

If you contribute computing power to the network, you will gain an additional free plan for every device that you have operational on the network.

There are four premium plans available, which in addition to having increased data transfer and request limits, also benefit from a number of premium features such as variable time-to-live (TTL) and cache pre-warming.

If you require capacity in excess of what is available in the listed plans, there's also an enterprise plan where you will be assigned an account manager who will work with you to create a solution that fits the specific needs of your business.

Once you've selected a plan, scroll down to the configuration section.

2. Configure deployment

CDN is a powerful content delivery & manipulation tool and configuring it is quick and easy. There are four configuration options: hostname, image source, asset source, and the time-to-live or TTL value which determines how long your assets remain cached in the network.

Let's take a look at each.

Hostname

The hostname is the domain that your content delivery will run from (e.g. cdn.example.com). Once you've created the deployment, you will be given a CNAME DNS record to point this domain to. You will then access your content through this domain.

You can read more about this in the DNS section below.

Image source

The image source is the origin URL that the network will draw your image assets from. This should be the directory from which all your image assets can be accessed, e.g. https://example.com/images.

Asset source

The asset source is the orogin URL that the network will draw your non-image assets from, e.g. https://example.com/css.

Time-to-live (TTL)

The time-to-live or TTL value determines how long your assets will be cached for by the network before they're refreshed from your origin.

3. Payment method

If you have selected a paid plan, you will be presented with the payment method screen. Here you will need to enter your card details and a billing address. The details will be saved to your account in case you wish to use them with other deployments, (note that it is possible to use different payment methods for different deployments should the need arise).

4. DNS

Once you've created your deployment, you will be taken to the deployment listing page, where you can see your active deployment of content delivery in the Edge Network.

Click View and you will be presented with the deployment details screen. From here you can see the deployment's configuration, and can update the settings, upgrade or downgrade your plan, and make changes to the payment method.

For now, we are interested in finding the CNAME value so that we can setup the Hostname. We can see that we have been assigned cdn.gregarious-quetzal.test.network. Navigate to your domain registrar, and create a DNS record with the type CNAME. The hostname should be equal to the hostname you provided during the configuration step, e.g. cdn.example.com, and the value should be the network CNAME provided, so in this example cdn.gregarious-quetzal.test.network. We recommend you set the TTL to 3600 (60 minutes).

Once you have saved the DNS record, you will need to wait a little while for the changes to propagate. This can take anywhere from 60 seconds to 48 hours, but it is usually pretty quick. The next step is to test the deployment.

5. Testing

Now that we have created our deployment and set up the DNS, we can test that it is working. For this you will need to ensure that you have an image located at the image source, e.g. https://example.com/photos/dog.jpg. Assuming that your image source was set to https://example.com/photos/, we won't need to supply the /photos/ path, so open up your browser and navigate to https://cdn.example.com/dog.jpg.

https://cdn.example.com/dog.jpg

Edge Content Delivery is more than just a CDN, it has a powerful image manipulation pipeline built in as well. This enables you to manipulate your images using code, by passing variables to the URL string. For example, you could generate thumbnails that crop the image to a square, lower the quality, and automatically detect and centre on the subject of the photo. For example:

The URL variables for this are as follows:

https://cdn.example.com/dog.jpg?resize=entropy&width=128&height=128&quality=50

To learn more about the image manipulation pipeline, take a look at the Image manipulation of the Edge documentation..

If your images don't work right away, it is likely that your DNS is still propagating. The Edge team are always here to help, so if you are struggling, please get in touch.

Managing your deployment

Monitoring usage

The Edge Network currently provides two usage metrics for Content Delivery:: data transfer out, and the number of requests processed.

These are updated every minute and can be viewed both on the deployments listing screen and within each deployment's settings screen.

There are a lot of additional metrics available behind the scenes, and many of these will be added to your account over the coming year.

Upgrading

Upgrading a Content Delivery deployment is quick and easy, and can be done at any time.

To upgrade, go into the deployment details screen. At the bottom of the screen you will find the subscription details section. Click Change Subscription and follow the Choosing a plan and Payment method steps. Once completed, your deployment will be upgraded and ready to use immediately.

Downgrading

As with upgrading, downgrading is very straight forward.

To downgrade, go into the deployment details screen. At the bottom of the screen you will find the subscription details section. Click Change Subscription and follow the Choosing a plan and Payment method steps. Once completed, your deployment will be downgraded.

Downgrades come into effect at the end of the current billing cycle. You will see a message telling you when the downgrade will take effect and should you wish to cancel the downgrade, you will be able to do so with a single click.

Canceling

If you want to remove a deployment, you can cancel your subscription by deleting it from deployments screen. It is very important to note that this is a non-reversible action and that it will take effect immediately. You may wish to consider downgrading instead.

To discuss anything to do with your account, please feel free to contact the Edge team directly.

Image manipulation

Edge Content Delivery includes a full-featured image processing engine that allows code based image conversion and manipulation in real-time, based on a set of optional URL parameters.

Format

https://{cdn-domain}/{path}{?parameters}

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?width=600&height=400&format=png

The URL above loads a JPEG from /assets/img/example/canoe.jpg and specifies that the result should be 600x400 pixels in size and be converted to a PNG.

Parameters

blur

The blur parameter adds blur to an image, using any value above zero.

• Accepts: any number from 1-100
• Default: 0
• Alias: b

Examples

https://cdn.edge.network/assets/img/example/dog.jpg?blur=5

Original image	Blur amount = 1	Blur amount = 5
Blur amount = 10	Blur amount = 20	Blur amount = 100

filter

The filter parameter allows you to specify the interpolation method to use when resizing images. When reducing the size of an image (or downsampling), some image data is simply discarded. However when increasing image dimensions, the image is expanded and gaps must be "filled in". Each interpolation filter uses a different algorithm for determining how to fill the gaps.

• Accepts: valid values are lanczos, nearest-neighbor, linear, cubic, grid, moving-average
• Default: lanczos
• Alias: f

Example

https://cdn.edge.network/assets/img/example/dog.jpg?width=600&height=400&resize=aspectfill&filter=linear

The following filters are available:

flip

The flip parameter flips images horizontally, vertically or both. A horizontal flip can also be referred to as "mirroring".

• Accepts: valid values are x, y and xy
• Default: 0
• Alias: fl

Horizontal flip: ?flip=x	Vertical flip: ?flip=y	Horizontal and vertical flip: ?flip=xy

format

Use the format parameter to specify the required output image format.

• Accepts: valid values are jpg, png, gif, webp
• Default: output defaults to the same as the input image
• Alias: fmt

When choosing WebP as the output format, it's possible to specify another format to be used as a fallback in case the requesting client doesn't have WebP support. The fallback is added to the format parameter, separated by a comma – e.g. ?format=webp,jpg.

Original JPG Image

JPG to PNG

https://cdn.edge.network/assets/img/example/dog.jpg?format=png

GIF to JPG

https://cdn.edge.network/assets/img/example/giphy.gif?format=jpg

GIF to PNG

https://cdn.edge.network/assets/img/example/giphy.gif?format=png

Original PNG Image

PNG to JPG

https://cdn.edge.network/assets/img/example/mountain.png?w=400&resize=aspectfit&format=jpg

progressive

Add progressive=true to the image parameters to have CDN serve a progressice JPEG.

gravity

Used to position the crop area. Available options (case sensitive):

• northwest
• north
• northeast
• west
• center
• east
• southWest
• south
• southeast
• none

Original image

https://cdn.edge.network/assets/img/example/girl-on-bridge.jpg

g=west	g=center	g=east

height

The height parameter is used to specify the required height of the output image, in pixels.

• Default: original height dimension
• Alias: h

If only height is specified, the width dimension will be set to the width of the original image. If you'd like to ensure the output image retains the aspect ratio of the original image, please ensure resize=aspectfit is specified.

If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400&resize=aspectfit

h=400	h=400&resize=aspectfit

quality

The quality parameter applies compression to an image, reducing it's file size.

• Accepts: any number from 1-100
• Default: 75
• Alias: q

The best results for quality and file size can be found around 40-60, where we've found generated images to be visually indistinguishable from the source image.

Examples

The original image and all quality variations below are 2048 × 1024 pixels.

Original image, 4.7MB

https://cdn.edge.network/assets/img/example/vegetables.jpg

Quality = 100, 1.3MB	Quality = 75, 180kB
Quality = 50, 119kB	Quality = 25, 82kB

ratio

Use the ratio parameter in combination with width (w) or height (h) to crop the image to the specified aspect ratio. Resize styles are respected.

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400&ratio=16-9

rotate

The rotate parameter rotates the image according to the value specified in degrees. The image will be zoomed so that it covers the entire area after rotation.

• Accepts: any number from 0-359
• Default: 0

saturate

The saturate parameter increases or reduces an image's colour saturation and can be used to convert it to black and white.

• Accepts: 0 or 1
• Default: none
• Alias: sat

To desaturate (convert to black and white), use 0 or any number below 0.

https://cdn.edge.network/assets/img/example/beach.jpg?saturate=0

Saturate amount = 0 (B&W)	Saturate amount = 1

sharpen

The sharpen parameter adds sharpness to an image.

• Accepts: 0-5
• Default: 0
• Alias: sh

Example

https://cdn.edge.network/assets/img/example/beach.jpg?sharpen=1

Default amount = 0	Sharpen amount = 1	Sharpen amount = 5

width

The width parameter is used to specify the required width of the output image, in pixels.

• Default: original width dimension
• Alias: w

If only width is specified, the height dimension will be set to the height of the original image. If you'd like to ensure the output image retains the aspect ratio of the original image, please ensure resize=aspectfit is specified.

If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?w=400&resize=aspectfit

w=400	w=400&resize=aspectfit

Resizing

Images can be easily resized using DADI CDN. Use the resize parameter with width and height to resize images, or specify crop along with crop coordinates for full control over the portion of the original image that is retained.

There are several ways to resize an image, the simplest of which is to specify the dimensions of the output images. Use width and height parameters to specify the final dimensions of the output image.

Using the width parameter

The width parameter (alias: w) specifies the width of the required output image in pixels. If only width is specified, the height dimension will be calculated automatically so that the original aspect ratio of the image is maintained given the new width. If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?w=400

Using the height parameter

The height parameter (alias: h) specifies the height of the required output image in pixels. If only height is specified, the width dimension will be calculated automatically so that the original aspect ratio of the image is maintained given the new height. If both width and height are omitted, the original image’s dimensions are used.

Example

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400

Specifying aspect ratio

Images can be resized to a specified aspect ratio by providing a width or height in combination with the ratio parameter. CDN will respect any resizeStyle specified.

https://cdn.edge.network/assets/img/example/canoe.jpg?h=400&ratio=16-9

Specifying a resize style

The resizeStyle (alias: resize) parameter allows you to specify how CDN should fit your image into the specified dimensions.

aspectfill

Keeps the aspect ratio of the original image and generates an output image of the specified width and height. The output image may be cropped, however by specifying the gravity parameter you can tell CDN which part of the image should be retained.

The output image is 400 x 300 pixels.

aspectfit

Keeps the aspect ratio of the original image and generates an output image with the maximum dimensions that fit inside the specified width and height.

The output image is 400 x 267 pixels.

crop

When crop is used as the resize style then an additional parameter must be used to specify the coordinates of the crop rectangle. There are two ways to pass the crop rectangle coordinates:

• Specify only the top left corner of the rectangle

  ?resizeStyle=crop&crop=10,15

• Specify the top left and the bottom right corners of the rectangle

  ?resizeStyle=crop&crop=10,15,200,300

entropy

Used in combination with width and height parameters, entropy crops the image using a technique that determines the most important areas. Areas of higher contrast are considered more important, and images are often cropped to remove large areas of static colour.

https://cdn.edge.network/assets/img/example/girl-on-bridge.jpg?w=250&h=300&resize=entropy

Original image	Entropy crop

fill

Generates an output image with the exact specified width and height dimensions, ignoring the aspect ratio of the original image. The output image may appear squashed or stretched.

The output image is 400 x 300 pixels.

gravity

Used to position the crop area. See Parameters / gravity for details and examples.

Cropping

For more control over the output image than available when using the standard resize style options aspectFit, aspectFill, fit and fill, you can specify three different ways to crop an image.

Top-left crop

By specifying only the top left corner of the crop rectangle, CDN works out the full crop rectangle size by using the specified width and height parameters. To obtain an image that is 300 wide and 400 high, but cropped from 100 pixels from the top edge:

https://cdn.edge.network/assets/img/example/girl-on-bridge.jpg?resize=crop&crop=0,10&width=300&height=400

Crop rectangle

It is also possible to supply both the top left and the bottom right coordinates of a crop rectangle (e.g. resize=crop&crop=0,0,100,100). This allows you to selectively crop an exact area out of an image.

Let's take a look at some examples. We'll use our 400x400 pixel image, which has squares marked at x, y (size): 0,0 (25 px), 25,25 (25px), 50,50 (50px), 100,100 (100px), 200,200 (200px):

We can crop the second and third boxes by supplying a top left of 50,50, and a bottom right of 200,200, giving us a 150x150 pixel image:

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200

We're also able to change the size of the image we get back. Let's change it to 100 pixels wide. In this case, the height will be inferred from the width. The same goes if we only supply a height.

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200&width=100

If you really want to get creative, you can supply a cropping rectangle along with both a width and height, which will allow you to completely resize an image after cropping. Let's take the above image and squash it.

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200&width=400&height=100

Another way of resizing our crops, if we don't want to be as specific, is to provide the devicePixelRatio ratio.

https://cdn.edge.network/assets/img/example/measure1.png?resize=crop&crop=50,50,200,200&devicePixelRatio=2

Read more about dealing with pixel ratios.

Entropy crop

Using resize=entropy crops the image using a technique that determines the most important areas.

Read more about entropy.

Example use case

For this example, we're going to imagine you have a magazine-style website with a list of articles on the homepage and an article page. We'll start with the following image, which your editor wants to use as the main article image.

Original image, 5616 × 3744 px, 4MB

https://cdn.edge.network/assets/img/example/beach.jpg

This is a large image, and it's not going to fit easily into the two spaces we have available for it. Unfortunately, no one in the department knows how to use Adobe Photoshop to make appropriately sized images. Fortunately, CDN can handle this task for you.

Resizing and cropping

On the article page, let’s assume your main image spot is a 500×300 pixel container. It's an odd size, but illustrates this concept well. To fit the base image into that container, we’ll need to change the dimensions and crop some data from the top and bottom.

To adjust the image we need to specify the new width and height, as well as tell CDN how we want to crop the image.

https://cdn.edge.network/assets/img/example/beach.jpg?w=500&h=300&resize=entropy

• width=500&height=300: Sets the width and height to fit the container.

• resize=entropy: Tells CDN how to determine the crop area. Entropy is a smart cropping feature that adjusts the crop area to ensure the important part of your image is retained. It uses areas of high contrast to set the crop area.

Resized image, 500 × 300 px, 98kB

Now, on the homepage, let’s assume each feature article has an image container that is 200×200 pixels. With the main subject of the image so close to the right, we'll once again need to tell CDN how we want the image cropped.

https://cdn.edge.network/assets/img/example/beach.jpg?w=200&h=200&resize=entropy

Resized image, 200 × 200 px, 29kB

If we don't specify entropy as the resize parameter, CDN defaults to using aspectfit and our image would look a little different, with the main subject almost excluded from the image.

https://cdn.edge.network/assets/img/example/beach.jpg?w=200&h=200

Caching

The network cache consists of two types of caching: the Lightening cache which holds assets in-memory for 60 seconds; and a disk cache which persists assets in line with the configured cache TTL. Lightening cache is designed to respond as fast as possible for frequently requested assets, whilst disk cache makes it possible to persist files for far longer without degrading performance or consuming memory on the device.

You can determine the cache response by looking at the X-Cache-Type HTTP header, which will be mem if the asset is cached in-memory, and disk otherwise.

Upon expiration, cached files will be removed from the network cache, and will be re-cached the next time they are accessed, unless they are pre-warmed (see below).

Cache invalidation

Files can be removed from the cache by the use of the invalidate parameter.

https://cdn.edge.network/assets/img/example/beach.jpg?invalidate=true

After removing the file, please allow up to 1 minute for the cached version to be removed from the network cache. This currently only removes the file in the region where this is requested, but this will change in future releases.

Cache pre-warming

Assets that are accessed above a user specified threshold will be automatically re-cached to maintain a quick response when the asset expires. In addition to pre-warming the asset, the cache can be configured to persist an expired asset during the process of pre-warming, ensuring a reliable response for assets with a longer load time.

You can determine whether the cache response is pre-warmed by looking at the X-cache-origin HTTP header, which will be pre-warm if pre-warmed, and request if not pre-warmed.

Cache pre-warming is currently an experimental option, so please reach out to us if you would like to enable it on your account.