## CDN

- [Overview](#overview)
- [Requirements](#requirements)
- [Your First CDN Project](#your-first-cdn-project)
- [Directory Sharding](#directory-sharding)
- [Links](#links)

## Overview

## Requirements

- **[Node.js](https://www.nodejs.org/)** (supported versions: 6.9.2, 6.11.1, 8.9.4)

## Your first CDN project

### Install dependencies

### Install CDN

```bash
$ 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:

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

### Start the server

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

```bash
$ 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:

```bash
$ 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](https://docs.dadi.cloud/cdn/#amazon-s3), [a remote server](https://docs.dadi.cloud/cdn/#remote-server), and the [the local filesystem](https://docs.dadi.cloud/cdn/#local-filesystem). We'll start using the local filesystem, but see the [full documentation](https://docs.dadi.cloud/cdn/#defining-sources) 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

```json
{
  "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

```bash
$ 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](https://docs.dadi.cloud/cdn)

## 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):
   ```bash
   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.