diff --git a/.gitignore b/.gitignore index bc612c52a6b..0cf8f5864b1 100644 --- a/.gitignore +++ b/.gitignore @@ -36,6 +36,7 @@ dist/ **/android/app/google-services.json **/android/app/src/dev/google-services.json **/android/app/src/prod/google-services.json +**/android/app/.cxx/ # iOS specific **/ios/**/Pods/ diff --git a/backend/README.md b/backend/README.md index d0d72d6e836..16f04dcb38e 100644 --- a/backend/README.md +++ b/backend/README.md @@ -1,39 +1,115 @@ -# Setup -1. Install the google-cloud-sdk `brew install google-cloud-sdk` or if you use nix envdir, it should be installed for you - -2. You will need to have your own Google Cloud Project (please refer to the [App Docs]([url](https://docs.omi.me/docs/developer/AppSetup#7-setup-firebase)) on how to setup Firebase). If you did setup Firebase for the App, then you'll already have a Project in Google Cloud. - Make sure you have the `Cloud Resource Manager` and `Firebase Management API` permissions at the minimum in the [Google Cloud API Console](https://console.cloud.google.com/apis/dashboard) -3. Run the following commands one by one - ``` - gcloud auth login - gcloud config set project - gcloud auth application-default login --project - ``` - Replace `` with your Google Cloud Project ID - This should generate the `application_default_credentials.json` file in the `~/.config/gcloud` directory. This file is read automatically by gcloud in Python, so you don’t have to manually add any env for the service account. -5. Install Python (use brew if on mac) (or with nix env it will be done for you) -6. Install `pip` (if it doesn’t exist) -7. Install `git `and `ffmpeg` (use brew if on mac) (again nix env installs this for you) -8. Move to the backend directory (`cd backend`) -9. Run the command `cat .env.template > .env` -10. For Redis (you can use [upstash](https://upstash.com/), sign up and create a free instance) -11. Add the necessary keys in the env file (OpenAI, Deepgram, Redis, set ADMIN_KEY to 123) -12. Run the command `pip install -r requirements.txt` to install required dependencies -13. Sign Up on [ngrok](https://ngrok.com/) and follow the steps to configure it -14. During the onboarding flow, under the `Static Domain` section, Ngrok should provide you with a static domain and a command to point your localhost to that static domain. Replace the port from 80 to 8000 in that command and run it in your terminal - ``` - ngrok http --domain=example.ngrok-free.app 8000 - ``` -15. Run the following command to start the server - ``` - uvicorn main:app --reload --env-file .env - ``` -16. If you get any error mentioning `no internet connection or something while downloading models`, then add the following lines in the `utils/stt/vad.py` file after the import statements. - ``` - import ssl - ssl._create_default_https_context = ssl._create_unverified_context - ``` -17. Now try running the `uvicorn main:app --reload --env-file .env` command again. -18. Assign the url given by ngrok in the app’s env to `API_BASE_URL` -19. Now your app should be using your local backend +# Omi Backend Setup +This README provides a quick setup guide for the Omi backend. For a comprehensive step-by-step guide with detailed explanations, please refer to the [Backend Setup Documentation](https://docs.omi.me/docs/developer/backend/Backend_Setup). + +## Quick Setup Steps + +1. Install the google-cloud-sdk + - Mac: `brew install google-cloud-sdk` + - Windows: `choco install gcloudsdk` + - Nix envdir: It should be pre-installed + +2. You will need to have your own Google Cloud Project with Firebase enabled. If you've already set up Firebase for the Omi app, you're good to go. If not, please refer to the [Firebase Setup Guide](https://firebase.google.com/docs/projects/learn-more). + - **IMPORTANT:** Make sure you have the [`Cloud Resource Manager API`](https://console.cloud.google.com/apis/library/cloudresourcemanager.googleapis.com), [`Firebase Management API`](https://console.cloud.google.com/apis/library/firebase.googleapis.com), and [`Cloud Firestore API`](https://console.developers.google.com/apis/api/firestore.googleapis.com/overview) enabled in the [Google Cloud API Console](https://console.cloud.google.com/apis/dashboard) **before proceeding to the next steps**. Failure to enable these APIs will result in authentication errors. + +3. Run the following commands one by one to authenticate with Google Cloud: + ```bash + gcloud auth login + gcloud config set project + gcloud auth application-default login --project + ``` + Replace `` with your Google Cloud Project ID. + This should generate the `application_default_credentials.json` file in the `~/.config/gcloud` directory. This file is read automatically by gcloud in Python. + +4. Install Python + - Mac: `brew install python` + - Windows: `choco install python` + - Nix envdir: It should be pre-installed + +5. Install `pip` if it doesn't exist (follow instructions on [pip installation page](https://pip.pypa.io/en/stable/installation/)) + +6. Install `git` and `ffmpeg` + - Mac: `brew install git ffmpeg` + - Windows: `choco install git.install ffmpeg` + - Nix envdir: These should be pre-installed + +7. Install `opus` (required for audio processing) + - Mac: `brew install opus` + - Windows: You should already have it if you're on Windows 10 version 1903 and above + +8. Move to the backend directory: `cd backend` + +9. Create your environment file: `cp .env.template .env` + +10. Set up Redis + - [Upstash](https://console.upstash.com/) is recommended - sign up and create a free instance + +11. Add the necessary API keys in the `.env` file: + - [OpenAI API Key](https://platform.openai.com/settings/organization/api-keys) + - [Deepgram API Key](https://console.deepgram.com/api-keys) + - Redis credentials from your [Upstash Console](https://console.upstash.com/) + - Set `ADMIN_KEY` to a temporary value (e.g., `123`) for local development + - **IMPORTANT:** For Pinecone vector database: + - Make sure to set `PINECONE_INDEX_NAME` to the name of your Pinecone index + - If you don't have a Pinecone index yet, [create one in the Pinecone Console](https://app.pinecone.io/) + - The index should be created with the appropriate dimension setting (e.g., 1536 for OpenAI embeddings) + +12. Install Python dependencies (choose one of the following approaches): + + **Option A: Using a virtual environment (recommended)** + ```bash + # Create a virtual environment + python -m venv venv + + # Activate the virtual environment + # On Windows: + venv\Scripts\activate + # On macOS/Linux: + source venv/bin/activate + + # Install dependencies within the virtual environment + pip install -r requirements.txt + ``` + You should see `(venv)` at the beginning of your command prompt when the virtual environment is active. + + **Option B: Direct installation** + ```bash + # Install dependencies globally + pip install -r requirements.txt + ``` + +13. Sign up on [ngrok](https://ngrok.com/) and follow the steps to configure it + - During onboarding, get your authentication token and run `ngrok config add-authtoken ` + +14. During the onboarding flow, under the `Static Domain` section, Ngrok should provide you with a static domain and a command to point your localhost to that static domain. Replace the port from 80 to 8000 in that command and run it in your terminal: + ```bash + ngrok http --domain=example.ngrok-free.app 8000 + ``` + +15. Start the backend server: + ```bash + uvicorn main:app --reload --env-file .env + ``` + +16. Troubleshooting: If you get any error mentioning "no internet connection" while downloading models, add the following lines in the `utils/stt/vad.py` file after the import statements: + ```python + import ssl + ssl._create_default_https_context = ssl._create_unverified_context + ``` + +17. Now try running the server again: `uvicorn main:app --reload --env-file .env` + +18. In your Omi app's environment, set `API_BASE_URL` to the URL provided by ngrok (e.g., `https://example.ngrok-free.app`) + +19. Your app should now be using your local backend + +20. If you used a virtual environment, when you're done, deactivate it by running: + ```bash + deactivate + ``` + +## Additional Resources + +- [Full Backend Setup Documentation](https://docs.omi.me/developer/backend/Backend_Setup) +- [Omi Documentation](https://docs.omi.me/) +- [Community Support](https://discord.gg/omi) diff --git a/docs/docs/developer/backend/Backend_Setup.mdx b/docs/docs/developer/backend/Backend_Setup.mdx index 81ef6130bf5..d77e4af58f0 100644 --- a/docs/docs/developer/backend/Backend_Setup.mdx +++ b/docs/docs/developer/backend/Backend_Setup.mdx @@ -54,6 +54,15 @@ Before you start, make sure you have the following: gcloud auth application-default login --project ``` - This process generates an `application_default_credentials.json` file in the `~/.config/gcloud` directory. This file is used for automatic authentication with Google Cloud services in Python. + - Copy the credentials file to your backend directory and rename it: + ```bash + # For macOS/Linux: + cp ~/.config/gcloud/application_default_credentials.json ./google-credentials.json + + # For Windows: + copy %APPDATA%\gcloud\application_default_credentials.json google-credentials.json + ``` + ## II. Backend Setup πŸ› οΈ @@ -129,11 +138,35 @@ Before you start, make sure you have the following: - **NO_SOCKET_TIMEOUT: (Optional)** Set to `True` to disable the socket timeout for the backend server (socket will stay connected for as long as the app is open) - **Other API Keys:** Fill in any other API keys required by your integrations (e.g., [Google Maps API key](https://console.cloud.google.com/google/maps-apis/credentials)) -5. **Install Python Dependencies: πŸ“š** - - In your terminal (inside the backend directory), run: - ```bash - pip install -r requirements.txt - ``` +6. **Install Python Dependencies: πŸ“š** + You have two options for installing the required Python packages: + + **Option A: Using a Virtual Environment (Recommended) 🐍** + - It's recommended to use a virtual environment to isolate your project dependencies and avoid conflicts + - Create a new virtual environment in the backend directory: + ```bash + # Create a new virtual environment + python -m venv venv + + # Activate the virtual environment + # On Windows: + venv\Scripts\activate + # On macOS/Linux: + source venv/bin/activate + ``` + - You should see `(venv)` at the beginning of your command prompt, indicating that the virtual environment is active + - Install dependencies within the virtual environment: + ```bash + pip install -r requirements.txt + ``` + - All packages will be installed isolated from your system's Python installation + + **Option B: Direct Installation** + - If you prefer not to use a virtual environment, you can install the dependencies directly: + ```bash + pip install -r requirements.txt + ``` + - Note that this approach may lead to conflicts with other Python projects on your system ## III. Running the Backend Locally πŸƒβ€β™‚οΈ @@ -174,6 +207,14 @@ Before you start, make sure you have the following: Now, your Omi app should be successfully connected to the locally running backend. +5. **When You're Done: πŸ›‘** + - If you used a virtual environment, when you're finished working with the backend, deactivate it by running: + ```bash + deactivate + ``` + - This command returns you to your system's global Python environment + - To reactivate the virtual environment later, just run the activation command again (`source venv/bin/activate` on macOS/Linux or `venv\Scripts\activate` on Windows) + ## Environment Variables πŸ” Here's a detailed explanation of each environment variable you need to define in your `.env` file: @@ -182,6 +223,9 @@ Here's a detailed explanation of each environment variable you need to define in - **`BUCKET_SPEECH_PROFILES`:** The name of the Google Cloud Storage bucket where user speech profiles are stored - **`BUCKET_BACKUPS`:** The name of the Google Cloud Storage bucket used for backups (if applicable) - **`GOOGLE_APPLICATION_CREDENTIALS`:** The path to your [Google Cloud service account credentials file](https://console.cloud.google.com/iam-admin/serviceaccounts) (`google-credentials.json`). This is generated in step 3 of **I. Setting Up Google Cloud & Firebase** + - By default, the backend expects to find a file named `google-credentials.json` in the same directory where the application is running + - If you've followed Option 1 in step 3 of the Google Cloud setup, this will be already set correctly + - If you prefer to use the default location of the credentials, set this to the full path of your `application_default_credentials.json` file (e.g., `~/.config/gcloud/application_default_credentials.json` on macOS/Linux or `%APPDATA%\gcloud\application_default_credentials.json` on Windows) - **`PINECONE_API_KEY`:** Your [Pinecone API key](https://app.pinecone.io/organizations/-/projects/-/api-keys), used for vector database operations. Storing Memory Embeddings: Each memory is converted into a numerical representation (embedding). Pinecone efficiently stores these embeddings and allows Omi to quickly find the most relevant memories related to a user's query - **`PINECONE_INDEX_NAME`:** The name of your Pinecone index where memory embeddings are stored - **`REDIS_DB_HOST`:** The host address of your Redis instance