From df7c79fa8f5e8769a2582e502ae429075fe37ef4 Mon Sep 17 00:00:00 2001
From: Rolf Neugebauer <rolf.neugebauer@docker.com>
Date: Mon, 7 Aug 2017 20:11:17 +0100
Subject: [PATCH] docs: Update packet documentation

Signed-off-by: Rolf Neugebauer <rolf.neugebauer@docker.com>
---
 docs/platform-packet.md | 101 +++++++++++++++++++++++-----------------
 1 file changed, 59 insertions(+), 42 deletions(-)

diff --git a/docs/platform-packet.md b/docs/platform-packet.md
index 32943ff71..a00d3f8bb 100644
--- a/docs/platform-packet.md
+++ b/docs/platform-packet.md
@@ -18,64 +18,81 @@ is a work in progress.
 [Type 1]:https://www.packet.net/bare-metal/servers/type-1/
 [Type 2A]:https://www.packet.net/bare-metal/servers/type-2a/
 
+The `linuxkit run packet` command can mostly either be configured via
+command line options or with environment variables. see `linuxkit run
+packet --help` for the options and environment variables.
+
 ## Boot
 
-Build an image with `moby build`. The [packet.yml](https://github.com/vielmetti/linuxkit/blob/master/examples/packet.yml)
-example file provides a suitable template to start from.
 
-Linuxkit on Packet [boots via iPXE]. This requires that you have
-an HTTP server on which you can store your images. At the moment
-there is no equivalent to "linuxkit push" to upload these images,
-so you will have to host them yourself. The images can be served
-from any HTTP server, though in the interest of performance you may
-want to locate those images near the data center that you're booting in.
 
-[boots via iPXE]:https://help.packet.net/technical/infrastructure/custom-ipxe
+LinuxKit on Packet boots the `kernel+initrd` output from moby
+via
+[iPXE](https://help.packet.net/technical/infrastructure/custom-ipxe). iPXE
+booting requires a HTTP server on which you can store your images. At
+the moment there is no builtin support for this, although we are
+working on this too.
 
-Servers take several minutes to provision. During this time their
-state can be seen from the Packet console.
+A simple way to host files is via a simple local http server written in Go, e.g.:
 
+```Go
+package main
+
+import (
+	"log"
+	"net/http"
+)
+
+func main() {
+	// Simple static webserver:
+	log.Fatal(http.ListenAndServe(":8080", http.FileServer(http.Dir("."))))
+}
 ```
-$ linuxkit run packet --help
-USAGE: linuxkit run packet [options] [name]
 
-Options:
+and then `go run` this in the directory with the `kernel+initrd`.
+
+The web server must be accessible from Packet. You can either run the
+server on another Packet machine, or use tools
+like [ngrok](https://ngrok.com/) to make it accessible via a reverse
+proxy.
+
+You then specify the location of your http server using the
+`-base-url` command line option. For example, to boot the
+toplevel [linuxkit.yml](../linuxkit.yml) example:
+
+```sh
+moby build linuxkit.yml
+# run the web server
+# run 'ngrok http 8080' in another window
+PACKET_API_KEY=<API key> linuxkit run packet -base-url http://9b828514.ngrok.io -project-id <Project ID> linuxkit
+```
+
+**Note**: It may take several minutes to deploy a new server. If you
+are attached to the console, you should see the BIOS and the boot
+messages.
+
 
-  -api-key string
-    	Packet API key
-  -base-url string
-    	Base URL that the kernel and initrd are served from.
-  -hostname string
-    	Hostname of new instance (default "moby")
-  -img-name string
-    	Overrides the prefix used to identify the files. Defaults to [name]
-  -machine string
-    	Packet Machine Type (default "baremetal_0")
-  -project-id string
-    	Packet Project ID
-  -zone string
-    	Packet Zone (default "ams1")
- ```
 ## Console
 
-If your LinuxKit system does not include an ssh or remote console 
-application, you can still connect to it via the Packet SOS ("Serial over SSH")
-console. See https://help.packet.net/technical/networking/sos-rescue-mode
-for details on that mode.
+By default, `linuxkit run packet ...` will connect to the
+Packet
+[SOS ("Serial over SSH") console](https://help.packet.net/technical/networking/sos-rescue-mode). This
+requires `ssh` access, i.e., you must have uploaded your SSH keys to
+Packet beforehand.
+
+**Note**: We also require that the Packet SOS host is in your
+`known_hosts` file, otherwise the connection to the console will
+fail. There is a Packet SOS host per zone.
+
+You can disable the serial console access with the `-console=false`
+command line option.
+
 
 ## Disks
 
 At this moment the Linuxkit server boots from RAM, with no persistent
-storage and there is no code that mounts disks. As a result,
-when the Linuxkit image reboots, all is lost. 
+storage.  We are working on adding persistent storage support on Packet.
 
-Packet supports a [persistent iPXE] mode through its API
-which would allow a server to come back up after a reboot
-and re-start the PXE process. This is great for testing your
-provisioning scripts. This is not yet available directly
-through Linuxkit.
-
-[persistent iPXE]:https://help.packet.net/technical/infrastructure/custom-ipxe
 
 ## Networking