roadrunner_cowmachine

Run cowmachine applications, such as Zotonic, on Roadrunner.

cowmachine runs on Cowboy by default, and lets you pick its HTTP server. roadrunner_cowmachine is a cowmachine server: set it in your config, and your listeners, middlewares, controllers, and WebSocket handlers run on Roadrunner as they are.

🚧 Status

roadrunner_cowmachine is in 0.x. The core is functional and covered by tests, but the API may change between minor versions. Pin an exact version in your deps if you need stability across upgrades.

Installation

Add it next to cowmachine in your rebar.config (latest version on Hex):

{deps, [
    cowmachine,
    roadrunner_cowmachine
]}.

Make it cowmachine's server in your sys.config:

[{cowmachine, [
    {server, roadrunner_cowmachine}
]}].

Starting a listener

Start listeners with cowmachine_server:start_listener/2, as you would on Cowboy:

{ok, _} = cowmachine_server:start_listener(my_listener, #{
    port => 8000,
    middlewares => [my_dispatcher, cowmachine],
    env => #{cowmachine_controller => my_controller}
}).

It takes the options you already use with cowmachine:

• port and ip, with ipv6_v6only for an IPv6 address
• tls with the ssl server options for HTTPS
• backlog, max_connections, num_acceptors and request_timeout
• middlewares and env
• metrics_callback, with metrics_req_filter and metrics_resp_headers_filter, called once per request with the same metrics as Cowboy's
• options: the server's own options, here any Roadrunner listener option

{ok, _} = cowmachine_server:start_listener(my_listener, #{
    port => 8000,
    middlewares => [my_dispatcher, cowmachine],
    options => #{max_concurrent_requests => 10_000}
}).

Writing code for any server

Middlewares get a request map shaped like Cowboy's, so matching on it (#{path := Path}, #{bindings := Bindings}) works on every server, and controllers use cowmachine_req as always.

For the raw request, use cowmachine_cowreq, which has the same functions as cowboy_req:

execute(Req0, Env) ->
    case cowmachine_cowreq:header(~"x-api-key", Req0) of
        undefined -> {stop, cowmachine_cowreq:reply(401, Req0)};
        _Key -> {ok, Req0, Env}
    end.

Code that calls cowboy_req to send a response or read the body runs on Cowboy only.

Sponsors

roadrunner_cowmachine is open source and maintained on personal time. If you or your company find it useful, consider sponsoring.

I also accept coffees ☕

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for development setup, testing guidelines, and contribution workflow.

License

Copyright (c) 2026 William Fank Thomé

roadrunner_cowmachine is open-source under the Apache 2.0 License on GitHub.

See LICENSE.md for more information.