chore: Instructions for Livebook (#18)

README.md

@@ -11,9 +11,9 @@
 
 To start your Phoenix server:
 
-  * Run `mix setup` to install and setup dependencies
-  * Run `mix build_code_vectors` to download the ICD-9 codelist, precompute vectors, and store the results in the database.
-  * Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
+- Run `mix setup` to install and setup dependencies
+- Run `mix build_code_vectors` to download the ICD-9 codelist, precompute vectors, and store the results in the database.
+- Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
 
 Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
 
@@ -26,29 +26,43 @@ The app is configured to deploy to Fly.io via a `fly.toml` file. To deploy, run
 ### Precomputing code vectors
 
 To build the code vectors for the ICD-9 codelist for the deployed environment:
+
 1. Connect to the server with `fly ssh console`.
 2. Run `/app/bin/medical_transcription eval MedicalTranscription.Release.precompute_code_vectors`. This will prepare the vectors in the database if they are not present.
 
+### Livebook
+
+In addition to connecting to a the deployed application via `iex`, Livebook supports connecting to the running application. Connecting a Livebook instance to the deployed application involves the following:
+
+1. Install and setup Wireguard with a peer connection for Fly.io: [Step by Step](https://fly.io/docs/networking/private-networking/#install-your-wireguard-app)
+2. Install and start Livebook: [Livebook.dev](https://livebook.dev/)
+3. [Connecting Livebook to a Production App](https://fly.io/docs/elixir/advanced-guides/connect-livebook-to-your-app/) requires a node name and cookie value:
+
+- Node name: `medical-transcription-cpu@myipfromfly` ("myipfromfly" can be retrieved with `fly ips private --app medical-transcription-cpu`)
+- Cookie value: `0gfxcPtwryKxI2O1N0eFAg9p4MJGC-oUGShgj_wgvNEGiba5EDEJFA==` (this value is set in `fly.toml`)
 
 ## Run in Docker
 
 1. Create a local volume: `docker volume create ml-data`
 2. Ensure the volume is writeable: `docker run --rm -v ml-data:/data busybox /bin/sh -c 'touch /data/.initialized && chmod 1777 /data'`. More background:
-  - What the initial `1` for `chmod` means: https://www.linuxnix.com/sticky-bit-set-linux/
-  - How to update the permissions of a mounted volume: https://serverfault.com/a/984599
+
+- What the initial `1` for `chmod` means: <https://www.linuxnix.com/sticky-bit-set-linux/>
+- How to update the permissions of a mounted volume: <https://serverfault.com/a/984599>
+
 3. Build the image with: `docker build . -t headwayio/medical_transcription`
 4. Run a container with: `docker run --env-file ./.env -p 4000:4000 headwayio/medical_transcription`
 
 ### Caveats
 
 You may need to make a few changes to get the app running in Docker at the moment:
+
 - In `lib/medical_transcription/application.ex`, comment out the `DNSCluster` child spec.
 - In `rel/env.sh.eex`, comment out the `ERL_AFLAGS`, `RELEASE_DISTRIBUTION`, and `RELEASE_NODE` environment variables.
 
 ## Learn more
 
-  * Official website: https://www.phoenixframework.org/
-  * Guides: https://hexdocs.pm/phoenix/overview.html
-  * Docs: https://hexdocs.pm/phoenix
-  * Forum: https://elixirforum.com/c/phoenix-forum
-  * Source: https://github.com/phoenixframework/phoenix
+- Official website: <https://www.phoenixframework.org/>
+- Guides: <https://hexdocs.pm/phoenix/overview.html>
+- Docs: <https://hexdocs.pm/phoenix>
+- Forum: <https://elixirforum.com/c/phoenix-forum>
+- Source: <https://github.com/phoenixframework/phoenix>