From e0aef077837e2648ca92bd6402d3c54334ddd0fb Mon Sep 17 00:00:00 2001
From: Leo Vasanko <leo@git>
Date: Mon, 13 Nov 2023 14:45:05 -0800
Subject: [PATCH] Update README

---
 README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 59 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 09f9e01..1cc9208 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,23 @@
 # Web File Storage
 
-Run directly from repository with Hatch (or use pip install as usual):
-
-```sh
-hatch run cista -l :3000 /path/to/files
-```
-
-Settings incl. these arguments are stored to config file on the first startup and later `hatch run cista` is sufficient. If the `cista` script is missing, consider `pip install -e .` (within `hatch shell`) or some other trickery (known issue with installs made prior to adding the startup script).
+The Python package installs a `cista` executable. Use `hatch shell` to initiate and install in a virtual environment, or `pip install` it on your system. Alternatively `hatch run cista` may be used to skip the shell step but stay virtual. `pip install hatch` first if needed.
 
 Create your user account:
 
 ```sh
-hatch run cista --user admin --privileged
+cista --user admin --privileged
 ```
 
+## Running the server
+
+Serve your files on localhost:8000:
+
+```sh
+cista -l :8000 /path/to/files
+```
+
+The Git repository does not contain a frontend build, so you should first do that...
+
 ## Build frontend
 
 Frontend needs to be built before using and after any frontend changes:
@@ -25,3 +29,50 @@ npm run build
 ```
 
 This will place the front in `cista/wwwroot` from where the backend server delivers it, and that also gets included in the Python package built via `hatch build`.
+
+## Development setup
+
+For rapid turnaround during development, you should run `npm run dev` Vite development server on the Vue frontend. While that is running, start the backend on another terminal `hatch run cista --dev -l :8000` and connect to the frontend.
+
+The backend and the frontend will each reload automatically at any code or config changes.
+
+## System deployment
+
+Clone the repository to `/srv/cista/cista-storage` or other suitable location accessible to the storage user account you plan to use. `sudo -u storage -s` and build the frontend if you hadn't already.
+
+Create **/etc/systemd/system/cista@.service**:
+
+```ini
+[Unit]
+Description=Cista storage %i
+
+[Service]
+User=storage
+WorkingDirectory=/srv/cista/cista-storage
+ExecStart=hatch run cista -c /srv/cista/%i -l /srv/cista/%i/socket /media/storage/@%i/
+TimeoutStopSec=2
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+```
+
+This assumes you may want to run multiple separate storages, each having their files under `/media/storage/<domain>` and configuration under `/srv/cista/<domain>/`. Instead of numeric ports, we use UNIX sockets for convenience.
+
+```sh
+systemctl daemon-reload
+systemctl enable --now cista@foo.example.com
+systemctl enable --now cista@bar.example.com
+```
+
+Exposing this publicly online is the most convenient using the [Caddy](https://caddyserver.com/) web server but you can of course use Nginx or others as well. Or even run the server with `-l domain.example.com` given TLS certificates in the config folder.
+
+**/etc/caddy/Caddyfile**:
+
+```Caddyfile
+foo.example.com, bar.example.com {
+    reverse_proxy unix//srv/cista/{host}/socket
+}
+```
+
+Using the `{host}` placeholder we can just put all the domains on the same block. That's the full server configuration you need. `systemctl enable --now caddy` or `systemctl restart caddy` for the config to take effect.