ShimmerCat QS uses two configuration files, both of which are expected to be at fixed locations relative to the server'ss working directory:

The devlove.yaml file

The basic features of this file are covered in detail in our tutorials in this documentation. Here is the full reference for the file, using json-schema, though we have used YAML instead of JSON for the schema so that it is easier to read. Scroll to after the text-box to find additional information about each object.

---
title: ShimmerCatDevlove
$schema: http://json-schema.org/draft-04/schema#
type: object
properties:
    shimmercat-devlove:
      type: object
      properties:
        domains: 
          type: object
          minProperties: 1
          patternProperties:
            "elec +[a-zA-Z0-9.-]+": 
                $ref: "#/definitions/electricDomain"
            "api +[a-zA-Z0-9.-]+":
                $ref: "#/definitions/apiDomain"
          additionalProperties: false
      required: ["domains"]
additionalProperties: false
required: ["shimmercat-devlove"]
definitions:
  electricDomain:
    type: object
    title: ElectricDomain
    properties:
      root-dir:
        oneOf:
          - type: string
          - $ref: "#/definitions/rootDirUseConsultant"
          - $ref: "#/definitions/rootDirFetchBackend"
      views-dir:
        type: string
      consultant:
        $ref: "#/definitions/consultant"
      consultants:
        type: object
        additionalProperties:
          $ref: "#/definitions/consultant"
      cache-key:
        type: string
      change-url:
        type: array
        items:
          - type: string
      changelist-settings:
        type: object
        properties:
          tNew:
             type: number
          tOld:
             type: number
        required: ["tNew", "tOld"]
      prob-accelerator-kicks-in:
        type: number
      bot-protection-enabled:
        type: boolean
    required: 
      - "root-dir"
    additionalProperties: false
  apiDomain:
    type: object
    title: ApiDomain
    properties:
      port:
        $ref: "#/definitions/networkAddress"
    required: 
      - port
  applicationPort:
    type: object 
    title: ApplicationPort
    properties:
      # TO-DO: We can make the `connect-to` property more precise
      "connect-to":
        $ref: "#/definitions/networkAddress"
      "document-root":
        type: string
      "application-protocol":
        type: string 
        pattern: |
          fastcgi|fcgi|http|http11|HTTP/1\.1|HTTP
      "encryption-level":
        type: string
        pattern: |
          plain|tls 
      "timeouts": 
        $ref: "#/definitions/applicationLifecycleTimeouts"
    required: ["connect-to"]
  networkAddress:
      type: string 
      pattern: "^(((lookup\\([a-zA-Z0-9.-]+\\))|([0-9]+\\.[0-9]+\\.[0-9]+\\.[0-9]+))?:)?([0-9]+)$"
  applicationLifecycleTimeouts:
      type: object
      title: Application Lifecycle Timeouts
      properties:
        # Will add more, like "connection" and "handshake" later
        "inactivity":
           type: "number"
        "connection":
           type: "number"
        "handshake":
           type: "number"
  consultants:
      type: object
      additionalProperties:
        $ref: "#/definitions/applicationPort"
  consultant:
      oneOf:
        - $ref: "#/definitions/networkAddress"
        - $ref: "#/definitions/applicationPort"
  rootDirUseConsultant:
      type: object
      properties:
        "use-consultant":
          type: string
      additionalProperties: false
      required:
        - "use-consultant"
  rootDirFetchBackend:
      type: object
      properties: 
        "fetch-backend":
          type: string
        "http-port":
          $ref: "#/definitions/networkAddress"
        "use-host":
          type: string
        "concurrency-limit":
          type: number
        "path-prefix":
          type: string
      required: 
        - "fetch-backend"
        - "use-host"

The following sub-sections explain the objects defined in the schema above.

Top objects

The top object in the devlove.yaml should only contain one property, shimmercat-devlove, and right below it another property domains:

---
shimmercat-devlove:
  domains: 
    ... 

domains should contain an object, with one property for each domain served by ShimmerCat.

Domains

The contents of the domains object are two types of domains: file-serving domains, which we call electric, and pure-forwarding domains, which we call api domains (using lowercase for "api").

Electric domains can be recognized automatically by the subkeys root-dir or consultant. Like this:

shimmercat-devlove:
    domains:
        www.mysite.com:
            root-dir: www

They can also be distinguished by prefixing the word elec to the key with the domain name.

API domains can be recognized automatically by specifying the subkey port with the web application port to which ShimmerCat should proxy requests, or by prefixing the word api to the key with the domain name, like this:

shimmercat-devlove:
    domains:
        api my-api.mysite.com:
            port: "8080"

Note that the value of the port property should follow the network-address schema, described below.

Of course, you can mix and match domains of different types in a single devlove.yaml file. Like this:

shimmercat-devlove:
    domains:
        api1.mysite.com:
            port: "8080"
        www.mysite.com:
            root-dir: www

What follow are all properties of the electric domains.

The root-dir

This is a string denoting a directory with static assets to serve on the domain. Or an object, describing an equivalent mean to obtain the assets. ShimmerCat QS, being a caching server, will just read the files from this place as they are requested by website visitors and copy-and-process them to its internal cache in the scratch folder. This means that you can mount a high latency filesystem and use it as your root-dir, and still obtain a very fast website.

This is the only mandatory property in an electric domain configuration object.

The views-dir

This is where views are expected to be. If left unspecified and root-dir is a string, then the root-dir will be used. Note that view files are expected to be in a local filesystem, since at best they are just cached for a few seconds.

Consultant(s)

In ShimmerCat lingo, a consultant is an external application that provides either contents or base data to create contents (depending on the content-disposition). In the first case "consultant" is synonymous to "origin" and "application backend".

A single domain can access more than one consultant, via the consultants property of the domain configuration object. For example:

...
       consultants:
          my-php-app:
            ...
          my-node-js-app:
            ...

The snippet above defines two consultants with names my-php-app and my-node-js-app, both of which can be served in the same domain. Their names can be used in a view to decide where to forward a request to.

Whenever a consultant is needed but no consultant name is provided, ShimmerCat QS fills in the missing name with default, and tries to use that one.

The property consultant, the singular of consultants, is just a shortcut to

       consultants:
          default: 
             ...

Other than that, the properties of each consultant object are more or less self-explanatory.

Command Line Reference

Command line options across modes

ShimmerCat, as of version 1.5.0 has two public-facing modes of operation: devlove and Internet The modes have slightly different options, and some of them have different defaults across modes.

In addition, there are two non-public modes:

In any of the modes, you can see which options ara available via the --help sub-option:

$ shimmercat devlove --help
A mode for web developers
...

General options

Options for development

The following options are handy to debug protocol-specific issues:

When developing a website, it is handy at times to disable all cache directives or even HTTP/2 Push. These two options are for that: