Ports#

Every host port a deployment publishes is one number plus a fixed offset. The number is deployment.port_base, which is 10000 unless you set it, and it reserves the thousand ports from there up – 10000–10999 by default. Move the base and the whole deployment moves with it, so a second deployment can share the host without being renumbered service by service:

# profile.yml
config:
  deployment.port_base: 20000

With that base the web terminal answers on 20100 instead of 10100, the database on 20800 instead of 10800, and so on for every row of the table below.

The layout#

Offsets count from deployment.port_base; the Port column is what each offset comes to at the default base of 10000. A row with a range is a band – one port per user, per worker, or per instance – and the first port of the band is the one a build publishes when only one of that thing exists. The virtual accelerator is the exception, and has its own section below.

Offset

Port

Service

Tier

Override key

Environment variable

+0

10000

nginx

gateway

modules.web_terminals.nginx_port

—

+1

10001

auth

gateway

modules.web_terminals.auth.port

—

+2

10002

history_origin

gateway

modules.web_terminals.history_port

—

+3

10003

history

gateway

—

—

+10

10010

dispatcher

dispatch

services.event_dispatcher.port

—

+11 to +49

10011-10049

worker

dispatch

services.dispatch_worker.worker_port_base

—

+53

10053

agent_record

services

agent_record.port

—

+60 to +69

10060-10069

qmd

services

services.qmd.port

—

+70

10070

tiled

services

services.bluesky.tiled_port

—

+71

10071

bluesky_web

services

services.bluesky_web.port

—

+80

10080

bluesky

services

services.bluesky.port

—

+81

10081

bluesky_second_lane

services

services.bluesky.port

—

+82

10082

optimizer

services

services.optimizer.port

—

+83

10083

optimizer_web

services

services.optimizer_web.port

—

+90 to +99

10090-10099

va_standin

services

services.live_standin.port

—

+100 to +199

10100-10199

web

panels

modules.web_terminals.web_base_port

—

+200 to +299

10200-10299

artifact

panels

modules.web_terminals.artifact_base_port

OSPREY_ARTIFACT_SERVER_PORT

+300 to +399

10300-10399

ariel

panels

modules.web_terminals.ariel_base_port

OSPREY_ARIEL_PORT

+500 to +599

10500-10599

channel_finder

panels

modules.web_terminals.channel_finder_base_port

OSPREY_CHANNEL_FINDER_PORT

+600 to +699

10600-10699

okf

panels

modules.web_terminals.okf_base_port

OSPREY_FACILITY_KNOWLEDGE_PORT

+700 to +799

10700-10799

system_health

panels

modules.web_terminals.system_health_base_port

OSPREY_HEALTH_PORT

+800

10800

postgres

stores

services.postgresql.port_host

—

+801

10801

mongo

stores

services.mongodb.port_host

—

+802

10802

graphdb_bolt

stores

services.graphdb.port_host

—

+803

10803

graphdb_http

stores

services.graphdb.http_port_host

—

+900 to +999

10900-10999

facility

facility

—

—

Service is the slot name. It is what a deployment template spells as osprey_ports.<slot>, and for the panels it is also the port-family name the per-user config keys are built from (modules.web_terminals.<family>_base_port).

Two rows share a key on purpose. The second Bluesky lane sits directly above the first and is derived from it, so services.bluesky.port moves both.

Which value wins#

A service settles on its port in this order, and the first one that is set wins:

  1. The environment variable, for the panels that have one. It is meant for a single run – the container the build renders sets it from the config, and setting it by hand overrides that container’s port for as long as it lives.

  2. The --port flag of osprey web. It moves that one run and nothing else.

  3. The service’s own key in the rendered config.yml – the Override key column. The value is an absolute port, not an offset, so a service pinned this way stays where it is put when port_base moves. Set it in profile.yml under config: so the next build keeps it.

  4. The layout – deployment.port_base plus the offset in the table.

Nothing in OSPREY reads a port from anywhere else, so a port you did not expect is always one of these four.

The web terminal is the one row of the table with an empty environment-variable cell that still has a variable behind it. The column lists what a panel’s own service reads, and the terminal is not one of those panels; its port comes from --port or the config. In a multi-user deployment, though, each per-user container is started with OSPREY_TERMINAL_WEB_PORT set, and that declaration outranks both – it is how the reverse proxy and the container stay agreed on which port the container is actually listening on, so nothing you pass on the command line inside that container can desync them.

The panel bands#

Each panel family owns a hundred ports, one per user: user i answers on the family’s first port plus i, so the user index reads off the port. With the default base, the second user’s terminal is on 10101 and their artifact gallery on 10201.

A deployment therefore holds at most 100 users. An index past 99 is refused whatever the family base ports are set to, because a family’s override key moves where its band starts, not how wide it is. More users need a second deployment on its own port_base; see What the perimeter needs.

Single-user mode is user index 0, which is the same slot the first user of a multi-user deployment takes. Two deployments at the same base therefore collide on those ports whichever mode they are in – give the second one its own port_base rather than moving panels individually.

The worker band#

The worker band is used only when event dispatch runs in host-network mode. Under the default bridge network the workers reach the dispatcher inside the container network and publish nothing on the host, so the band stays empty.

In host mode, worker 1 takes the first port of the band and each further worker the next one up. dispatch.worker_port_stride (default 1) widens the gap between them when a worker needs a range of its own. The band ends at +49: a build whose last worker would land past that is refused, and the message names the service the overflow would have collided with.

The facility band#

The framework publishes nothing between +900 and +999, which is 10900–10999 at the default base. That band is yours: a facility’s own services, added to a deployment alongside the ones OSPREY ships, can claim ports there without ever colliding with the framework. The exemplar profile’s facility MCP server takes the first of them, 10900.

The Channel Access exception#

Virtual-accelerator instance 1 is the one port port_base does not move. It serves EPICS on 5064, the Channel Access protocol port, so that clients configured for a real facility reach it without being reconfigured. A second deployment on the same host that also runs a virtual accelerator has to move it by hand, with services.virtual_accelerator.port.

Its pvAccess port is outside the block for the same reason. Instance 1 publishes its model surface on 5075, the pvAccess protocol port, and a second deployment on the same host that also runs a virtual accelerator moves it with virtual_accelerator.pva_port in the build profile, which the build writes to services.virtual_accelerator.pva_port.

Every further virtual accelerator is inside the block, in the va_standin band, and moves with the base like everything else.

The keys#

Each is set in profile.yml, but not at the same level of it. A key misplaced at the top level is refused; one misplaced under config: is accepted and not read. Write a config: key dotted, one per line: a nested deployment: mapping replaces the whole deployment subtree (see Build Profile — profile.yml).

Key

Default

Where it goes

What it does

deployment.port_base

10000

Under config:

The first port of the deployment’s block. Everything in the table above is this number plus an offset.

port_base

–

Top level

Shorthand for deployment.port_base, and wins over it when both are set.

worker_port_stride

1

Top-level dispatch:

The gap between one dispatch worker’s port and the next, in host-network mode. A build profile key, not a config: one – the build writes it through to services.dispatch_worker.worker_port_stride in the rendered config.

Each row’s Override key

–

Under config:

An absolute port for that one service, ignoring the layout.

# profile.yml
port_base: 20000

dispatch:
  triggers: my_triggers.yml
  network: host
  worker_port_stride: 10

A base below 1024 is refused: those ports are privileged, and the deployment could not bind its own block without running as root. A base whose block would run past 65535 is refused for the same practical reason. A base of 32768 or above builds, but warns – part of the block then overlaps the range the kernel hands out for outgoing connections, where a service can find its port already taken.