[FEATURE] Support standard color control environment variables. Use colored logs by default in docker contexts.

[markope]

Feature Description

Summary: Support NO_COLOR/FORCE_COLOR environment variables and improve color detection for Docker environments

Problem Statement:
When running crossbar in Docker containers or non-TTY environments, log output appears as plain uncolored text because the current color detection relies solely on sys.__stdout__.isatty(). This makes logs harder to read and doesn't follow modern CLI conventions for color control. Users have no way to force colors on or off via environment variables.

Proposed Solution:
Enhance the color auto-detection logic in _start_logging() to:

1. Respect NO_COLOR environment variable to explicitly disable colors (per https://no-color.org/)
2. Respect FORCE_COLOR and CLICOLOR_FORCE environment variables to explicitly enable colors
3. Default to enabling colors when in auto mode

Use Cases

Use Case 1:

• Actor: DevOps engineer running crossbar in Docker
• Goal: View colored log output via docker logs for easier debugging
• Example: docker logs crossbar-container displays colored output distinguishing log levels

Use Case 2:

• Actor: Developer with accessibility needs or specific terminal
• Goal: Disable colors that may not render correctly
• Example: NO_COLOR=1 crossbar start runs without any ANSI color codes

Use Case 3:

• Actor: CI/CD pipeline operator
• Goal: Force colors in CI logs that support ANSI (GitHub Actions, GitLab CI)
• Example: FORCE_COLOR=1 crossbar start ensures colored output in CI logs

Example API/Usage

# Force colors on (Docker, CI/CD)
FORCE_COLOR=1 crossbar start

# Force colors off (accessibility, piping to file)
NO_COLOR=1 crossbar start

# Auto-detect (default) - now defaults to colors enabled
crossbar start

# Current behavior in _start_logging():
if color == "auto":
    if sys.__stdout__.isatty():
        color = True
    else:
        color = False  # Always disabled in Docker

# Proposed behavior:
if color == "auto":
    if os.environ.get('NO_COLOR'):
        color = False
    elif os.environ.get('FORCE_COLOR') or os.environ.get('CLICOLOR_FORCE'):
        color = True
    elif sys.__stdout__.isatty():
        color = True
    else:
        color = True  # Default to colors enabled

Alternatives Considered

Alternative 1: Only add TTY detection improvement

• Pros: Minimal change
• Cons: No user control via environment variables

Alternative 2: Add a new CLI flag --force-color

• Pros: Explicit control
• Cons: Doesn't follow industry standards, requires config changes

Why the proposed solution is better: Uses widely-adopted conventions (NO_COLOR, FORCE_COLOR, CLICOLOR_FORCE) that users already know from other tools. No new CLI flags needed, works with existing --color=auto option.

Impact Assessment

Breaking Changes: Minor - logs that previously had no color in non-TTY environments will now show colors by default. Users can set NO_COLOR=1 to restore previous behavior.

Affected Components:

• Core library (src/crossbar/node/main.py)
• API
• Documentation
• Tests
• CI/CD

Estimated Complexity: Low

Additional Context

Related Issues:

• None known

External References:

• https://no-color.org/ - NO_COLOR standard
• https://force-color.org/ - FORCE_COLOR convention
• CLICOLOR_FORCE - BSD/macOS convention also used by many tools

Checklist

• I have searched existing issues to avoid duplicates
• I have described the problem clearly
• I have provided use cases
• I have considered alternatives
• I have assessed impact and breaking changes

[oberstet]

Colored output requires a TTY. If you want colors when running Crossbar in Docker, start the container with -t (or tty: true in docker-compose). Without a TTY, output is log data and must not contain ANSI escape sequences.

Using -t does already work correctly:

oberstet@amd-ryzen5:~$ docker run --rm python:3.12-slim python -c \
"import sys; print('isatty:', sys.__stdout__.isatty()); print('\033[31mTHIS IS RED TEXT\033[0m')" \
> out.txt
oberstet@amd-ryzen5:~$ cat out.txt 
isatty: False
THIS IS RED TEXT
oberstet@amd-ryzen5:~$ cat -v out.txt 
isatty: False
^[[31mTHIS IS RED TEXT^[[0m
oberstet@amd-ryzen5:~$ docker run --rm -t python:3.12-slim python -c \
"import sys; print('isatty:', sys.__stdout__.isatty()); print('\033[31mTHIS IS RED TEXT\033[0m')" \
> out.txt
oberstet@amd-ryzen5:~$ cat -v out.txt 
isatty: True^M
^[[31mTHIS IS RED TEXT^[[0m^M
oberstet@amd-ryzen5:~$ 

[oberstet]

BUT, looking at the current code https://github.com/crossbario/crossbar/blob/2e2007d613de14cc491c77d35842bf03d4f27da3/src/crossbar/node/main.py#L672C1-L747C34:

Colored logging should be enabled only when sys.stdout.isatty() is true. This reflects the actual output destination and correctly handles terminals, redirection, Docker, and logging wrappers. Using sys.__stdout__ bypasses these mechanisms and produces incorrect behavior.

I think the underlying issue is that _start_logging() uses sys.__stdout__.isatty() to detect whether to enable colored logging:

if sys.__stdout__.isatty():
    color = True
else:
    color = False

Using sys.__stdout__ here is problematic because it bypasses any redirection or logging wrappers. In Docker, CI, or when stdout/stderr are redirected to a file or pipe, sys.__stdout__.isatty() can return True even though the output is not a terminal. This can produce ANSI escape codes in logs, which is exactly what we want to avoid.

The proper API is sys.stdout.isatty() (or sys.stderr.isatty() depending on which stream you log to). This correctly reflects whether the log output is actually a terminal.

Minimal patch (simple variant)

-            if sys.__stdout__.isatty():
+            if sys.stdout.isatty():
                 color = True
             else:
                 color = False

Optional stricter variant (both stdout and stderr must be a terminal)

-            if sys.__stdout__.isatty():
+            if sys.stdout.isatty() and sys.stderr.isatty():
                 color = True
             else:
                 color = False

This fixes:

• Docker logs / non-TTY containers
• stdout redirection (> file)
• CI pipelines
• Logging wrappers like Twisted observers

With this change, you no longer need special Docker logic to disable colors: the isatty() check naturally ensures colors are only enabled when output is a terminal. This keeps the default behavior safe while still allowing colors when running interactively with -t. There is no need for any environment variables.

[oberstet]

so what's the problem with the current CLI option --color ?

(cpy312) oberstet@amd-ryzen5:~/work/wamp/crossbar$ crossbar start --help

usage: /home/oberstet/work/wamp/crossbar/.venvs/cpy312/bin/crossbar start [-h] [--color {true,false,auto}]
                                                                          [--loglevel {none,error,warn,info,debug,trace}]
                                                                          [--logformat {syslogd,standard,none}]
                                                                          [--logdir LOGDIR] [--logtofile] [--cbdir CBDIR]
                                                                          [--config CONFIG] [--shutdownafter SHUTDOWNAFTER]

options:
  -h, --help            show this help message and exit
  --color {true,false,auto}
                        If logging should be colored.
  --loglevel {none,error,warn,info,debug,trace}
                        How much Crossbar.io should log to the terminal, in order of verbosity.
  --logformat {syslogd,standard,none}
                        The format of the logs -- suitable for syslogd, not colored, or colored.
  --logdir LOGDIR       Crossbar.io log directory (default: <Crossbar Node Directory>/)
  --logtofile           Whether or not to log to file
  --cbdir CBDIR         Crossbar.io node directory (overrides ${CROSSBAR_DIR} and the default ./.crossbar)
  --config CONFIG       Crossbar.io configuration file (overrides default CBDIR/config.json)
  --shutdownafter SHUTDOWNAFTER
                        Automatically shutdown node after this many seconds.
(cpy312) oberstet@amd-ryzen5:~/work/wamp/crossbar$