Webserver is a small Python script that wraps up the invocation of Docker to run a webserver in a container.

To use this script, you must have Docker and Python 3 installed.

Make sure you have all the prerequisites installed:

python -m pip install -r requirements.txt

Then you can run bin/webserver. You may wish to copy it to /usr/local/bin or ~/bin or somewhere on your path.

The first time you run the script, Docker will download the Apache webserver container. That should only happen once. You’ll need an internet connection for that.

If you just run webserver, it will attempt to start a new webserver on the default port (8125, unless you configure it differently) serving the current working directory.

If it succeeds, http://localhost:8125/ will show you the current directory in a browser.

If you don’t specify a port and there’s already a server on port 8125, it will try 8126, then 8127, etc. until it finds an open port. (Open port here means one that isn’t used by a webserver. If you have some other service running on the port selected, the attempt to start a container will fail.)

• Use --root PATH to change the root directory of the web server to PATH.
• Use --port INT to change the local port to INT.
• Use --start NAME to change the server name to NAME. If you don’t specify a name, Docker will generate a random name.

If you don’t remembe what servers are running, --list will list them.

You can stop a running server:

• Use --stop NAME to stop the server named NAME.
• Use --stop-all to stop all the webservers running. This will not stop any other containers.

The default behavior of the script is to let the webserver run in the background. If, instead, you’d like to watch the log messages on the server, start it with --foreground.

You can also look at the logs on any running server:

• Use --logs NAME to see the logs on the server named NAME.

If you combine --logs NAME and --foreground, you can watch the log messages on the named server.

In foreground mode, you have to abort the script with Ctrl-C to get your terminal back. This will not stop the server. Use one of the stop options to do that.

The --version option will show you the server version.

After using the script for a couple of weeks, I decided it would be handy if some servers always started on the same port, thus a configuration file was born.

The default configuration file is nwalsh/webserver.json in your XDG configuration directory, $XDG_CONFIG_HOME, or $HOME/.config if that environment variable isn’t set. (In other words, the default location is $HOME/.config/nwalsh/webserver.json.) You can load a different configuration file with --config.

The configuration file is an object with three properties:

default-port

The default server port (instead of 8125)

servers

A collection of web servers

container

An alternate container configuration

All are optional. Any other properties are ignored, but there’s no guarantee I won’t add more in the future.

The default-port property specifies the default port.

For example:

{
  "default-port": 8888
}

The servers property is a nested map defining the properties of each named server.

For example:

{
  "servers": {
    "demo": {
      "root": "/path/to/demo",
      "port": 8130
    }
}

This configuration defines a server named demo that will serve up the local directory /path/to/demo on port 8130. You can have as many servers as you like. Each server must specify a root and a port.

By default, webserver starts an Apache 2.4 server in a container. If you want to start a different container, configure it with container.

For example:

{
  "container": {
    "name": "nginx:mainline",
    "root": "/usr/share/nginx/html"
  }
}

This configuration will start the Nginx mainline server instead of Apache. The root property identifies the location inside the container where the server root directory should be mounted.

For what it’s worth, Nginx doesn’t have directory listings enabled by default, so it’s somewhat harder to use in an ad hoc manner.

Obviously, container could be generalized into a nested map like servers and it could support ports other than port 80. But not today.