computer-playbook/roles/web-svc-cdn/README.md

# Content Delivery Network

## Description

[Nginx](https://nginx.org/) is a high-performance web server and reverse proxy.
This role wraps Nginx as an internal Content Delivery Network that serves static assets such as CSS and JavaScript bundles for other web applications in the stack.

## Overview

This role deploys an Nginx-based CDN container behind the project's standard reverse proxy and exposes the canonical `cdn` service so that other roles can consume it through `services.cdn`.
It also publishes the `css` and `javascript` aliases as canonical references back to `cdn` so dependent applications can opt into either alias without duplicating configuration.

## Cosmos

The diagram places Content Delivery Network in the Infinito.Nexus cosmos: the components it deploys (capabilities), the central services it consumes (dependencies), and its outward reach (federation and bridged external networks).

```mermaid
flowchart LR
    subgraph deps [Dependencies]
        dep_svc_net_tor["svc-net-tor 🐳🐝"]
        dep_web_app_matomo["web-app-matomo 🐳🐝"]
        dep_web_app_prometheus["web-app-prometheus 🐳🐝"]
    end
    subgraph role [web-svc-cdn 🐳🐝]
        svc_dashboard["dashboard"]
        svc_cdn["cdn"]
        svc_build["build"]
        svc_matomo["matomo"]
        svc_javascript["javascript"]
        svc_prometheus["prometheus"]
        svc_tor["tor"]
    end
    subgraph dependents [Dependents]
        dpt_web_app_dashboard["web-app-dashboard 🐳🐝"]
        dpt_web_svc_css["web-svc-css 💻"]
    end
    dep_svc_net_tor -. "0..1" .-> svc_tor
    dep_web_app_matomo -. "0..1" .-> svc_matomo
    dep_web_app_prometheus -. "0..1" .-> svc_prometheus
    svc_dashboard -- "1:1" --> dpt_web_app_dashboard
    svc_dashboard -- "1:1" --> dpt_web_svc_css
```

Solid `1:1` edges are fixed relationships; dashed `0..1` edges are conditional (enabled only in matching deployments); red `0..0` edges are turned off in this role. Node markers show the role's deploy modes (💻 host, 🐳 compose, 🐝 swarm); ❌ marks a service that is explicitly turned off, and ⚙️ an Ansible role dependency declared in `meta/main.yml`.

## Features

- **Canonical CDN service:** Provides the primary `cdn` service entry consumed via `services.cdn` across the stack.
- **Aliased asset channels:** Exposes `css` and `javascript` as canonical aliases of `cdn` for clearer per-asset wiring.
- **TLS-aware delivery:** Runs behind the project's reverse proxy and inherits its certificate management.
- **Container-managed:** Deploys via Docker Compose with project-standard healthchecks, restart policy, and resource limits.
- **Matomo and Prometheus aware:** Toggles tracker and metrics integration based on the presence of the corresponding application roles.

## Quick Setup

### Development

Clone, set up the workstation, and deploy Content Delivery Network onto the local stack:

```bash
git clone https://github.com/infinito-nexus/core.git
cd core
make onboard
make compose-deploy mode=reinstall apps=web-svc-cdn full_cycle=false
```

### Production

Run the published image to provision the inventory and deploy Content Delivery Network to a managed server (the mounted volume persists the inventory):

```bash
APP=web-svc-cdn
HOST=<your-server>
DOMAIN=<your-domain>
TLS_MODE=self_signed
SSH_PUBLIC_KEY="<your-ssh-public-key>"

docker run --rm -it \
  -v "$PWD/inventories:/etc/infinito.nexus/inventories" \
  -e APP="$APP" -e HOST="$HOST" -e DOMAIN="$DOMAIN" -e TLS_MODE="$TLS_MODE" -e SSH_PUBLIC_KEY="$SSH_PUBLIC_KEY" \
  ghcr.io/infinito-nexus/core/debian bash -c '
    INVENTORY=/etc/infinito.nexus/inventories/production
    infinito administration inventory provision "$INVENTORY" \
      --inventory-file "$INVENTORY/devices.yml" \
      --host "$HOST" \
      --include "$APP" \
      --vars "{\"TLS_MODE\": \"$TLS_MODE\", \"DOMAIN_PRIMARY\": \"$DOMAIN\", \"users\": {\"administrator\": {\"authorized_keys\": [\"$SSH_PUBLIC_KEY\"]}}}" &&
    infinito administration deploy dedicated "$INVENTORY/devices.yml" \
      --password-file "$INVENTORY/.password" \
      --diff -vv'
```

## Further Resources

- [Nginx](https://nginx.org/)
- [Content delivery network on Wikipedia](https://en.wikipedia.org/wiki/Content_delivery_network)

## Credits

Implemented by **[Kevin Veen-Birkenbach](https://www.veen.world)**.
Part of the [Infinito.Nexus Project](https://s.infinito.nexus/code) and maintained by [Kevin Veen-Birkenbach](https://www.veen.world).
Licensed under the [Infinito.Nexus Community License (Non-Commercial)](https://s.infinito.nexus/license).