From d3ebcac391358c3730dba6bb0ed4803481e60c06 Mon Sep 17 00:00:00 2001 From: jamesread Date: Tue, 28 Jul 2026 13:12:32 +0100 Subject: [PATCH] docs: Update how multiple ports work --- .../ROOT/pages/reference/multiple_instances.adoc | 10 ++++------ .../ROOT/pages/reference/network-ports.adoc | 14 ++++++++++---- 2 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/modules/ROOT/pages/reference/multiple_instances.adoc b/docs/modules/ROOT/pages/reference/multiple_instances.adoc index 7f46cf2..f8935b2 100644 --- a/docs/modules/ROOT/pages/reference/multiple_instances.adoc +++ b/docs/modules/ROOT/pages/reference/multiple_instances.adoc @@ -12,13 +12,13 @@ This is the easiest way to run multiple OliveTin instances. Follow the xref:inst 3. When creating the container, pass in the 2nd instance's config, eg; `-v /opt/OliveTin_two/:/config/` 4. When creating the container, set the external port, eg: `2337:1337` - 2337 is the external port) -You do not need to change the listenAddresses / ports for the other 3 ports that OliveTin uses, when you are running inside a container. +You do not need to change the listenAddresses / ports for the other 3 ports that OliveTin uses, when you are running inside a container. == Without containers - using a package (.tar.gz) If you are not using containers, then it is probably best not to use a `.deb/.rpm` installation, as those packages can only be installed for one instance. -Instead, follow the instructions for xref:install/targz.adoc[installing from a .tar.gz] archive. +Instead, follow the instructions for xref:install/targz.adoc[installing from a .tar.gz] archive. When you come to create the config.yaml file, OliveTin will look for this in it's own startup directory. Therefore it is probably best to extract the .tar.gz file like this and change the paths; @@ -28,7 +28,7 @@ When you come to create the config.yaml file, OliveTin will look for this in it' Because you are running outside of a container, you will also need to change the "internal" ports used by OliveTin so they are separate for all instances. OliveTin listens on 4 addresses (1 external, 3 internal) and needs 4 ports. You can read about these in the xref:reference/network-ports.adoc[network ports documentation]. -NOTE: OliveTin also supports reading the PORT environment variable, and will use this as a base port for the simgle frontend, will add 1 to start extra servers. For example of PORT is 2000, then the simgle frontend will start on port 2000, the REST API on 2001, and so on. +NOTE: If the `PORT` environment variable is set, OliveTin listens on that port for the single HTTP frontend (overriding `listenAddressSingleHTTPFrontend` in the config). When `PORT` is unset, the config value is used, or `1337` if that setting is omitted. `PORT` is also used as a base for the other internal listen addresses (+1, +2, …) when those are not set in the config. For example, if `PORT` is 2000, the single frontend starts on port 2000, the REST API on 2001, and so on. You could end up with a setup that looks like this; @@ -40,7 +40,7 @@ You could end up with a setup that looks like this; | OliveTin_three | `/opt/OliveTin_three` | `/opt/OliveTin_three/config.yaml` | `0.0.0.0:3337` | `localhost:3338` | `localhost:3339` | `localhost:3340` |=== -Note that you will also need to adjust the default systemd service file to point to your install directory, if using that. Here is an example for `OliveTin_two`; +Note that you will also need to adjust the default systemd service file to point to your install directory, if using that. Here is an example for `OliveTin_two`; .A modified systemd service file for a 2nd instance ---- @@ -55,5 +55,3 @@ Restart=always [Install] WantedBy=multi-user.target ---- - - diff --git a/docs/modules/ROOT/pages/reference/network-ports.adoc b/docs/modules/ROOT/pages/reference/network-ports.adoc index 5453241..813960d 100644 --- a/docs/modules/ROOT/pages/reference/network-ports.adoc +++ b/docs/modules/ROOT/pages/reference/network-ports.adoc @@ -4,7 +4,7 @@ OliveTin might surprise some people when they see it is listening on several ports when it starts up. Most of these ports are internal and localhost-only by default. It keeps the architecture of OliveTin clean and simple, and allows for -a lot of flexibility if needed. +a lot of flexibility if needed. == Network flow diagram @@ -38,18 +38,24 @@ server. Below is a detailed reference table. -== Port Reference Table +== Port Reference Table .Port reference table [%header,cols="1,2"] |=== -| Config file reference (and Default Address:Port) | Purpose +| Config file reference (and Default Address:Port) | Purpose | `listenAddressSingleHTTPFrontend: 0.0.0.0:1337` (listen on all available addresses) | This is a "micro reverse proxy" built into OliveTin. It's only purpose is to serve /ui and / (the web interface) from a single endpoint. This means that problems like CORSs and setting "external addresses" is not necessary. It does not do any caching or anything else. It can be disabled, but it makes life a lot easier for you. It's common to put your own reverse proxy like haproxy, traefik, etc in front of this single micro reverse proxy. | `listenAddressRestActions: localhost:1338` | REST - the protocol used by web pages to talk to web APIs. In the case of OliveTin, the API is used to get actions, and start actions. | `listenAddressGrpcActions:localhost:1339` | gRPC - a very popular method of service-to-service API communication. This provides the "real" API for OliveTin. | `listenAddressWebUI: localhost:1340` | Hosts a simple static web server with some HTML, stylesheets, Javascript etc for the web interface. | `listenAddressPrometheus: localhost:1341` | Hosts a prometheus endpoint, which is disabled by default. See xref:advanced_configuration/prometheus.adoc[Prometheus] to learn more. -|=== +|=== + +== PORT environment variable + +If the `PORT` environment variable is set at startup, OliveTin uses it as the listen port for `listenAddressSingleHTTPFrontend`, keeping the host from the config (default host `0.0.0.0`). This overrides an explicit port in `config.yaml`, which is useful on platforms that assign a port via `PORT` (for example Heroku or Cloud Run). + +When `PORT` is not set, OliveTin uses `listenAddressSingleHTTPFrontend` from the config, or `0.0.0.0:1337` if that setting is omitted. == See also