From f7b2cba5a083d1e377f189445a8b41380d74031e Mon Sep 17 00:00:00 2001
From: Pablo Lamela <pablo.lamela@iohk.io>
Date: Thu, 10 Aug 2023 15:33:01 +0200
Subject: [PATCH] Extend README.md (#7)

Add more info to the README on how to run and troubleshoot Marlowe Runner
---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 44 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 583bdecc..3f74a26f 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,55 @@
-# marlowe-runner
+# Marlowe Runner
+
+A simple web app which allows you to deploy and progress through Marlowe contracts on Cardano easily from the browser.
 
 ## Installation
 
-* Nix:
-  ```shell
-  $ nix develop
-  ```
+### Prerequisites
 
-## CI
+Ensure you have `nix` installed on your system and an instance of the [Marlowe Runtime](https://docs.marlowe.iohk.io/docs/getting-started/deployment-options)'s Webserver running pointed to the desired Cardano network.
 
-* Testing:
-  ```shell
-  $ spago test
-  ```
+### Setup
 
-* Formatting:
-  ```shell
-  $ purs-tidy format-in-place 'src/**/*.purs'
-  ```
+Enter the development shell:
+```bash
+nix develop
+```
 
-## Staging server
+Install the necessary dependencies:
+```bash
+npm install
+```
 
-Start the server with
+Run the tests:
+```bash
+spago test
+```
 
+## Running
+
+To start the server you can use the `npm run start` command, for example:
+```bash
+NETWORK="preview" MARLOWE_WEB_SERVER_URL="http://localhost:3780" npm run start
 ```
-npm run start
+
+In the previous example:
+- `NETWORK`: Specifies the Cardano network to use. In the example above, it's set to `preview`.
+- `MARLOWE_WEB_SERVER_URL`: Specifies URL for the Marlowe Runtime Web server of the network specified (`NETWORK`).
+
+After this, the Marlowe Runner instance should be available by default at: `http://localhost:8080/`
+
+### Troubleshooting
+
+Ensure that:
+  -  The protocol (`http` or `https`) is correct.
+  -  There's no extra `/` at the end of the URL.
+
+If you get a blank page when opening Marlowe Runner in your browser, it may be necessary that you install a light wallet like [Nami](https://namiwallet.io/).
+
+## Contributing
+
+Before contributing, please format the source code using the following command from within the `nix` development shell:
+
+```bash
+purs-tidy --format-in-place src/**/*.purs
 ```