Docs for deployment to Fly.io (#68)

* add watch pkg to examples/fly/Dockerfile

* add some annotations to fly.io example config.toml

* add draft deploy-on-fly.io doc

* add deploy-on-fly link to SUMMARY.md

* commit before moving into user guide

* interstitial commit

* getting reoriented

* docs words, links

* my fancy trick did not outwit the vagaries of COPY

* launch on fly.io and testing database is up to date

* add a page on using flyctl proxy to run CLI locally

* try a title

* add links to Fly.io docs

* fix a title in a few places

* rename a doc file

doc/SUMMARY.md

@@ -16,6 +16,10 @@
 - [Telemetry](telemetry/README.md)
     - [Prometheus](telemetry/prometheus.md)
 - [Templates]() (to come)
+- [Deploy on Fly.io](deploy-on-fly/README.md)
+  - [Launch a Corrosion Cluster](deploy-on-fly/launch.md)
+  - [Work with cluster data on Fly.io](deploy-on-fly/explore.md)
+  - [Run Corrosion commands on a remote node](deploy-on-fly/local-remote.md)
 
 # Reference
 - [API](api/README.md)

doc/deploy-on-fly/README.md

@@ -0,0 +1,11 @@
+# Deploy on Fly.io
+
+The [Corrosion repository](https://github.com/superfly/corrosion) on GitHub includes example files to deploy Fly Machines running Corrosion in a cluster, communicating via [Fly private networking](https://fly.io/docs/reference/private-networking/).
+
+- [Launch a Corrosion cluster](./launch.md)
+- [Work with cluster data on Fly.io](./explore.md)
+- [Run Corrosion commands on a remote node](./local-remote.md)
+
+Corrosion is designed to run on the same node as any program that uses it. On Fly.io, that means deploying from a Docker image that runs both your code and Corrosion.
+
+It's also possible for your other Machines on the same Fly private network to read from and write to their nearest Corrosion node via [API](../api/). This can be handy for occasional or development use.

doc/deploy-on-fly/explore.md

@@ -0,0 +1,154 @@
+# Work with cluster data on Fly.io
+
+With your Corrosion cluster deployed, you can work with the example database.
+
+To get started, shell into each Corrosion node, in separate terminals. 
+
+```
+fly ssh console --pty --app <your-app-name> --select
+```
+
+If you run the command from the directory containing your Corrosion app's `fly.toml` configuration file, you can omit the `--app` flag. 
+
+We'll call one Machine "Node A" and the other "Node B". Every node is read-write, so it doesn't matter which is which.
+
+The example schema, `todo.sql`, specifies a single table called `todos`, with `id`, `title`, and `completed_at` columns.
+
+```sql
+-- /etc/corrosion/schemas/todo.sql
+
+CREATE TABLE todos (
+    id BLOB NOT NULL PRIMARY KEY,
+    title TEXT NOT NULL DEFAULT '',
+    completed_at INTEGER
+);
+```
+
+## Inserting and querying data
+
+### Insert some data on Node A
+
+From Node A's terminal session:
+
+```bash
+# corrosion exec --param 'some-id' --param 'Write some Corrosion docs!' 'INSERT INTO todos (id, title) VALUES (?, ?)'
+INFO corrosion: Rows affected: 1
+```
+### Query data on Node A
+
+Via SQLite directly:
+
+```plain
+# sqlite3 /var/lib/corrosion/state.db 'SELECT * FROM todos;'
+some-id|Write some Corrosion docs!|
+```
+
+Using the API, via the CLI:
+
+```bash
+# corrosion query 'SELECT * FROM todos;' --columns
+id|title|completed_at
+some-id|Write some Corrosion docs!|
+```
+
+### Query data on Node B
+
+From Node B's terminal:
+
+```bash
+# corrosion query 'SELECT * FROM todos;' --columns
+id|title|completed_at
+some-id|Write some Corrosion docs!|
+```
+Node A's contribution is already present in Node B's database.
+
+### Insert data on Node B
+
+```bash
+# corrosion exec --param 'some-id-2' --param 'Show how broadcasts work' 'INSERT INTO todos (id, title) VALUES (?, ?)'
+INFO corrosion: Rows affected: 1
+```
+
+### Check the data in Node A's database
+
+
+```
+# corrosion query 'SELECT * FROM todos;' --columns
+id|title|completed_at
+some-id|Write some Corrosion docs!|
+some-id-2|Show how broadcasts work|
+``` 
+
+The second update has propagated back to Node A.
+
+## Updating a file using a Corrosion template
+
+The example template `todos.rhai` makes a checklist out of the rows in our `todos` table.
+
+```js
+/* /etc/corrosion/templates/todos.rhai */
+
+<% for todo in sql("SELECT title, completed_at FROM todos") { %>
+[<% if todo.completed_at.is_null() { %> <% } else { %>X<% } %>] <%= todo.title %>
+<% } %>
+```
+
+### Start `corrosion template` and watch the output file
+
+On Node A, start processing the template.
+
+```
+# corrosion template "/etc/corrosion/templates/todos.rhai:todos.txt" &
+[1] 354
+root@4d8964eb9d9487:/#  INFO corrosion::command::tpl: Watching and rendering /etc/corrosion/templates/todos.rhai to todos.txt
+```
+Whenever there's an update to the results of the template's query (or queries), `corrosion template` re-renders the output file.
+
+Start watching the output file.
+
+```
+# watch -n 0.5 cat todos.txt
+Every 0.5s: cat todos.txt
+
+[ ] Write some Corrosion docs!
+[ ] Show how broadcasts work
+```
+
+### Add a todo item
+
+On the other Machine (Node B), insert some data.
+
+```
+# corrosion exec --param 'some-id-3' --param 'Hello from a template!' 'INSERT INTO todos (id, title) VALUES (?, ?)'
+INFO corrosion: Rows affected: 1
+```
+
+The new todo item gets propagated back to Node A, and your watch should look like this:
+
+```
+Every 0.5s: cat todos.txt
+
+[ ] Write some Corrosion docs!
+[ ] Show how broadcasts work
+[ ] Hello from a template!
+```
+
+### Mark all items as done
+
+Mark all tasks as completed, on either node:
+
+```
+# corrosion exec 'UPDATE todos SET completed_at = 1234567890'
+INFO corrosion: Rows affected: 3
+```
+
+```
+$ watch -n 0.5 cat todos.txt
+Every 0.5s: cat todos.txt
+
+[X] Write some Corrosion docs!
+[X] Show how broadcasts work
+[X] Hello from a template!
+```
+
+Now you have a distributed to-do list app! A front end is left as an exercise for the reader ;)