From dfd57b477867e3ffa9a4510b2d133d1410ad4c52 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sebastian=20Kurf=C3=BCrst?=
 <sebastian.kurfuerst@sandstorm.de>
Date: Fri, 19 Aug 2022 20:14:43 +0200
Subject: [PATCH] docs: improve development getting started (#453)

---
 README.md              |  2 ++
 docker-compose.yml     |  2 ++
 frontend/README_DEV.md | 44 +++++++++++++++++++++++++++++++++++++++---
 3 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index af5872f2f2..8584f9a753 100644
--- a/README.md
+++ b/README.md
@@ -243,6 +243,8 @@ with hot-code reloading.
 
 ### Backend + Frontend
 
+See the [./frontend/README_DEV.md](./frontend/README_DEV.md) file for all running options.
+
 1. Create a Postgres Database for Windmill and create an admin role inside your
    Postgres setup.
 2. Install [nsjail](https://github.com/google/nsjail) and have it accessible in
diff --git a/docker-compose.yml b/docker-compose.yml
index 300f147af3..79950c62ec 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -9,6 +9,8 @@ services:
       - db_data:/var/lib/postgresql/data
     ports:
       - 5432:5432
+      # NOTE: if port 5432 are already in use locally, we'll also bind another port
+      - 5433:5432
     environment:
       POSTGRES_PASSWORD: ${DB_PASSWORD}
       POSTGRES_DB: windmill
diff --git a/frontend/README_DEV.md b/frontend/README_DEV.md
index f724717a66..4dafd664d0 100644
--- a/frontend/README_DEV.md
+++ b/frontend/README_DEV.md
@@ -1,5 +1,7 @@
 # Developing
 
+## Starting the Development Server
+
 Once you've created a project and installed dependencies with `npm install` (or
 `pnpm install` or `yarn`), start a development server:
 
@@ -20,18 +22,54 @@ docker-compose up db server
 
 ### 2. Backend is run by cargo
 
-In the backend folder:
+**Prerequisites**
+
+- Install Rust [as explained on the website](https://www.rust-lang.org/tools/install).
+- Install llvm 
+
+  **on OSX:**
+  ```bash
+  brew install llvm caddy gsed
+  
+  # make LLVM tools available on PATH
+  echo 'export PATH="/opt/homebrew/opt/llvm/bin:$PATH"' >> ~/.zshrc
+  
+  # now, restart your shell. You should now have the `lld` binary on your PATH.
+  ```
+  
+**Do a Frontend Build**
+
+In order to run the backend, you need to have a frontend build inside `frontend/build/`.
+
+Otherwise, `cargo run` will break.
+
+So, in the frontend folder, run:
 
 ```bash
-cargo run
+# !!! on OSX, you are not allowed to use the system SED, but you need to use GNU SED.
+# !!! thus, in `frontend/package.json`, replace all `sed` occurences with `gsed`.
+
+# prerequisite for build
+npm run generate-backend-client
+
+npm run build
+# now, you'll have a `frontend/build` folder.
 ```
 
-In the root folder
+In the root folder:
 
 ```bash
 docker-compose up db
 ```
 
+In the backend folder:
+
+```bash
+DATABASE_URL=postgres://postgres:changeme@127.0.0.1:5433/windmill?sslmode=disable cargo run
+```
+
+You can now access [http://127.0.0.1:8000](http://127.0.0.1:8000).
+
 ### In both cases
 
 In the frontend folder: