How-to
Put Starboard behind a reverse proxy
A reverse proxy is a program that receives visits to your own web address over HTTPS and passes them on to
Starboard. These settings make Starboard trust the proxy and answer to your address, such as
https://starboard.example.com.
This is for people who already run, or are ready to set up, a reverse proxy such as Caddy, nginx or Traefik. If that is new to you, use a VPN (virtual private network) instead. Read Use Starboard away from home safely.
Before you begin
- You have a domain name, and it points at your home internet connection.
- A reverse proxy runs on the server, or on another computer on your home network, and it gets HTTPS certificates for your domain.
- You can enter commands on the server and edit a file there. Read The terminal: entering commands.
Steps
- On the server, go to the Starboard folder and open the
.envfile in a text editor. For example:
nano ~/starboard/.env
- Find these lines and change them, with your own address in place of
starboard.example.com:
STARBOARD_TRUST_PROXY=1
STARBOARD_ALLOWED_HOSTS=starboard.example.com
STARBOARD_TRUST_PROXY=1 tells Starboard to believe what the proxy says about the visitor and about
HTTPS. STARBOARD_ALLOWED_HOSTS lists the names Starboard answers to, separated by commas.
3. If the proxy runs on another computer, or in its own Docker container, also add its address:
STARBOARD_PROXY_ADDRESSES=192.168.1.21
Starboard always trusts a proxy on the server itself, so leave this empty in that case. 4. Save the file. In nano, press Ctrl+O, then Enter, then Ctrl+X. 5. Start Starboard again so it reads the new settings. From the Starboard folder, run:
docker compose up -d
If you installed from the ready-made image, there is no .env file. Add the same settings to the
environment list in compose.image.yaml instead, each on its own line starting with -. Then run
this command from that folder:
docker compose -f compose.image.yaml up -d
- Point your reverse proxy at Starboard on port 8095. With Caddy on the same server, this is the whole entry in its Caddyfile:
starboard.example.com {
reverse_proxy 127.0.0.1:8095
}
- Open
https://starboard.example.comand sign in. - When every address you use for Starboard starts with
https, go to Settings, then Security. Activate More settings. Then, under Sessions, activate Only send the sign-in cookie over HTTPS.
Things to note
- Never forward Starboard's port, 8095, straight to the internet from your router. Only the reverse proxy should be reachable from outside, and only over HTTPS.
- With 'Only send the sign-in cookie over HTTPS' active, you cannot sign in at a plain
http://address, such ashttp://192.168.1.20:8095. Deactivate it again if you still use one. - Set
STARBOARD_TRUST_PROXY=1only when a proxy sits in front of Starboard. Otherwise, leave it at0. - To answer to every name under your domain, start the entry with a full stop, such as
STARBOARD_ALLOWED_HOSTS=.example.com. - Starboard needs home network access active if the proxy runs on another computer. Read Choose who can open Starboard.
If it does not work
- "Starboard does not answer to the name": the address is missing from
STARBOARD_ALLOWED_HOSTS. Add it exactly as it appears in the browser, withouthttps://, then repeat step 5. - You sign in but are sent back to the sign-in page: Only send the sign-in cookie over HTTPS is active
and the address starts with
http. Sign in at yourhttpsaddress instead. If you still need the plain address, deactivate the switch in Settings, Security, under More settings. - A few wrong passwords lock everyone out, not only one device: Starboard treats every visit as coming
from the proxy, because it does not trust it yet. Add the proxy's address to
STARBOARD_PROXY_ADDRESSES, then repeat step 5.
Find out more
This page on GitHub, where the help is written.