CDN Types

FarCry Core supports a number of different CDN types by default.

Local

Use cases:

store files in project webroot and server them with the application web server (default)
store files outside the project root and server with a web server directory alias
store files on a shared network drive
serve files from a separate domain

Configuration properties:

Property	Description
fullPath REQ	The full local path to where these files are stored. This can be any path that ColdFusion accepts, including network paths and RAM disks.
urlPath OPT	The url path to where these files are served. This should either be a domain-relative path (e.g. /cache) or a protocol relative path (e.g. //cdn.example.com/cache). If you don't specify this property, attempts to retrieve the URL for a resource will throw an error. Only privatefiles and publicfiles in core support leaving this out as FarCry will use cfcontent to stream those resources.

As an example, here is the default cache setup:

Example

<cfset application.fc.lib.cdn.setLocation(
	name="cache",
	cdn="local",
	fullpath=application.fc.lib.cdn.normalizePath(application.path.cache),
	urlpath=application.fc.lib.cdn.normalizePath(application.url.cache)
) />

S3

Use cases:

store and serve public files from S3
store and serve secured files from S3 (using temporary URLs)

Note that we've found latency to be an issue for resources that need to be served quickly (i.e. CSS, JS, images). If you want to host such files on S3 you should use something like CloudFront to improve responsiveness.

Configuration properties:

Property	Description
accessKeyId REQ
awsSecretKey REQ
bucket REQ
region REQ
domain OPT	Defaults to "s3-#region#.amazonaws.com". Use this to override the domain used in URLs.
security OPT	Defaults to "public". If you change it to "private", files will only be accessible when FarCry provides the link, and only for a limited time.
pathPrefix OPT	Use to specify a sub-directory to store files in.
urlExpiry OPT	This option is required if security="private", and specifies the number of seconds that a link should be valid for.
admins OPT	An array of S3 canonical user ids and email addresses that should be given full rights on every uploaded file. While this isn't required, we strongly recommend that you include your own account email address.
localCacheSize OPT	Number of recent files to keep on the local filesystem for fast access. Locations that have a lot of read/write access (like images) should have >5, more if many users use the system at once. Defaults to 0.
maxAge OPT	The cache header that will be included in the response header when a file is requested. This affects how long browsers will cache these assets.
sMaxAge OPT	The cache header that will be included in the response header when a file is requested. This affects how long proxies (like CloudFront) will cache these assets.

Here is an example where I have overridden the location of FarCry images. Notice that first I create a new, non-standard location that has the default details. This is useful if you want to use the built in migration tool to move local files to a CDN.

Example

<cfset application.fc.lib.cdn.setLocation(
    name="images_old",
    cdn="local",
    locationinfo=application.fc.lib.cdn.getLocation("images")
) />
<cfset application.fc.lib.cdn.setLocation(
    name="images",
    cdn="s3",
    accessKeyId="ABCDEFGHIJKLMNOPQRST",
    awsSecretKey="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCD",
    bucket="your-cdn-test",
    region="ap-southeast-2",
    security="public",
    pathPrefix="/images",
    admins=["you@example.com.au"]
) />

FTP

Use cases:

storing files on a separate FTP server
commercial CDNs like Limelight, which provide FTP access

Property	Description
server REQ	The FTP server domain or IP address.
urlPathPrefix REQ	The URL path that corresponds to the ftpPathPrefix location on the server (or the root directory if ftpPathPrefix isn't provided). Should be a protocol relative path (e.g. //cdn.example.com/cache).
ftpPathPrefix OPT	A specific folder on the FTP server to store files in.
username OPT	FTP account username.
password OPT	FTP account password.
port OPT	FTP port
proxyServer OPT	CFFTP proxyServer value.
retryCount OPT	CFFTP retryCount value. Defaults to 1.
timeout OPT	CFFTP timeout value. Defaults to 30 seconds.
fingerprint OPT	CFFTP fingerprint value.
key OPT	CFFTP key value.
secure OPT	CFFTP secure value. Defaults to false.
passive OPT	CFFTP passive value. Defaults to false.
localCacheSize OPT	Number of recent files to keep on the local filesystem for fast access. Locations that have a lot of read/write access (like images) should have >5, more if many users use the system at once. Defaults to 0.

Here is an example of overriding the public files location to put files on an FTP accessible CDN (Limelight in this case). Once again, you can see that I have copied the default location to a new non-standard config so that I can use it in the migration tool later.

Example

<cfset application.fc.lib.cdn.setLocation(
    name="publicfiles_old",
    cdn="local",
    locationinfo=application.fc.lib.cdn.getLocation("publicfiles")
) />
<cfset application.fc.lib.cdn.setLocation(
    name="publicfiles",
    cdn="ftp",
    server="example.upload.llnw.net",
    username="example-user",
    password="ABCDEFGHIJK",
    ftpPathPrefix="/content/cdn-test/publicfiles",
    urlPathPrefix="//example.xx.llnwd.net/v1/cdn-test/publicfiles",
    passive=true
) />