If you want to bind Puma to a unix socket, you can do this either by providing a -b options:
$ puma -b unix:///var/run/puma.sock
or using a puma.rb config file and setting the bind options.
# puma.rb config file # ...config... bind 'unix://var/run/puma.sock' # ...config
Unfortunately if you try to bind multiple Pumas to one socket, you might end up with issue similar to this one:
2015/02/16 12:12:22 [error] 2476#0: *16083152 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:12:23 [error] 2476#0: *16083176 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.10.203, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:12:23 [error] 2474#0: *16083180 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:12:43 [error] 2476#0: *16083282 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:12:43 [error] 2476#0: *16083292 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:12:43 [error] 2476#0: *16083301 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:13:33 [error] 2474#0: *16083390 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:13:33 [error] 2474#0: *16083392 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:13:33 [error] 2474#0: *16083397 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:13:33 [error] 2474#0: *16083398 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app" 2015/02/16 12:13:43 [error] 2477#0: *16083428 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 64.251.13.85, server: app, request: "POST /notifier_api/v2/notices HTTP/1.1", upstream: "http://unix:///var/run/puma.sock:/notifier_api/v2/notices", host: "app"
So, what is the reason? Your one and only socket might just not be enough. You can call bind multiple times, to create multiple sockets that your clustered Puma will use:
# ...config... bind 'unix://var/run/puma1.sock' bind 'unix://var/run/puma2.sock' bind 'unix://var/run/puma3.sock' bind 'unix://var/run/puma4.sock' bind 'unix://var/run/puma5.sock' # ...config...
Btw great docs for Puma - it's nowhere mentioned and the easiest place to understand how it works, is in the source code, that looks like that:
# Bind the server to +url+. tcp:// and unix:// are the only accepted # protocols. # def bind(url) @options[:binds] << url end