1. Souin reverse-proxy cache
2. Configuration
   2.1. Required configuration
   2.2. Optional configuration
3. Diagrams
   3.1. Sequence diagram
4. Cache systems
5. Examples
   5.1. Træfik container
6. SSL
   6.1. Træfik
   6.2. Apache
   6.3. Nginx
7. Credits

Souin is a new cache system suitable for every reverse-proxy. It will be placed on top of your current reverse-proxy whether it's Apache, Nginx or Traefik.
As it's written in go, it can be deployed on any server and thanks to the docker integration, it will be easy to install on top of a Swarm, or a kubernetes instance.
It's RFC compatible, supporting Vary, request coalescing and other specifications related to the RFC-7234

If you need redis or other custom cache providers, you have to use the full-featured version. You can read the documentation, on the full-featured branch to discover the specific parts.

The configuration file is stored at /anywhere/configuration.yml. You can edit it provided you fill at least the required parameters as shown below.

default_cache: # Required part
  port: # Ports to expose Souin
    web: 80
    tls: 443
  ttl: 10 # Default TTL
reverse_proxy_url: 'http://traefik' # If it's in the same network you can use http://your-service. Then just use https://yourdomain.com

This is a fully working minimal configuration for a Souin instance

# /anywhere/configuration.yml
default_cache:
  headers: # Default headers concatenated in stored keys
    - Authorization
  cache_providers:
    - all # Enable all providers by default
  redis: # Redis configuration
    url: 'redis:6379'
  regex:
    exclude: 'ARegexHere' # Regex to exclude from cache
ssl_providers: # The {providers}.json to use
  - traefik
urls:
  'https:\/\/domain.com\/first-.+': # First regex route configuration
    ttl: 1000 # Override default TTL
  'https:\/\/domain.com\/second-route': # Second regex route configuration
    ttl: 10 # Override default TTL
    headers: # Override default headers
    - Authorization
  'https?:\/\/mysubdomain\.domain\.com': # Third regex route configuration
    ttl: 50
    headers: # Override default headers
    - Authorization
    - 'Content-Type'

The cache system sits on top of two providers at the moment. It provides an in-memory and redis cache systems because setting, getting, updating and deleting keys in Redis is as easy as it gets.
In order to do that, Redis needs to be either on the same network than the Souin instance when using docker-compose or over the internet, then it will use by default in-memory to avoid network latency as much as possible. Souin will return at first the in-memory response when it gives a non-empty response, then the redis one will be used with same condition, or fallback to the reverse proxy otherwise.

The cache invalidation is build for CRUD requests, if you're doing a GET HTTP request, it will serve the cached response when it exists, otherwise the reverse-proxy response will be served.
If you're doing a POST, PUT, PATCH or DELETE HTTP request, the related cache GET request, and the list endpoint will be dropped.
It works very well with plain API Platform integration (not for custom actions at the moment) and CRUD routes.

Træfik is a modern reverse-proxy and help you to manage full container architecture projects.

# your-traefik-instance/docker-compose.yml
version: '3.4'

x-networks: &networks
  networks:
    - your_network

services:
  traefik:
    image: traefik:v2.0
    command: --providers.docker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /anywhere/traefik.json:/acme.json
    <<: *networks

  # your other services here...

networks:
  your_network:
    external: true

# your-souin-instance/docker-compose.yml
version: '3.4'

x-networks: &networks
  networks:
    - your_network

services:
  souin:
    image: darkweak/souin:latest
    ports:
      - 80:80
      - 443:443
    depends_on:
      - redis
    environment:
      GOPATH: /app
    volumes:
      - /anywhere/traefik.json:/ssl/traefik.json
    <<: *networks

  redis:
    image: redis:alpine
    <<: *networks

networks:
  your_network:
    external: true

As Souin is compatible with Træfik, it can use (and it should use) traefik.json provided on træfik. Souin will get new/updated certs from Træfik, then your SSL certs will be up to date as far as Træfik will be too To provide, acme, you just have to map volume as above

    volumes:
      - /anywhere/traefik.json:/ssl/traefik.json

Souin will listen to the apache.json file. You have to setup your own way to aggregate your SSL cert files and keys. Alternatively you can use a side project called dob, it's open-source and written in go too

    volumes:
      - /anywhere/apache.json:/ssl/apache.json

Souin will listen to the nginx.json file. You have to setup your own way to aggregate your SSL cert files and keys. Alternatively you can use a side project called dob, it's open-source and written in go too

    volumes:
      - /anywhere/nginx.json:/ssl/nginx.json

At the moment you can't choose the path for the *.json file in the container, they have to be placed in the /ssl folder. In the future you'll be able to do that by setting one env var If none *.json file is provided to container, a default cert will be served.

Thanks to these users for contributing or helping this project in any way

• oxodao
• Deuchnord
• Sata51
• Pierre Diancourt