CDN

• Overview
• Requirements
• Your First CDN Project
• Directory Sharding
• Links

Overview

Requirements

• Node.js (supported versions: 6.9.2, 6.11.1, 8.9.4)

Your first CDN project

Install dependencies

Install CDN

$ cd my-app
$ npm install @caruuto/cdn

Add an entry point

You'll need an entry point for your project. We'll create a file called index.js and later we will start the application with node index.js. Add the following to the new file:

/**
 *  index.js
 */
const app = require('@caruuto/cdn')

Start the server

CDN can be started from the command line simply by issuing the following command:

$ node index.js

With the default configuration, our CDN server is available at http://localhost:8001. Visiting this URL will display a welcome message.

Configuration

CDN requires a configuration file specific to the application environment. For example in the production environment it will look for a file named config.production.json.

When CDN was installed, a development configuration file was created for you in a config folder at your application root.

Run CDN as a service

To run your CDN application in the background as a service, install Forever and Forever Service:

$ npm install forever forever-service -g

$ forever-service install -s index.js -e NODE_ENV=production cdn --start

Note: the environment variable NODE_ENV=production must be set to the required configuration version matching the configuration files available in the config directory.

Configuring an image source

Before you can serve assets or images you need to tell CDN where your files are located. Currently, CDN can serve your files from three types of source: Amazon S3, a remote server, and the the local filesystem. We'll start using the local filesystem, but see the full documentation for details on using the other source types.

The sample configuration file defines a local filesystem source. The path property is set to use an directory called images at the root of your application. CDN will look for your files at the location defined in this path property every time it handles a request.

Example

{
  "server": {
    "host": "127.0.0.1",
    "port": 8001
  },
  "images": {
    "directory": {
      "enabled": true,
      "path": "./images"
    }
  }
}

We'll use the above configuration for an example. With image files in the images directory we can make a request for one to view it in the browser:

Images available

$ my-app/images  ls -la
total 9464
drwxr-xr-x  4 root  wheel      136 13 Mar 13:02 .
drwxr-xr-x  4 root  wheel      136 13 Mar 13:01 ..
-rw-r--r--  1 root  wheel     9396 13 Mar 13:02 92875.jpg
-rw-r--r--  1 root  wheel  4832710 13 Mar 13:02 92876.jpg

Browser request

http://127.0.0.1:8001/92875.jpg

Links

• CDN Documentation

Directory Sharding

CDN uses 4-character subdirectory sharding (directoryChunkSize: 4) for all filesystem cache entries. This prevents performance degradation from large flat cache directories by distributing files across a nested hierarchy. For example, a cache key 1073ab6c… is stored at ./cache/1073/ab6c/….

Deployment Runbook: Enabling Directory Sharding

When deploying a version that enables directoryChunkSize: 4 for the first time, the existing flat-directory cache must be flushed before restarting the service. Existing cache entries stored in the old flat layout will not be found after this change (due to path mismatch), so leaving them in place wastes disk space.

Required steps:

1. Stop the CDN service.
2. Delete the existing cache directory (or call the cache flush API endpoint):

   rm -rf ./cache

3. Deploy the new code (which includes directoryChunkSize: 4 in the config).
4. Start the CDN service. The cache directory will be recreated automatically and new entries will use the sharded path layout.