JWEBSERVER(1)

💅 JWEBSERVER(1) — like, the jwebserver glow-up guide

okay bestie, so this one lives in the JDK Commands corner of the manpage universe, and it's literally the manual for jwebserver — the little command that spins up the Java Simple Web Server. she's minimal, she's cute, she serves static files and nothing else. let's get into it 🎀

---

✨ NAME ✨

jwebserver — launch the Java Simple Web Server. that's it, that's the whole vibe. 🦋

✨ SYNOPSIS ✨

jwebserver [options]

options — the command-line options, obviously. for the full rundown of what each one does, scroll your little heart down to Options (iykyk). 💖

✨ DESCRIPTION ✨

okay so jwebserver gives you a minimal HTTP server — and when I say minimal I mean it was designed for prototyping, testing, and debugging, not for running your whole empire. it serves a single directory hierarchy, and it only serves static files. that's the whole menu.

and listen: only HTTP/1.1 is supported. HTTP/2 and HTTPS are not supported, periodt. no cap, don't come asking.

she only serves idempotent HEAD and GET requests. literally anything else gets hit with a 501 - Not Implemented or a 405 - Not Allowed response 🙈. and GET requests get mapped to the directory being served like this:

• if the requested resource is a file, its content is served.
• if the requested resource is a directory that contains an index file, the content of the index file is served.
• otherwise, the names of all files and subdirectories of the directory are listed. symbolic links and hidden files are not listed or served.

MIME types? configured automatically, bestie, using the built-in table. for example, .html files are served as text/html and .java files are served as text/plain. iconic behaviour tbh.

jwebserver is located in the jdk.httpserver module, and can alternatively be started with java -m jdk.httpserver. it's based on the web server implementation in the com.sun.net.httpserver package. and the com.sun.net.httpserver.SimpleFileServer class provides a programmatic way to retrieve the server and its components for reuse and extension — so if you wanna build on her, you absolutely can, main character energy. 👑

✨ USAGE ✨

jwebserver [-b bind address] [-p port] [-d directory]
           [-o none|info|verbose] [-h to show options]
           [-version to show version information]

✨ OPTIONS ✨

• -h or -? or --help — prints the help message and exits. the classic "wait what do I type" move.
• -b addr or --bind-address addr — specifies the address to bind to. default: 127.0.0.1 or ::1 (loopback). for all interfaces use -b 0.0.0.0 or -b ::.
• -d dir or --directory dir — specifies the directory to serve. default: current directory. 🍓
• -o level or --output level — specifies the output format. none | info | verbose. default: info.
• -p port or --port port — specifies the port to listen on. default: 8000.
• -version or --version — prints the version information and exits.

to stop the server, press Ctrl + C. 💀 rude but effective.

✨ STARTING THE SERVER ✨

the following command starts the Simple Web Server:

$ jwebserver

if startup is successful, the server prints a message to System.out listing the local address and the absolute path of the directory being served. for example:

$ jwebserver
Binding to loopback by default. For all interfaces use "-b 0.0.0.0" or "-b ::".
Serving /cwd and subdirectories on 127.0.0.1 port 8000
URL http://127.0.0.1:8000/

look at her go 😭💖 so tidy.

✨ CONFIGURATION ✨

by default, the server runs in the foreground and binds to the loopback address and port 8000. this can be changed with the -b and -p options. for example, to bind the Simple Web Server to all interfaces, use:

$ jwebserver -b 0.0.0.0
Serving /cwd and subdirectories on 0.0.0.0 (all interfaces) port 8000
URL http://123.456.7.891:8000/

⚠️ note that this makes the web server accessible to all hosts on the network. do not do this unless you are sure the server cannot leak any sensitive information. like, fr fr, this is the part where you read the whole sentence before hitting enter. 🫶

as another example, use the following command to run on port 9000:

$ jwebserver -p 9000

by default, the files of the current directory are served. a different directory can be specified with the -d option. 📁

by default, every request is logged on the console. the output looks like this:

127.0.0.1 - - [10/Feb/2021:14:34:11 +0000] "GET /some/subdirectory/ HTTP/1.1" 200 -

logging output can be changed with the -o option. the default setting is info. the verbose setting additionally includes the request and response headers as well as the absolute path of the requested resource. highkey the move when you're debugging and need the full tea. 🍵

✨ STOPPING THE SERVER ✨

once started successfully, the server runs until it is stopped. on Unix platforms, the server can be stopped by sending it a SIGINT signal (Ctrl+C in a terminal window). simple as. ✨

✨ HELP OPTION ✨

the -h option displays a help message describing the usage and the options of the jwebserver. when in doubt, -h it out. 💅

---

and that's the whole page, bestie — JDK 23, dated 2024, from the JDK Commands manual, JWEBSERVER(1). slay, go serve some static files responsibly 🌈💜