Fixes DEV-300

CONTRIBUTING.md

@@ -20,62 +20,113 @@ Server.
 > This guide was made using a M1 Macbook Pro. For any compatibility issues
 > on different platforms please raise an Issue.
 
-### Docker
+### Prerequisites and Dependencies
+
+Honcho is developed using [python](https://www.python.org/) and [poetry](https://python-poetry.org/).
+
+The minimum python version is `3.8.1`
+The minimum poetry version is `1.4.1`
+
+### Setup
 
-The API can be run using docker-compose. The `docker-compose.yml.example` file can be copied to `docker-compose.yml` and the environment variables can be set in the `.env` file.
+Once the dependencies are installed on the system run the following steps to get
+the local project setup. 
+
+1. Clone the repository
 
 ```bash
-cd honcho/api
-cp docker-compose.yml.example docker-compose.yml
-[ update the file with openai key and other wanted environment variables ]
-docker compose up -d
+git clone https://github.com/plastic-labs/honcho.git
 ```
 
-#### Manually
+2. Enter the repository and install the python dependencies
 
-The API can be run either by installing the necessary dependencies and then
-specifying the appropriate environment variables.
+We recommend using a virtual environment to isolate the dependencies for Honcho
+from other projects on the same system. With `poetry` a virtual environment can
+be generated using the `poetry shell` command. Once the virtual environment is
+created and activated install the dependencies with `poetry install`
 
-1. Create a virtualenv and install the API's dependencies
+Putting this together:
 
 ```bash
-cd honcho/api/ # change to the api directory
-poetry shell # Activate virutal environment
-poetry install # install dependencies
+cd honcho
+poetry shell
+poetry install
 ```
 
-2. Copy the `.env.template` file and specify the type of database and
-   connection_uri. For testing sqlite is fine. The below example uses an
-   in-memory sqlite database.
+3. Set up a database
+
+Honcho utilized [Postgres](https://www.postgresql.org/) for its database with 
+pgvector. An easy way to get started with a postgresdb is to create a project
+with [Supabase](https://supabase.com/)
+
+A `docker-compose` template is also available with a database configuration
+available. 
+
+4. Edit the environment variables. 
+
+Honcho uses a `.env` file for managing runtime environment variables. A
+`.env.template` file is included for convenience. Several of the configurations
+are not required and are only necessary for additional logging, monitoring, and
+security.
+
+Below are the required configurations
+
+```env
+CONNECTION_URI= # Connection uri for a postgres database
+OPENAI_API_KEY= # API Key for OpenAI used for insights
+```
+> Note that the `CONNECTION_URI` must have the prefix `postgresql+psycopg` to
+> function properly. This is a requirement brought by `sqlalchemy`
 
-> Honcho has been tested with Postgresql and PGVector
+The template has the additional functionality disabled by default. To ensure
+that they are disabled you can verify the following environment variables are
+set to false. 
 
 ```env
-DATABASE_TYPE=postgres
-CONNECTION_URI=postgresql://testuser:testpwd@localhost:5432/honcho
+USE_AUTH_SERVICE=false
+OPENTELEMETRY_ENABLED=false
+SENTRY_ENABLED=false
 ```
 
-3. launch a postgresd with pgvector enabled with docker-compose
+5. Launch the API
+
+With the dependencies installed, a database setup and enabled with `pgvector`,
+and the environment variables setup you can now launch a local instance of
+Honcho. The following command will launch the storage API for Honcho
 
 ```bash
-cd honcho/api/local
-docker-compose up -d
+python -m uvicorn src.main:app --reload --port 8000
 ```
+This is a development server that will reload whenever code is changed. When
+first launching the API with a connection the database it will provision the
+necessary tables for Honcho to operate.
 
-4. Run the API via uvicorn
+### Docker
+
+As mentioned earlier a `docker-compose` template is included for running Honcho.
+As an alternative to running Honcho locally it can also be run with the compose
+template. 
+
+Copy the template and update the appropriate environment variables before
+launching the service.
 
 ```bash
-cd honcho/api # change to the api directory
-poetry shell # Activate virtual environment if not already enabled
-python -m uvicorn src.main:app --reload
+cd honcho/api
+cp docker-compose.yml.example docker-compose.yml
+[ update the file with openai key and other wanted environment variables ]
+docker compose up
 ```
 
-#### Deploy on Fly
+### Deploy on Fly
 
 The API can also be deployed on fly.io. Follow the [Fly.io
 Docs](https://fly.io/docs/getting-started/) to setup your environment and the
 `flyctl`.
-`flyctl`.
+
+A sample `fly.toml` is included for convenience.
+
+> Note. The fly.toml does not include launching a Postgres database. This must
+> be configured separately
 
 Once `flyctl` is set up use the following commands to launch the application:
 
@@ -86,6 +137,3 @@ cat .env | flyctl secrets import # Load in your secrets
 flyctl deploy # Deploy with appropriate environment variables
 ```
 
-
-## Self-Hosting 
-