Skip to content

feat(config): add SPOOLMAN_API_URL with SPOOLMAN_UI_URL alias#94

Open
yfridelance wants to merge 2 commits into
drndos:mainfrom
yfridelance:feat/separate-spoolman-api-ui-urls
Open

feat(config): add SPOOLMAN_API_URL with SPOOLMAN_UI_URL alias#94
yfridelance wants to merge 2 commits into
drndos:mainfrom
yfridelance:feat/separate-spoolman-api-ui-urls

Conversation

@yfridelance
Copy link
Copy Markdown

@yfridelance yfridelance commented May 8, 2026

Summary

Allow SPOOLMAN_BASE_URL (used for UI links) and the URL used for backend
API calls to differ. Adds an optional SPOOLMAN_API_URL override and
introduces SPOOLMAN_UI_URL as a more semantic alias for the existing
SPOOLMAN_BASE_URL.

Fully backward compatible — existing deployments with only
SPOOLMAN_BASE_URL continue to work unchanged.

Problem

Today SPOOLMAN_BASE_URL is used for two distinct concerns:

  1. Backend HTTP calls from the OpenSpoolMan container to the Spoolman API
  2. UI links rendered into the browser (menu link, spool detail links,
    QR sticker targets)

In a reverse-proxy or split-horizon setup these need different URLs:

  • The backend reaches Spoolman via internal Docker DNS, e.g.
    http://spoolman:8000
  • The browser must use a public hostname terminated by the reverse
    proxy, e.g. https://spoolman.example.com

Currently users have to choose one. Picking the internal URL gives a
broken "Spoolman" link in the menu pointing to http://spoolman:8000
(unresolvable from a browser). Picking the external URL forces extra
DNS workarounds (extra_hosts, custom dns: entries) so the container
itself can resolve its own public hostname.

Solution

Variable Required Purpose Fallback
SPOOLMAN_BASE_URL (or SPOOLMAN_UI_URL) yes UI links shown to the user
SPOOLMAN_API_URL no Backend API calls SPOOLMAN_BASE_URL

Resolution order in config.py:

SPOOLMAN_BASE_URL = os.getenv("SPOOLMAN_BASE_URL") or os.getenv("SPOOLMAN_UI_URL")
SPOOLMAN_API_URL  = os.getenv("SPOOLMAN_API_URL")  or SPOOLMAN_BASE_URL
SPOOLMAN_API_V1   = f"{SPOOLMAN_API_URL}/api/v1"

Example: split-horizon deployment

# What users see in the browser (reverse proxy + TLS)
SPOOLMAN_BASE_URL=https://spoolman.example.com

# What the OpenSpoolMan container uses internally
SPOOLMAN_API_URL=http://spoolman:8000

Existing single-URL deployments are unaffected:

SPOOLMAN_BASE_URL=http://spoolman:8000   # used for both, as before

Changes

  • config.py — accept SPOOLMAN_UI_URL as alias; add optional
    SPOOLMAN_API_URL with fallback to SPOOLMAN_BASE_URL; replace
    internal references that hit the API to use SPOOLMAN_API_URL /
    SPOOLMAN_API_V1.
  • Templates — UI links continue to use SPOOLMAN_BASE_URL (no
    semantic change, just isolated from API resolution).
  • config.env.template — document the new optional variable and
    the alias.
  • README.md — short note in the configuration section.

Backward compatibility

  • No breaking changes.
  • All existing env files keep working.
  • If neither SPOOLMAN_BASE_URL nor SPOOLMAN_UI_URL is set, behaviour
    is unchanged from today (i.e. unset → existing failure mode).

Test scenarios

  • Only SPOOLMAN_BASE_URL set → API calls and UI links use it (current behaviour)
  • Only SPOOLMAN_UI_URL set → treated as SPOOLMAN_BASE_URL
  • Both SPOOLMAN_BASE_URL and SPOOLMAN_API_URL set → API uses
    SPOOLMAN_API_URL, UI uses SPOOLMAN_BASE_URL
  • SPOOLMAN_UI_URL and SPOOLMAN_API_URL set, no SPOOLMAN_BASE_URL
    → UI uses the alias, API uses its own value

Allow the Spoolman API and UI URLs to be configured independently for
reverse-proxy and split-horizon deployments, where the container reaches
Spoolman via internal DNS (e.g. http://spoolman:8000) while the browser
must use a public hostname (e.g. https://spoolman.example.com).

- Add optional SPOOLMAN_API_URL, falling back to SPOOLMAN_BASE_URL
- Accept SPOOLMAN_UI_URL as a semantic alias for SPOOLMAN_BASE_URL
- Backend API calls use SPOOLMAN_API_URL / SPOOLMAN_API_V1
- Rendered UI links (menu, spool detail) keep using SPOOLMAN_BASE_URL
- Document new variables in config.env.template and README

Backward compatible: deployments using only SPOOLMAN_BASE_URL continue
to work unchanged.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant