Open the MonoDoc Web Viewer with monodoc-http

Run monodoc-http and it grabs a random port, starts XSP, and tries to pop your browser open, so when nothing shows you need to know which half broke.

On this machine the package is version 4.2-3.2. The command has no useful options of its own: it just chooses a temporary port and launches the web server for you. Allow about ten minutes.

You need: a graphical session for the automatic browser launch, plus the monodoc-http and mono-xsp4 packages installed.
No sudo. The wrapper is designed to bind to a high, local port, so this is an ordinary user job.

1. Check the installed wrapper

Confirm which script will run and record the package version. These commands only read local state:

$ command -v monodoc-http
/usr/bin/monodoc-http
$ dpkg-query -W -f='${Package} ${Version}\n' monodoc-http
monodoc-http 4.2-3.2

The Debian file is a Bash script. It sets the locale to C, chooses a random port, rejects values below 1025, and checks whether the port is already in use. It then starts xsp4 with the web root /usr/share/monodoc/web, the loopback address 127.0.0.1, and the selected port.

Checkpoint: verify the script syntax without starting anything:

$ bash -n /usr/bin/monodoc-http
$ sed -n '1,80p' /usr/bin/monodoc-http

Do not expect monodoc-http --help to print a command reference. The script does not parse its arguments, so extra arguments will not pick a port, a bind address, a document root, or a browser.

2. Start the viewer

Run the wrapper in a terminal belonging to your desktop session:

$ monodoc-http

The XSP web server is starting now. To view the monodoc pages, your
web browser will open http://localhost:PORT/ now.

The actual output contains a different number in place of PORT. The script clears the terminal first, prints that message, waits five seconds in a background shell, and asks sensible-browser to open the URL. The foreground process is xsp4, so leave this terminal running while you browse.

There is no persistent service to stop or configuration to undo. Press Ctrl-C in the terminal when you are done: that kills the foreground XSP process and closes the temporary server.

3. Verify the listener and the address

If the browser does not open, read the URL printed by the wrapper and test it yourself. Replace PORT with the number shown in your terminal:

$ curl --fail http://127.0.0.1:PORT/
<!DOCTYPE html>
...
$ ss -ltnp | grep ':PORT '
LISTEN ... 127.0.0.1:PORT ...

The HTML varies with the installed MonoDoc files, and the ss columns vary by system. What matters is an HTTP response and a listener on 127.0.0.1: loopback is reachable from this machine only, never from other hosts on the network.

Warning: use localhost or 127.0.0.1 exactly as printed. Do not swap in the machine's LAN address to make a remote browser work: this wrapper has no authentication and no HTTPS, so exposing it beyond the local host is an unsafe change.

4. Read the package configuration without changing it

Debian also installs an XSP configuration fragment. Inspect it if you are integrating MonoDoc with a service manager or another web-server arrangement:

$ sed -n '1,80p' /etc/mono-server4/conf.d/monodoc-http/10_monodoc-http
# This is the configuration file
# for the monodoc-http
path = /usr/share/monodoc/web
alias = /monodoc

This file describes the web path and the /monodoc alias for an XSP or server integration. It is not an argument file consumed by the monodoc-http script.

Do not edit it as a first troubleshooting step.
Do not wire up a service from it until you have decided how access control, logging, upgrades and shutdown will work.

5. Diagnose an XSP startup failure

If the wrapper prints its startup message and then exits with a .NET exception, the random-port selection and browser helper have already run. Check the underlying server directly, using the same root and loopback binding but a fixed high port:

$ xsp4 --root /usr/share/monodoc/web --port 12086 --address 127.0.0.1
The XSP web server is starting now...
Unhandled Exception:
System.TypeLoadException: ...

Example: on this host, the installed monodoc-http 4.2-3.2 wrapper reaches XSP fine, but XSP itself fails with a System.TypeLoadException involving Mono.Security.Protocol.Tls.PrivateKeySelectionCallback. That is a local Mono/XSP assembly compatibility problem, not evidence that the web root is missing. The command exits, so there is no viewer to browse.

Check the related packages before changing anything:

$ dpkg-query -W -f='${Package} ${Version}\n' monodoc-http mono-xsp4 mono-xsp4-base mono-runtime
$ command -v xsp4
/usr/bin/xsp4

Compare the versions with your distribution's package records and its official bug tracker or documentation. Do not copy a random Mono assembly into /usr/lib, downgrade libraries by hand, or run the server as root: that can damage package ownership and widen the impact of a broken local viewer.

6. Stop cleanly and recover

For a normally running instance, go back to its terminal and press Ctrl-C. If you lost that terminal, identify the process before stopping anything:

$ pgrep -af 'xsp4.*usr/share/monodoc/web'
12345 xsp4 --root /usr/share/monodoc/web --port 23456 --address 127.0.0.1

The PID and port are examples. If the command is yours and you want to end that temporary viewer, use the reported PID:

$ kill 12345
$ ss -ltnp | grep ':23456 ' || echo 'viewer stopped'
viewer stopped

Warning: this stops that one viewer and does not touch MonoDoc data, but never kill a process solely because its port looks familiar. Confirm the full command line first, and if a process refuses to exit, look at its parent and state before escalating to kill -9.

Done means

Confirmed the installed package version and wrapper path.
Know the wrapper picks a temporary port and binds XSP to loopback.
Opened the printed URL, or tested it with curl.
Kept the foreground terminal running until the viewer was no longer needed.
Can separate a browser or port problem from an XSP assembly failure.
Stopped the temporary process without touching package files or exposing the viewer to the network.