144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
# Contributing
|
|
|
|
This project is completely open source and welcomes any and all open source
|
|
contributions. The workflow for contributing is to make a fork of the
|
|
repository. You can claim an issue in the issues tab or start a new thread to
|
|
indicate a feature or bug fix you are working on.
|
|
|
|
Once you have finished your contribution make a PR , and it will be reviewed by
|
|
a project manager. Feel free to join us in our
|
|
[discord](http://discord.gg/plasticlabs) to discuss your changes or get help.
|
|
|
|
Your changes will undergo a period of testing and discussion before finally
|
|
being entered into the `main` branch and being staged for release
|
|
|
|
## Local Development
|
|
|
|
Below is a guide on setting up a local environment for running the Honcho
|
|
Server.
|
|
|
|
> This guide was made using a M1 Macbook Pro. For any compatibility issues
|
|
> on different platforms please raise an Issue.
|
|
|
|
### Prerequisites and Dependencies
|
|
|
|
Honcho is developed using [python](https://www.python.org/) and [poetry](https://python-poetry.org/).
|
|
|
|
The minimum python version is `3.9`
|
|
The minimum poetry version is `1.4.1`
|
|
|
|
### Setup
|
|
|
|
Once the dependencies are installed on the system run the following steps to get
|
|
the local project setup.
|
|
|
|
1. Clone the repository
|
|
|
|
```bash
|
|
git clone https://github.com/plastic-labs/honcho.git
|
|
```
|
|
|
|
2. Enter the repository and install the python dependencies
|
|
|
|
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`
|
|
|
|
Putting this together:
|
|
|
|
```bash
|
|
cd honcho
|
|
poetry shell
|
|
poetry install
|
|
```
|
|
|
|
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`
|
|
|
|
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
|
|
USE_AUTH_SERVICE=false
|
|
OPENTELEMETRY_ENABLED=false
|
|
SENTRY_ENABLED=false
|
|
```
|
|
|
|
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
|
|
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.
|
|
|
|
### 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.
|
|
|
|
The docker-compose template is set to use an environment file called `.env`.
|
|
You can also copy the `.env.template` and fill with the appropriate values.
|
|
|
|
Copy the template and update the appropriate environment variables before
|
|
launching the service.
|
|
|
|
```bash
|
|
cd honcho/api
|
|
cp .env.template .env
|
|
# update the file with openai key and other wanted environment variables
|
|
cp docker-compose.yml.example docker-compose.yml
|
|
docker compose up
|
|
```
|
|
|
|
### 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`.
|
|
|
|
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:
|
|
|
|
```bash
|
|
cd honcho/api
|
|
flyctl launch --no-deploy # Follow the prompts and edit as you see fit
|
|
cat .env | flyctl secrets import # Load in your secrets
|
|
flyctl deploy # Deploy with appropriate environment variables
|
|
```
|
|
|