Improves documentation for getting started and common setup issues

README.md

@@ -74,8 +74,12 @@ cd riverst
 - In `src/server/`, rename [`.env.example`](src/server/env.example) to `.env` and fill in the required API keys and configuration
 - In `src/client/react/`, rename [`.env.example`](src/client/react/env.example) to `.env` and fill in the required API keys and configuration
 
+More detailed instructions for setting up the [client](src/client/react/README.md) and [server](src/server/README.md) can be found in their respective README documents.
+
 **Note**: Not all API KEYS are strictly required. Only if you want to use a remote service, you need to expose the corresponding API KEY
 
+**Note**: If you want to run local models, you will need to have Ollama or another method for running models locally. Please see [#5 under Getting Started for the server setup](src/server/README.md#getting-started).
+
 ### 3. Run
 
 #### 3a. Run with Docker
@@ -84,7 +88,7 @@ cd riverst
 docker compose up --build
 ```
 
-#### 3b. Run manually in two different tabs of your terminal
+#### 3b. Run manually in two different tabs of your terminal (recommended)
 
 - **Start the server:**
   ```bash
@@ -106,6 +110,10 @@ docker compose up --build
 
 ℹ️ **Note 2:** For AWS EC2 deployment instructions, see [here](notes/first_steps_to_deploy.md).
 
+### 4. Run into issues?
+
+It's possible some issues might have arisen along the way. Feel free to post an issue asking for help as well as check out our [Common Pitfalls Guide](notes/common_pitfalls.md) for some issues that we have seen pop up.
+
 ---
 
 ## 🙏 Acknowledgments

notes/common_pitfalls.md

@@ -0,0 +1,45 @@
+# Common Pitfalls and Issues
+
+This document is meant to share some of the common pitfalls, issues, and errors that we have encountered while helping others set up Riverst on their local systems and some possible ways to go about solving them.
+
+## Google OAuth
+
+We have noticed that even when all of the setup for Google OAuth has been done perfectly (creation in the web console, .env configured properly, authorized users listed), OAuth still might not work. Some notes about Google OAuth:
+
+### It does not allow for connections without a DNS record (using IP addresses)
+
+You might encounter this after having run it locally without issue since it is fine with using localhost, but moving it onto a server or attempting cross-machine connections might fail. There is currently not a workaround beyond giving your server a domain. Doing so will also help with other security related issues that are addressed later.
+
+## Connecting Across Machines
+
+Perhaps when you first put Riverst onto a server or boot it up locally and create a session, you might want to test it on another device. Despite it running fine locally, issues might occur when first attempting cross machine connections.
+
+### Cannot find the dev machine/hosted site at all
+
+In the case that you can't find the Riverst site at all from another machine, there are a few checks you can make:
+
+- If you are using IP addresses, the machines likely need to be on the same local network, unless the IP address can be accessed from external networks.
+- The dev server is typically binding to your localhost, but to allow for external connections, one can use `npm run dev -- --host 0.0.0.0`
+
+## The site is reachable but the sessions are empty
+
+This might have occurred for a number of reasons. Make sure to check the server logs as well as the browser logs. A notable error that we have found is `crypto.randomUUID is not a function`. On the surface this might seem like a versioning issue, but it is actually because the crypto package requires a secure context. This can either be through `https://` URLs or using `http://localhost` (or similarly `http://127.0.0.1`) which might have been why initial tests worked but when doing cross machine connections, things failed.
+
+There are a few possible solutions for this. One is using ngrok or some other service to expose the local server over HTTPS. A quick workaround can also be to provide self-signed certificates. Any users will have to accept security warnings but this will allow cross machine connections.
+
+Go to `src/client/react/`, open `vite.config.ts` add the following to `server` section:
+```javascript
+https: {
+      key: fs.readFileSync('./cert/key.pem'),
+      cert: fs.readFileSync('./cert/cert.pem'),
+    }
+```
+
+You will also need to add `import fs from 'fs'` to the file imports.
+
+Within that same folder, run the following:
+
+```
+mkdir cert
+openssl req -x509 -newkey rsa:2048 -keyout cert/key.pem -out cert/cert.pem -days 365 -nodes
+```

src/server/README.md

@@ -19,8 +19,11 @@ pip install -r requirements.txt
    - Set your env variables (you can follow the instructions in the `.env.example` file)
 
 **Note**: Not all API KEYS are strictly required. Only if you want to use a remote service, you need to expose the corresponding API KEY
+
 **Note**: `.env` is gitignored for security
 
+**Note**: Using OpenAI for all of the services with a free user plan will likely cause a Pipecat 500 issue shortly after generating a session as OpenAI rate limits free users to 3 requests per minute, which the initial setup of the models alone might exceed.
+
 4. [Optional] If you want to use Google authentication (ENABLE_GOOGLE_AUTH is `true`), you need to set it up:
    - Copy `authorization/authorized_users.json.example` to `authorization/authorized_users.json`
    - Add authorized user email addresses to the JSON array