Deployment

Falcon Serve

falcon serve is not designed for deployment. Do not use it for deployment.

Falcon Hosts

falcon host is designed for deployment.

Configuration

falcon host loads configuration from the falcon.rb file in your application directory. This file contains configuration blocks which define how to host the application and any related services. This file should generally be executable and it invokes falcon host which starts all defined services.

Here is a basic example which hosts a rack application:

#!/usr/bin/env -S falcon host
# frozen_string_literal: true

load :rack, :lets_encrypt_tls, :supervisor

hostname = File.basename(__dir__)
rack hostname, :lets_encrypt_tls do
	cache true
end

supervisor

These configuration blocks are constructed using build-environment, and the defaults are listed in the Falcon source code.

Application Configuration

The rack environment inherits the application environment. These environments by default are defined for usage with falcon virtual, but you can customise any parts of the configuration, e.g. to bind a production host to localhost:3000 using plaintext HTTP/2:

#!/usr/bin/env -S falcon host
# frozen_string_literal: true

load :rack, :supervisor

hostname = File.basename(__dir__)
rack hostname do
	endpoint Async::HTTP::Endpoint.parse('http://localhost:3000').with(protocol: Async::HTTP::Protocol::HTTP2)
end

supervisor

You can verify this is working using nghttp -v http://localhost:3000.

Falcon Virtual

Falcon can replace Nginx as a virtual server for Ruby applications.

/--------------------\
|   Client Browser   |
\--------------------/
          ||          
  (TLS + HTTP/2 TCP)
          ||          
/--------------------\
| Falcon Proxy (SNI) |
\--------------------/
          ||          
  (HTTP/2 UNIX PIPE)
          ||          
/--------------------\
| Application Server |   (Rack Compatible)
\--------------------/

You need to create a falcon.rb configuration in the root of your applications, and start the virtual host:

$ cat /srv/http/example.com/falcon.rb
#!/usr/bin/env -S falcon host

load :rack, :lets_encrypt_tls, :supervisor

rack 'hello.localhost', :lets_encrypt_tls

supervisor

$ falcon virtual /srv/http/example.com/falcon.rb

The Falcon virtual server is hard coded to redirect http traffic to https, and will serve each application using an internal SNI-based proxy.