Merge pull request #109 from ceruleandeep/main

Move multi-user documentation to own page

.editorconfig

@@ -5,7 +5,7 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.{md, yml}]
+[*.{md,yml}]
 charset = utf-8
 indent_style = space
 indent_size = 4

.gitignore

@@ -1,2 +1,3 @@
 .DS_Store
 .vscode
+/.idea

Administration/index.md

@@ -0,0 +1,58 @@
+---
+order: 25
+icon: gear
+expanded: true
+---
+
+# Administration
+
+!!! warning
+
+Despite following many security best practices, the SillyTavern server is not secure enough for public internet exposure.
+
+**NEVER HOST ANY INSTANCES TO THE OPEN INTERNET WITHOUT ENSURING PROPER SECURITY MEASURES FIRST.**
+
+**WE ARE NOT RESPONSIBLE FOR ANY DAMAGE OR LOSSES IN CASES OF UNAUTHORIZED ACCESS DUE TO IMPROPER OR INADEQUATE SECURITY IMPLEMENTATION.**
+!!!
+
+:::callout
+**[Multi-user](multi-user)**
+
+To share your SillyTavern instance with others, you can create multiple user accounts. Each user has their own settings, extensions, and data. User accounts can also be password-protected.
+:::
+
+:::callout
+**[Remote access](remote-connections)**
+
+You can access your SillyTavern instance from your phone, tablet, or another computer.
+:::
+
+
+:::callout
+**[VPNs and Tunneling](tunneling.md)**
+
+To access your SillyTavern instance from the internet, you can use a VPN or a tunneling service like Cloudflare Zero Trust, ngrok, or Tailscale.
+:::
+
+:::callout
+**[Reverse proxying](reverse-proxying)**
+
+For enthusiasts, you can set up a reverse proxy to access your SillyTavern instance from the internet.
+:::
+
+
+
+## Security checklist
+
+**This is just a recommendation. Please consult a web application security specialist before making your ST instance live.**
+
+1. Keep your operating system and runtime software like Node.js updated. This will ensure that your system is up-to-date with the latest security patches and fixes which can help prevent potential vulnerabilities.
+2. Use a whitelist and a network firewall. Only allow trusted IP ranges to access the server.
+3. Enable basic authentication. It acts as a "master password" before you can proceed to the front-end app.
+4. Alternatively, configure external authentication. Some known services for that are [Authelia](https://www.authelia.com/) and [authentik](https://goauthentik.io/). See more in the [SSO guide](sso.md).
+5. Never leave admin accounts passwordless. A server will warn you upon the startup if you have any unprotected admin accounts.
+6. Use the discreet login setting outside of the local network. This will hide the user list from any potential outsiders.
+7. Check the access logs often. They are written to the server console and the `access.log` file and provide information on incoming connections, such as IP address and user agent.
+8. Configure HTTPS. For a localhost server, you can generate and use a self-signed certificate. Otherwise, you may need to deploy a proxying web server like [Traefik](https://traefik.io/) or [Caddy](https://caddyserver.com/docs/getting-started).
+
+Find more on secure proxying in the following guide: [Reverse Proxying SillyTavern](reverse-proxying).

Administration/multi-user.md

@@ -0,0 +1,72 @@
+---
+title: Multi-user mode
+icon: people
+order: -10
+---
+
+Multi-user mode allows several people to use one SillyTavern server. Each user has their own settings, extensions, and data. User accounts can also be password-protected.
+
+## Configuration
+
+To enable and use the multi-user mode, edit the `config.yaml` file:
+
+```yaml
+# Enable multi-user mode
+enableUserAccounts: true
+# Enable discreet login mode: hides user list on the login screen
+enableDiscreetLogin: true
+```
+
+1. When the user account setting is disabled, a `default-user` fallback admin account is utilized for storing the user data.
+2. When the discreet login setting is disabled, a list of active users is displayed on the login screen. If enabled, a user must enter their handle manually.
+
+> You can't _delete_ the `default-user` account from the users list because it is used for serving the user data in case if `enableUserAccounts` is set to `false`. But you can _disable_ it to hide it from the list and disallow logins.
+
+## User handles
+
+A handle is the unique identifier of a user. It can consist only of lowercase letters, numbers, and dashes.
+
+A path to the user data directory assumes using the following pattern: `%DATA_ROOT%/%USER_HANDLE%`.
+
+Examples of valid user handles:
+
+-   default-user
+-   juan555
+-   flux-the-cat
+-   cool-guy1337
+
+## Roles
+
+-   **Admin** - can manage (create, delete, modify) other users.
+-   **User** - can't manage other users.
+
+Except for having admin panel access, both user roles are functionally identical and can use a full range of SillyTavern features without any restrictions. An implementation of user permissions is TBD.
+
+All user accounts are created as regular users first, and then could be promoted to admins if needed.
+
+### Login screen
+
+There you can select a user account to use. Has two styles, depending on the `enableDiscreetLogin` config value.
+
+The login screen is bypassed and not displayed when you have only one active user and it is not password protected.
+
+### User profile
+
+You can access an account self-management menu using an "Account" button under the "User settings" panel in the top menu bar.
+
+1. Display name - used in the login screen, can be changed. Does not correlate with personas and is not visible for the AI APIs - you can still use as many personas as you want.
+2. Profile picture - used in the login screen. You can either use a custom picture, the default persona picture (if set), or the last used persona otherwise.
+3. Password - a lock icon reflects the account protection status (open lock = no password). A password can be set, changed, or removed using the "Change Password" button.
+4. Settings Snapshots - access and review the backups of your `settings.json` file, with the ability to create or restore snapshots.
+5. Download Backup - download an archive of your user data folder.
+6. Reset Settings - reset factory default settings, while leaving other data (character, chats) intact.
+
+## Password recovery
+
+1. A password can be recovered from a login screen. You need access to the server console to get a one-time recovery code (consisting of 4 digits).
+2. Alternatively, you can use a utility script in the SillyTavern server to reset a password by providing the user handle.
+
+```txt
+Usage: node recover.js [account] (password)
+Example: node recover.js admin SecurePassword
+```

Administration/remote-connections.md

@@ -0,0 +1,161 @@
+---
+icon: rss
+order: -30
+route: /usage/remoteconnections
+---
+
+# Remote connections
+
+Most often this is for people who want to use SillyTavern on their mobile phones while their PC runs the ST server within the same WiFi network.
+
+It is also the first step for allowing remote connections from outside the local network.
+
+!!! warning
+You should not use port forwarding to expose your ST server to the internet. Instead, use a VPN or a tunneling service like Cloudflare Zero Trust, ngrok, or Tailscale. See the [VPN and Tunneling](tunneling.md) guide for more information.
+!!!
+
+!!! danger Disclaimer
+**NEVER HOST ANY INSTANCES TO THE OPEN INTERNET WITHOUT ENSURING PROPER SECURITY MEASURES FIRST.**
+
+**WE ARE NOT RESPONSIBLE FOR ANY DAMAGE OR LOSSES IN CASES OF UNAUTHORIZED ACCESS DUE TO IMPROPER OR INADEQUATE SECURITY IMPLEMENTATION.**
+!!!
+
+## Allowing remote connections
+
+By default, ST server only accepts local connections. In order to allow remote connections, set the parameter `listen` within `config.yaml` to `true`:
+```yaml
+# Listen for incoming connections
+listen: true
+```
+
+## Access control
+
+After activating the remote connection listening, you must turn on at least one access control method, or ST server will refuse to start.
+
+### Access control by whitelist
+
+* Create a new text file inside your SillyTavern base install folder called `whitelist.txt`.
+* Open the file in a text editor, add a list of IPs you want to be allowed to connect.
+  * Each IP must be on its own line.
+  * **127.0.0.1 MUST be included in the list, or you will not be able to connect on the host machine**
+  * Individual IPs, and wildcard (*) IP ranges are accepted.
+  * CIDR masks are also accepted (eg. 10.0.0.0/24).
+* Save the `whitelist.txt` file.
+* **Restart your SillyTavern server.**
+
+#### Example `whitelist.txt` files
+
+1. Allows any device on the local network to connect:
+
+    ```txt
+    10.0.0.0/8
+    172.16.0.0/12
+    192.168.0.0/16
+    127.0.0.1
+    ::1
+    ```
+
+    If you are not sure what addresses your local network uses, use the whitelist above. 
+
+2. Allows two specific devices to connect:
+
+    ```txt
+    192.168.0.2
+    192.168.0.5
+    127.0.0.1
+    ```
+
+3. Allows any device on the 192.168.0.* subnet to connect:
+
+    ```txt
+    192.168.0.*
+    127.0.0.1
+    ```
+
+!!! `config.yaml` also has a `whitelist` array, which you can use in the same way, but this array will be ignored if `whitelist.txt` exists. We do not recommend using the `config.yaml` IP list, because using `whitelist.txt` is easier.
+!!!
+
+!!! Removing access control by whitelist
+Change `whitelistMode` to `false`, remove (or rename) `whitelist.txt` in the SillyTavern base install folder, and restart the server.
+!!!
+
+### Access control by HTTP Basic Authentication
+
+The server will ask for username and password whenever a client connects via HTTP. **This only works if the Remote connections (listen: true) are enabled.**
+
+To enable HTTP BA, Open `config.yaml` in the SillyTavern base directory and search for `basicAuthMode` Set basicAuthMode to true and set username and password. Note: `config.yaml` will only exist if ST has been executed before at least once.
+```yaml
+basicAuthMode: true
+basicAuthUser:
+  username: "MyUsername"
+  password: "MyPassword"
+```
+
+Alternatively you can enable basic auth as follows:
+
+```yaml
+basicAuthMode: true
+enableUserAccounts: true
+perUserBasicAuth: true
+```
+
+In this `perUserBasicAuth` mode the basic auth's username and password will be the same as any valid multi user account that has a password. Additionally SillyTavern will login directly to that account. **Ensure you have an account with a password prior to enabling `perUserBasicAuth`.**
+
+Save the file and restart SillyTavern if it was already running. You should be prompted for username and password when connecting to your ST. Both username and password are transmitted in plain text. If you are concerned about this, you can serve ST via HTTPS.
+
+## Connecting to your SillyTavern instance
+
+### Getting the IP address for the ST host machine
+
+After the whitelist has been setup, you'll need the IP of the ST-hosting device.
+
+If the ST-hosting device is on the same wifi network, you will use the ST-host's internal wifi IP:
+
+* For Windows: windows button > type `cmd.exe` in the search bar > type `ipconfig` in the console, hit Enter > look for `IPv4` listing.
+
+If you (or someone else) wants to connect to your hosted ST while not being on the same network, you will need the public IP of your ST-hosting device.
+
+* While using the ST-hosting device, access [this page](https://whatismyipaddress.com/) and look for for `IPv4`. This is what you would use to connect from the remote device.
+
+### Connecting to the ST server
+
+Whatever IP you ended up with for your situation, you will put that IP address and port number into the remote device's web browser.
+
+A typical address for an ST host on the same wifi network would look like:
+
+`http://192.168.0.5:8000`
+
+Use http:// NOT https://
+
+### Troubleshooting
+
+Still unable to connect?
+
+* Enable the Private Network profile type in Settings > Network and Internet > Ethernet. This is VERY important for Windows 11, otherwise, you would be unable to connect even with the aforementioned firewall rules.
+* On Windows, the application may be blocked by the application firewall. The quickest way to fix this is to uninstall and reinstall node.js, and when prompted by the firewall, allow it to access the network. Otherwise, you will need to manually allow the node.js application through the Windows application firewall.
+* On Linux, you may need to allow the port through the firewall. The command to do this is `sudo ufw allow 8000`. This will allow traffic on port 8000.
+
+Do not modify the port forwarding settings on your router. This is not necessary for accessing ST within your local network, and can expose your server to the internet.
+
+## HTTPS
+
+### Start SillyTavern with TLS/SSL
+
+To encrypt traffic from and to your ST instance, start the server with the `--ssl` flag.
+
+Example:
+```
+node server.js --ssl
+```
+As per default, ST will search for your certificates inside the `certs` folder. If your files are located elsewhere, you can use the `--keyPath` and `--certPath` arguments.
+
+Example:
+```
+node server.js --ssl --keyPath /home/user/certificates/privkey.pem --certPath /home/user/certificates/cert.pem
+```
+
+The user you're running SillyTavern with requires read permissions on the certificate files.
+
+### How to get a certificate
+
+The simplest, quickest way to get a certificate is by using [certbot](https://letsencrypt.org/getting-started/).