Better documentation of --host, closes #574

simonw · Nov 1, 2019 · ffae2f0 · ffae2f0
1 parent 7152e76
commit ffae2f0
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 14 deletions.
diff --git a/README.md b/README.md
@@ -89,26 +89,31 @@ Now visiting http://localhost:8001/History/downloads will show you a web interfa
 
 ## datasette serve options
 
-    $ datasette serve --help
-
     Usage: datasette serve [OPTIONS] [FILES]...
 
       Serve up specified SQLite database files with a web UI
 
     Options:
       -i, --immutable PATH      Database files to open in immutable mode
-      -h, --host TEXT           host for server, defaults to 127.0.0.1
-      -p, --port INTEGER        port for server, defaults to 8001
+      -h, --host TEXT           Host for server. Defaults to 127.0.0.1 which means
+                                only connections from the local machine will be
+                                allowed. Use 0.0.0.0 to listen to all IPs and
+                                allow access from other machines.
+      -p, --port INTEGER        Port for server, defaults to 8001
       --debug                   Enable debug mode - useful for development
-      --reload                  Automatically reload if database or code change detected -
-                                useful for development
-      --cors                    Enable CORS by serving Access-Control-Allow-Origin: *
+      --reload                  Automatically reload if database or code change
+                                detected - useful for development
+      --cors                    Enable CORS by serving Access-Control-Allow-
+                                Origin: *
       --load-extension PATH     Path to a SQLite extension to load
-      --inspect-file TEXT       Path to JSON file created using "datasette inspect"
-      -m, --metadata FILENAME   Path to JSON file containing license/source metadata
+      --inspect-file TEXT       Path to JSON file created using "datasette
+                                inspect"
+      -m, --metadata FILENAME   Path to JSON file containing license/source
+                                metadata
       --template-dir DIRECTORY  Path to directory containing custom templates
       --plugins-dir DIRECTORY   Path to directory containing custom plugins
-      --static STATIC MOUNT     mountpoint:path-to-directory for serving static files
+      --static STATIC MOUNT     mountpoint:path-to-directory for serving static
+                                files
       --memory                  Make :memory: database available
       --config CONFIG           Set config option using configname:value
                                 datasette.readthedocs.io/en/latest/config.html

diff --git a/datasette/cli.py b/datasette/cli.py
@@ -230,9 +230,16 @@ def package(
     multiple=True,
 )
 @click.option(
-    "-h", "--host", default="127.0.0.1", help="host for server, defaults to 127.0.0.1"
+    "-h",
+    "--host",
+    default="127.0.0.1",
+    help=(
+        "Host for server. Defaults to 127.0.0.1 which means only connections "
+        "from the local machine will be allowed. Use 0.0.0.0 to listen to "
+        "all IPs and allow access from other machines."
+    ),
 )
-@click.option("-p", "--port", default=8001, help="port for server, defaults to 8001")
+@click.option("-p", "--port", default=8001, help="Port for server, defaults to 8001")
 @click.option(
     "--debug", is_flag=True, help="Enable debug mode - useful for development"
 )

diff --git a/docs/datasette-serve-help.txt b/docs/datasette-serve-help.txt
@@ -6,8 +6,11 @@ Usage: datasette serve [OPTIONS] [FILES]...
 
 Options:
   -i, --immutable PATH      Database files to open in immutable mode
-  -h, --host TEXT           host for server, defaults to 127.0.0.1
-  -p, --port INTEGER        port for server, defaults to 8001
+  -h, --host TEXT           Host for server. Defaults to 127.0.0.1 which means only
+                            connections from the local machine will be allowed. Use
+                            0.0.0.0 to listen to all IPs and allow access from other
+                            machines.
+  -p, --port INTEGER        Port for server, defaults to 8001
   --debug                   Enable debug mode - useful for development
   --reload                  Automatically reload if database or code change detected -
                             useful for development