Networking

This section specifies how your Blocklet is exposed to the network. After defining how your Blocklet runs (see Execution), the next step is to configure its network interfaces, ports, and services through the interfaces property in blocklet.yml.

An interface defines a public endpoint for your Blocklet, mapping a URL path to an internal port where your application is listening. This allows Blocklet Server to route incoming requests correctly.

The interfaces Property#

The interfaces property is an array of objects, where each object defines a single network interface. A Blocklet can have multiple interfaces, for example, one for a public web UI and another for a .well-known service.

Example: Basic Web Interface#

Here is a simple configuration for a web application:

This example defines a primary web interface named publicUrl that can be mounted at any path (prefix: '*') and forwards traffic to the port defined by the BLOCKLET_PORT environment variable.

Interface Properties#

Each object in the interfaces array can have the following properties:

Property	Type	Description	Required
type	string	The type of interface. Valid values are web (for standard web traffic) and wellknown (for /.well-known/ paths).	Yes
name	string	A unique, human-readable name for the interface (e.g., publicUrl, adminApi).	Yes
path	string	The root path inside the Blocklet that this interface serves. Defaults to /.	No
prefix	string	The URL prefix where the interface is mounted. * allows it to be mounted at any path. For wellknown types, this must start with /.well-known. Defaults to *.	No
protocol	string	The protocol used. Valid values are http and https. Defaults to http.	No
port	string or object	Defines the port mapping. Can be a string (e.g., BLOCKLET_PORT, an uppercase variable name) or an object { "internal": "INTERNAL_PORT", "external": 8080 } for explicit mapping. Defaults to BLOCKLET_DEFAULT_PORT_NAME.	No
containerPort	number	The port number inside the container to expose. Primarily used for Docker-based Blocklets.	No
hostIP	string	Binds the interface to a specific host IP address (ipv4 or ipv6).	No
proxyBehavior	string	Determines how requests are handled. service (default) processes requests through Blocklet services (like auth). direct bypasses services for a direct proxy to the application.	No
cacheable	string[]	An array of path prefixes (e.g., ['/assets', '/images']) that can be cached by Blocklet Server for better performance.	No
services	object[]	An array of services to attach to this interface, such as authentication. See the Features section for details.	No
endpoints	object[]	An array of OCAP (Open Component Access Protocol) endpoints exposed by this interface, defining a structured API.	No

Advanced Example: Multiple Interfaces#

This example shows a Blocklet with two distinct interfaces: one for the main application and another for a specific /.well-known configuration.

In this configuration:

• The web interface is protected by an authentication service.
• The wellknown interface provides a public assetlinks.json file, bypassing any services for direct access.

Now that you understand how to configure your Blocklet's network presence, you can proceed to the next section to learn how to declare system requirements and dependencies.

Next: Dependencies