Substrate Caddy Module

Overview

Substrate is a custom Caddy v2 module designed to execute commands based on HTTP requests. It manages processes and proxies traffic to dynamically created backends.

What's special about it is that it allows the proxies themselves to tell Caddy which files and paths they are set up to respond.

You can think of it as a generic Franken PHP for your own backend.

Installation

To use this module, build Caddy with the Substrate module included:

xcaddy build --with github.com/fserb/substrate

Configuration

Substrate provides a global app and a handler for HTTP requests.

Global Configuration

To enable the module globally, use the substrate directive in the global options block:

{
    substrate
}

Handler Configuration

The substrate directive can be added to site blocks to define command execution logic. The syntax is:

substrate {
    command <command> [arguments...]
    env <key> <value>
    user <username>
    dir <directory>
    restart_policy always|never|on_failure
    redirect_stdout stdout|stderr|null|file <filename>
    redirect_stderr stdout|stderr|null|file <filename>
}

Directive Details

• command: Command to execute along with its arguments.
• env: Set environment variables for the process (can be repeated).
• user: Run the command as the specified user.
• dir: Set the working directory.
• restart_policy: Restart behavior.
  • always: Always restart when the process exits.
  • never: Never restart.
  • on_failure: Restart only if the process exits with a failure.
• redirect_stdout/redirect_stderr:
  • stdout: Output to stdout.
  • stderr: Output to stderr.
  • null: Discard output.
  • file <filename>: Write output to the specified file.

Example Configuration

example.com {
    substrate {
        command /usr/bin/myapp --flag value
        env FOO bar
        user appuser
        dir /var/myapp
        restart_policy on_failure
        redirect_stdout file /var/log/myapp/stdout.log
        redirect_stderr stderr
    }
}

How It Works

Substrate will start your proxy command and set up a SUBSTRATE env var with a URL. Once your proxy is running, it should send a POST request to this URL, containing a JSON, with the following format:

{
  host: "localhost:3333", // the host:port where the proxy is listening at.
  match: [".ext"],        // the list of file extensions we should listen to.
                          // this also automatically handles paths with the omitted
                          // extension or index.ext.
  paths: ["/up"],         // hard-coded paths that this proxy can answer.
  catch_all: ["/path/catchall.ext"],  // files that behave as catch-all for any subdir.
}

once this gets received, Caddy will start forwarding the proper requests to the proxy. You can send multiple jsons to the provided URL, overwriting the previous commands.

For more details, check the example directory.