{% comment %}
Copyright (C) The Arvados Authors. All rights reserved.

SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}

h2. Published ports

Containers can expose web services.  These can be interactive web applications such as Jupyter notebooks or AI chats, or HTTP-based APIs.  Arvados acts as a reverse proxy, forwarding HTTP requests to the container and relaying responses back to the client.  Arvados routes HTTP requests based on the URL, based on the following format:

@https://<uuid>-<port>.containers.zzzzz.example.com@

Where the @uuid@ is a container UUID or container request UUID, and @port@ is the port on the container to which the client wishes to send the request.  To be able to accept requests, the container should listen on all interfaces (i.e. bind to 0.0.0.0; binding only to loopback, i.e. 127.0.0.1 will *not* work) and handle plain text HTTP/1.1 traffic.

The @published_ports@ field of the container record advertises which ports on the container are available to receive requests.

The value @published_ports@ is a hash.  Each key in the hash is a port number that the container is listening on.  Each entry in the hash has three keys described here:

table(table table-bordered table-condensed).
|_. Key|_. Type|_. Description|
|access|string|One of "public" or "private".  If "private", the client connecting to the container must provide an Arvados API for the user who submitted the container request(s) corresponding to the container.  The token is provided as a query parameter @?arvados_api_token=...@.  Arvados will consume the query parameter and respond with a redirect and a cookie used to authenticate subsequent requests.  If "public", no authentication is required.|
|label|string|A string that will be displayed to the user on Workbench describing the service.  Cannot be empty.|
|initial_path|string|The relative path that should be included when constructing the URL that will be presented to the user in Workbench.  May include any or none of path, fragment and query parameter parts of the URL, or be blank.  Leading slash is optional.|

For example:

<pre>
{
  "published_ports": {
    "80": {
      "access": "private",
      "label": "Jupyter notebook instance",
      "initial_path": "",
    }
  }
}
</pre>

If the container is listening on other ports it is possible to connect to those unpublished ports with the appropriate numeric @<port>@ in the @<uuid>-<port>@ part of the hostname.  Unpublished ports are not displayed in Workbench and have a default acccess level of "private".