docs/install: update instructions

INSTALL.md

@@ -3,7 +3,7 @@ distributions are different, the steps stay roughly the same.
 
 #### Installing hard dependencies
 
-```bash
+```console
 user@host:~$ sudo pacman -S postgres
 user@host:~$ sudo pacman -S python
 user@host:~$ sudo pacman -S python-pip
@@ -12,11 +12,13 @@ user@host:~$ python --version
 Python 3.5.1
 ```
 
+
+
 #### Setting up a database
 
 First, basic `postgres` configuration:
 
-```bash
+```console
 user@host:~$ sudo -i -u postgres initdb --locale en_US.UTF-8 -E UTF8 -D /var/lib/postgres/data
 user@host:~$ sudo systemctl start postgresql
 user@host:~$ sudo systemctl enable postgresql
@@ -24,7 +26,7 @@ user@host:~$ sudo systemctl enable postgresql
 
 Then creating a database:
 
-```bash
+```console
 user@host:~$ sudo -i -u postgres createuser --interactive
 Enter name of role to add: szuru
 Shall the new role be a superuser? (y/n) n
@@ -34,23 +36,22 @@ user@host:~$ sudo -i -u postgres createdb szuru
 user@host:~$ sudo -i -u postgres psql -c "ALTER USER szuru PASSWORD 'dog';"
 ```
 
-#### Installing `szurubooru's` dependencies
 
-```bash
+
+#### Installing soft dependencies
+
+```console
 user@host:path/to/szurubooru$ sudo pip install -r requirements.txt # installs backend deps
 user@host:path/to/szurubooru$ npm install # installs frontend deps
 ```
 
-#### Preparing `szurubooru` for first use
 
-```bash
-user@host:path/to/szurubooru$ npm run build # compiles frontend
-user@host:path/to/szurubooru$ alembic update head  # runs all DB upgrades
-```
 
-Time to configure things:
+#### Preparing `szurubooru` for first run
 
-```bash
+Configure things:
+
+```console
 user@host:path/to/szurubooru$ cp config.ini.dist config.ini
 user@host:path/to/szurubooru$ vim config.ini
 ```
@@ -58,13 +59,20 @@ user@host:path/to/szurubooru$ vim config.ini
 Pay extra attention to the `[database]` and `[smtp]` sections, and API URL in
 `[basic]`.
 
-### Upgrading the database
+Then update the database and compile the frontend:
 
-    [user@host:path/to/szurubooru] alembic upgrade HEAD
+```console
+user@host:path/to/szurubooru$ alembic update head # runs all DB upgrades
+user@host:path/to/szurubooru$ npm run build # compiles frontend
+```
 
-Alembic should have been installed during installation of `szurubooru`'s
+`alembic` should have been installed during installation of `szurubooru`'s
 dependencies.
 
+It is recommended to rebuild the frontend after each change to configuration.
+
+
+
 ### Wiring `szurubooru` to the web server
 
 `szurubooru` is divided into two parts: public static files, and the API. It
@@ -75,7 +83,7 @@ Below are described the methods to integrate the API into a web server:
 
 1. Run API locally with `waitress`, and bind it with a reverse proxy. In this
    approach, the user needs to install `waitress` with `pip install waitress`
-   and then start `szurubooru` with `./bin/szurubooru` (see `--help` for
+   and then start `szurubooru` with `./scripts/host-waitress` (see `--help` for
    details). Then the user needs to add a virtual host that delegates the API
    requests to the local API server, and the browser requests to the `public/`
    directory.
@@ -85,3 +93,35 @@ Below are described the methods to integrate the API into a web server:
 
 Note that the API URL in the virtual host configuration needs to be the same as
 the one in the `config.ini`, so that client knows how to access the backend!
+
+#### Example
+
+**nginx configuration** - wiring API `http://great.dude/api/` to
+`localhost:6666` to avoid fiddling with CORS:
+
+```nginx
+server {
+    listen 80;
+    server_name great.dude;
+
+    location = /api {
+        return 302 /api/;
+    }
+    location ~ ^/api(/?)(.*)$ {
+        proxy_pass http://127.0.0.1:6666/$2$is_args$args;
+    }
+    location / {
+        root /home/rr-/src/maintained/szurubooru/public;
+        try_files $uri /index.htm;
+    }
+}
+```
+
+**`config.ini`**:
+
+```ini
+[basic]
+api_url = http://big.dude/api/
+```
+
+Then the backend is started with `./scripts/host-waitress`.