From 1f62b53da25e6fe55883674d143e03bf7261d6a8 Mon Sep 17 00:00:00 2001
From: Alex Gleason <alex@alexgleason.me>
Date: Mon, 18 Jul 2022 12:16:11 -0500
Subject: [PATCH] Docs: update docs sections from README

---
 docs/development/how-it-works.md    | 18 +++++++++++++++++-
 docs/development/live-backend.md    | 20 --------------------
 docs/development/running-locally.md | 12 +++++++++---
 3 files changed, 26 insertions(+), 24 deletions(-)
 delete mode 100644 docs/development/live-backend.md

diff --git a/docs/development/how-it-works.md b/docs/development/how-it-works.md
index d0fa66f01..e5c4c7bc4 100644
--- a/docs/development/how-it-works.md
+++ b/docs/development/how-it-works.md
@@ -5,4 +5,20 @@ Soapbox FE is a [single-page application (SPA)](https://en.wikipedia.org/wiki/Si
 It has a single HTML file, `index.html`, responsible only for loading the required JavaScript and CSS.
 It interacts with the backend through [XMLHttpRequest (XHR)](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest).
 
-It incorporates much of the [Mastodon API](https://docs.joinmastodon.org/methods/) used by Pleroma and Mastodon, but requires many [Pleroma-specific features](https://docs-develop.pleroma.social/backend/API/differences_in_mastoapi_responses/) in order to function.
+Here is a simplified example with Nginx:
+
+```nginx
+location /api {
+  proxy_pass http://backend;
+}
+
+location / {
+  root /opt/soapbox;
+  try_files $uri index.html;
+}
+```
+
+(See [`mastodon.conf`](https://gitlab.com/soapbox-pub/soapbox-fe/-/blob/develop/installation/mastodon.conf) for a full example.)
+
+Soapbox incorporates much of the [Mastodon API](https://docs.joinmastodon.org/methods/), [Pleroma API](https://api.pleroma.social/), and more.
+It detects features supported by the backend to provide the right experience for the backend.
diff --git a/docs/development/live-backend.md b/docs/development/live-backend.md
deleted file mode 100644
index 1857324db..000000000
--- a/docs/development/live-backend.md
+++ /dev/null
@@ -1,20 +0,0 @@
-# Developing against a live backend
-
-You can also run Soapbox FE locally with a live production server as the backend.
-
-> **Note:** Whether or not this works depends on your production server. It does not seem to work with Cloudflare or VanwaNet.
-
-To do so, just copy the env file:
-
-```
-cp .env.example .env
-```
-
-And edit `.env`, setting the configuration like this:
-
-```
-BACKEND_URL="https://pleroma.example.com"
-PROXY_HTTPS_INSECURE=true
-```
-
-You will need to restart the local development server for the changes to take effect.
diff --git a/docs/development/running-locally.md b/docs/development/running-locally.md
index 8a8c655b2..d11c59396 100644
--- a/docs/development/running-locally.md
+++ b/docs/development/running-locally.md
@@ -23,16 +23,22 @@ yarn dev
 
 It will serve at `http://localhost:3036` by default.
 
-It will proxy requests to the backend for you.
-For Pleroma running on `localhost:4000` (the default) no other changes are required, just start a local Pleroma server and it should begin working.
+You should see an input box - just enter the domain name of your instance to log in.
+
+Tip: you can even enter a local instance like `http://localhost:3000`!
 
 ## Troubleshooting: `ERROR: NODE_ENV must be set`
 
 Create a `.env` file if you haven't already.
 
-```
+```sh
 cp .env.example .env
 ```
 
 And ensure that it contains `NODE_ENV=development`.
 Try again.
+
+## Troubleshooting: it's not working!
+
+Run `node -V` and compare your Node.js version with the version in [`.tool-versions`](https://gitlab.com/soapbox-pub/soapbox-fe/-/blob/develop/.tool-versions).
+If they don't match, try installing [asdf](https://asdf-vm.com/).