Running the Quickstart on an External Server

Network Interface Binding

One issue that you might encounter when trying to deploy Apicurio Studio to an external server is binding WildFly to the correct network interface. Often times a server may be multi-homed, and by default WildFly may not bind to the correct interface.

A very simple solution to this problem is to use the -b option when starting up Apicurio Studio. You can either specify the network interface you’d like, or you can simply use 0.0.0.0 to instruct WildFly to bind to all interfaces.

~/APICURIO_HOME/bin/standalone.sh -c standalone-apicurio.xml -b 0.0.0.0

For additional information about binding to a network interface, please see the WildFly documentation on the topic.

Connecting the UI to the Back-End API

When the Apicurio Studio user interface starts up, the server initializes it by sending it some configuration information located at config.js. This config.js file is generated by the server and includes a few pieces of information such as authentication, current user, and also the location of the back-end API that the UI should use. By default, the server will attempt to figure this URL out based on information included in the inbound HTTP Request it receives. However, some configurations can throw off this automatic detection, resulting in the wrong URL being sent to the UI (and thus a “connection failure” error).

In these cases you must manually configure the API URL. This can be done by setting an environment variable or system property.

Config Item Environment Variable System Property
Hub API URL APICURIO_UI_HUB_API_URL apicurio-ui.hub-api.url

Also useful when separating the UI from Back-End!

This setting is also (of course) quite useful if you decide to break apart the back-end API from the user interface (i.e. deploy the back-end to cluster A and the UI to cluster B). Separating the UI from the API is not typical, but can be useful if scaling them at different levels.

For example, you might set the system property by passing a -D parameter on the startup command line. You might also set an environment in your shell prior to startup. Another option is setting the system property in the standalone-apicurio.xml file:

<system-properties>
  <property name="apicurio-ui.hub-api.url"
            value="https://studio.example.org/hub-api" />
</system-properties>