SimpleCDN

SimpleCDN is, well, a simple CDN server. Built with relatively high r/w latency in mind (think NAS mount), it provides efficiënt ways to cache files, either using the built-in in-memory cache, or the Redis extension.

Warning

While Redis support is available, it is not very stable, especially in high-load scenario's (tens of requests per second). By implementing a custom connection manager, it's brought down to a minimum but failures still happen. In such cases, SimpleCDN will load the data from disk instead of using the cache.

How to use this in an existing project?

NuGet Packages

SimpleCDN is available on NuGet:

• 
• 

How to use SimpleCDN Standalone

Using Docker

Tags:

• latest: the latest stable release, useful for quickly testing SimpleCDN.
• main: the latest build of the main branch, usually on the last commit. Not recommended for anything as it may contain bugs or break.
• X.X[.X]: pin to a specific minor or patch version. This provides higher precision and is recommended for production scenarios, especially with multi-instance environments. Supported versions can be found in the tags listing. Note that the docker tag does not have the v prefix, so Git tag v0.7.1 is Docker tag 0.7 or 0.7.1.

with docker run

docker run -p "<your_port>:8080" -v "<your_cdn_data>:/data:ro" ghcr.io/jonathanbout/simplecdn

This will pull and run the latest stable build of SimpleCDN.

with docker compose

services:
  server:
    image: ghcr.io/jonathanbout/simplecdn
    volumes:
    - <your_cdn_data>:/data:ro # :ro to make the bind mount read-only
    ports:
    - <your_port>:8080

# === use below only if you want to use redis ===
    environment:
    - Cache__Redis__ConnectionString=redis:6379
  redis:
    image: redis

Using dotnet

dotnet run

# PublishAOT is not supported with dotnet run so we need to disable it
dotnet run --property:PublishAot=false -- --CDN:DataRoot <your_cdn_data>

Variables

Generic

key	value type	default value	description
CDN:DataRoot	a local path	/data when using the Docker image, otherwise required.	The data root, where the files to be served are stored.
CDN:AllowDotFileAccess	true or false	false	Whether to allow access to dotfiles and directories.
CDN:ShowDotFiles	true or false	false	Whether to show dotfiles in generated index files. When AllowDotFileAccess is false, ShowDotFiles is ignored.
CDN:BlockRobots	true or false	true	Whether to request robots to not index CDN files. Its still up to the robots to adhere to this rule.
CDN:Footer	Any HTML	Powered by SimpleCDN (with a link to this GitHub repo)	The text to place at the bottom of generated index files.
CDN:PageTitle	Any <title> compatible string	SimpleCDN	The text to display in the browser's title bar.

Caching

key	value type	default value	description
Cache:MaxAge	A TimeSpan	One hour	How long an item may be stale (read nor written) before being removed.
Cache:MaxItemSize	A size in kB within your devices memory.	8_000	The maximum size of a file to be cached. If the size exceeds this value, the file is streamed directly from the disk.
Cache:Type	InMemory, Redis or Disabled	InMemory, or if Redis has been configured, Redis	What cache provider to use, if any.
In-Memory Options
Cache:InMemory:MaxSize	A size in kB	500_000	How big the cache may grow. When an entry is added, the oldest entries will be removed until this limit is met.
Cache:InMemory:PurgeInterval	A TimeSpan	5 minutes	How often the purge loop should wake up, to remove stale items older than Cache:MaxAge
Redis Options
Cache:Redis:ConnectionString	A redis connection string	None. Required when using Redis	How SimpleCDN should connect to your Redis instance.
Cache:Redis:ClientName	A string, without spaces	SimpleCDN	How SimpleCDN should identify itself to Redis.
Cache:Redis:KeyPrefix	A string	SimpleCDN	A string to prepend to Redis entry keys.

Overriding the defaults:

• With an environment variable, e.g. CDN__DataRoot=/mnt/data
• With an appsettings.json file, e.g.

{
  "CDN": {
    "ShowDotFiles": false
  }
}

• with a command line argument, e.g. --CDN:MaxCachedItemSize 10000

tip: see github.com/thomhurst/ReadableTimeSpan for the supported TimeSpan formats

Note

Command line arguments have precedence over appsettings.json and appsettings.json has precedence environment variables.

Development

Contributions are always welcome! Feel free to create an issue if you encounter problems. If you know a fix, a Pull Request is even better!

If you want to build a custom caching provider, take a look at the extensions/README.md file.

Building the docker image

Building a docker image can be done easily with docker build:

docker build . -f src/standalone/Dockerfile -t simplecdn:local

Be aware the build context has to be the root of the repo, whilst the dockerfile is in the src/standalone folder.

Running tests

Executing the Unit tests can be done with just a single command:

dotnet test SimpleCDN.sln

This will run the NUnit Unit Tests and the XUnit Integration Tests in the tests folder.