How do you run ZAP's windowed session in a container with no display, and what still differs?

## With no switch at all, the program wants a display The GUI flag is only cleared by a switch, so `zap.sh` with no lifetime argument selects `GuiBootstrap`. The first thing that bootstrap does after logging its start-up line is ask the Java runtime whether the graphics environment is headless. If it is, it logs and prints a fatal message — "ZAP GUI is not supported on a headless environment", with a pointer at the help argument — and returns a failure code. In a container with no display that is the entire run: the process is gone in seconds, and the pipeline sees a start-up failure rather than a scan. That is the problem the shipped launcher scripts exist to solve, and they solve it in two different ways. ## `zap-x.sh`: a virtual display in front of the real program The script exports a display name, starts `Xvfb` on it if a lock file is not already there, and then runs `/zap/zap.sh` with **whatever arguments it was given**. When the program returns it captures the exit code, kills the virtual display, removes the lock and exits with the captured code. Two properties are worth noticing: - it is a **wrapper around the whole command line**, not a mode of its own, so it works the same whether you hand it the windowed session or a headless lifetime; - it **preserves the exit code**, so putting it in front of a one-shot run does not cost you the verdict. ## Webswing: the desktop over HTTP The second script is heavier. It starts a Webswing server against a virtual display and serves the real Swing desktop to a browser, so a person can drive the windowed session inside a container they have no screen on. The default images carry everything it needs — the X server, a window manager, the VNC server, the Webswing distribution itself. The program notices: when it detects its container it also notices a Webswing home directory and appends that fact to the container name it records about itself. Neither script is present in the small published image, which has no X server and no interpreter, so "run the desktop in a container" is a property of the default images specifically. ## `hasView()` is the branch that actually matters Here is the part that catches people. A virtual display makes the *graphics environment* non-headless, which is what lets `GuiBootstrap` proceed. It does not attach a view. The program's own behaviour is gated on `hasView()` — whether the view singleton was initialised — and the headless lifetimes deliberately never initialise it; the daemon bootstrap goes further and marks the view as never-to-be-initialised at all. So: | you run | graphics environment | view attached | view-gated behaviour | |---|---|---|---| | `zap.sh` on a desktop | not headless | yes | fires | | `zap-x.sh` with no lifetime switch | not headless | yes | fires | | `zap-x.sh` with a headless lifetime switch | not headless | no | does not fire | | a headless lifetime with no display at all | headless | no | does not fire | So a virtual display does not move the program's own behaviour across that branch: put `Xvfb` in front of a one-shot run and every view-gated path stays exactly where it was. What a display **does** buy you is anything in the run that needs one for itself — a real browser being the obvious case, which is why the default images carry an X server, a window manager and a browser together. Distinguish the two: the display is for the things the run drives, the view is for the program's own behaviour. ## Why that distinction has teeth A measurable example lives in the local-server start-up. When the main listener cannot be bound — the address is wrong, the port is taken — the code checks whether a view is attached. With one, it offers a dialog and lets you pick another port, and the program survives. With none, it logs, prints to standard error if the lifetime is the one-shot one, and terminates the program outright. Same failure, two completely different outcomes, decided by a branch that has nothing to do with whether a display exists. That shape recurs. More than one of this program's guard rails and recovery paths is written as "if there is a view", which is another way of saying it is a desktop behaviour and not a pipeline one; and a couple of its self-termination paths are written as "if there is *no* view", firing in automation and not on a human's screen. When you read this codebase, treat a view check as a statement about *who is watching*, and ask what happens on the side where nobody is. ## Practical advice If you want a human to look at a run inside a container, use the shipped launchers on a default image and accept that you are running the desktop. If you want a scan, use a headless lifetime, and add a virtual display only because something in the run needs one — never in the hope of changing how the program itself behaves, because it will not. And when you are debugging "it worked on my laptop", check which side of the view branch each machine was on before you look at anything else.