2  Hello, World!

This is the most basic application one can build with Ambiorix:

library(ambiorix)

app <- Ambiorix$new()

home_get <- function(req, res) {
  res$send("Hello, World!")
}

app$get("/", home_get)

app$start(port = 3000L)

2.1 Instantiate App

We instantiate a new Ambiorix application using:

app <- Ambiorix$new()

Ambiorix is an R6 class. This explains why we use $ to access the class methods.

Intuitively, new() is the method which creates a new Ambiorix application.

2.2 Define Request Handler

We defined our “Hello, World” request handler as follows:

home_get <- function(req, res) {
  res$send("Hello, World!")
}

A handler must be a function that:

  1. Accepts two arguments, in this order:
    1. req: The request object. This contains all the information you need to know about the incoming HTTP request.
    2. res: The response object. This is an R6 class that you will use to send responses back to the client.
  2. Returns a valid Response value, in our case using res$send().

2.3 Attach Handler

To attach the request handler to the app instance, we use:

app$get("/", home_get)

After instantiation, the app object exposes several methods. Among them are these HTTP request methods:

  • get
  • post
  • put
  • patch
  • delete
  • options
  • all

All the above app methods accept three parameters, in this order:

  1. path: <String>, <Required>. The request path.
  2. handler: <Function>, <Required>. The request handler.
  3. error: <Function>, <Optional>. An error handler for this path. Defaults to NULL, meaning errors encountered while the handler is running will be handled by the global app error handler [if it is set].

So in our case, “/” is the request path we want the handler to apply to.

2.4 Start App

We finally start the web server on port 3000 of the host machine using:

app$start(port = 3000L)

The app$start() method accepts three parameters:

  1. port: <Integer>, <Optional>. The port to run the web server on. Defaults to NULL, which picks a random available port on the host machine.
  2. host: <String>, <Optional>. The network interface to bind the web server to. Defaults to NULL, which uses 0.0.0.0 as the host.
  3. open: <Logical>, <Optional>. Whether to open the app in the browser. Default value is interactive().

2.4.1 port

By default, Ambiorix serves an application at a random available port.

In the “Hello, World!”, try not to define a port ie. only have app$start() instead of app$start(port = 3000L).

However, explicitly setting a port—either manually or programmatically—is essential during deployment to ensure your app is correctly exposed to the outside world.

Ambiorix determines which port to bind the web server on in this specific order:

  1. ambiorix.port.force R option. Used by Belgic.
  2. AMBIORIX_PORT environment variable. Can be set in .Renviron.
  3. port parameter. Passed directly to app$start() or app$new().
  4. SHINY_PORT environment variable. Useful when deploying in Shiny Server et al.
  5. Random port. If none of the above are set, Ambiorix defaults to an available random port.

2.4.2 host

The host determines which network interface the server binds to.

  • 0.0.0.0 (the default) makes the app accessible from any network interface on the machine: containers, virtual machines, or when you want other devices on the network to reach the app.
  • 127.0.0.1 restricts access to the local machine only. It instructs the server to only listen for connections on the localhost. This is the best choice when you don’t want external access.

You generally only change the host when controlling who can connect to the running server.