https://github.com/jonathanbout/simplecdn
A CDN server for serving your static files somewhat efficiently
https://github.com/jonathanbout/simplecdn
cdn index-generator static-file-server
Last synced: about 2 months ago
JSON representation
A CDN server for serving your static files somewhat efficiently
- Host: GitHub
- URL: https://github.com/jonathanbout/simplecdn
- Owner: JonathanBout
- License: mit
- Created: 2024-11-23T21:41:37.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-06T15:09:45.000Z (3 months ago)
- Last Synced: 2026-04-06T15:42:25.422Z (3 months ago)
- Topics: cdn, index-generator, static-file-server
- Language: C#
- Homepage: https://www.nuget.org/packages/SimpleCDN
- Size: 762 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# SimpleCDN
SimpleCDN is, well, a simple CDN server. Built with relatively high r/w latency in mind (think NAS mount), it provides efficient ways to cache files, either using the built-in in-memory cache, or the Redis extension.
## How to use this in an existing project?
### NuGet Packages
SimpleCDN is available on NuGet:
- [](https://NuGet.org/packages/SimpleCDN)
- [](https://nuget.org/packages/SimpleCDN.Extensions.Redis)
## 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](https://github.com/JonathanBout/SimpleCDN/tags). 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 ":8080" -v ":/data:ro" ghcr.io/jonathanbout/simplecdn
```
This will pull and run the latest stable build of SimpleCDN.
#### with `docker compose`
```yml
services:
server:
image: ghcr.io/jonathanbout/simplecdn
volumes:
- :/data:ro # :ro to make the bind mount read-only
ports:
- :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
```
### 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 `` compatible string | `SimpleCDN` | The text to display in the browser's title bar. |
| `CDN:GenerateIndexJson` | `true` or `false` | `false` | Whether to generate `index.json` files, just like `index.html` files but easier to read for machines. |
#### 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. |
| **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.
```json
{
"CDN": {
"ShowDotFiles": false
}
}
```
- with a command line argument, e.g. `--CDN:MaxCachedItemSize 10000`
_tip: see [github.com/thomhurst/ReadableTimeSpan](https://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](https://github.com/jonathanbout/simplecdn/tree/main/extensions/README.md).
### 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.