Updates to contribution guide (#222)

Co-authored-by: Andres Cruz <[email protected]>

CONTRIBUTING.md

@@ -47,6 +47,96 @@ In addition, Opik relies on:
 2. MySQL: Used to store metadata associated with projects, datasets, experiments, etc.
 3. Redis: Used for caching
 
+### Configuring your development environment
+
+#### Pre-requisites
+In order to run the development environment, you will need to have the following tools installed:
+
+* Docker - https://docs.docker.com/engine/install/
+
+* kubectl - https://kubernetes.io/docs/tasks/tools/#kubectl
+
+* Helm - https://helm.sh/docs/intro/install/
+
+* minikube - https://minikube.sigs.k8s.io/docs/start
+
+* More tools:
+    * **`bash`** completion / `zsh` completion
+    * `kubectx` and `kubens` - easy switch context/namespaces for kubectl -  https://github.com/ahmetb/kubectx
+
+#### Setting up the environment
+
+The local development environment is based on minikube. Once you have minikube installed, you can run it using:
+
+```bash
+minikube start
+```
+
+You can then run Opik and it's dependencies (Clickhouse, Redis, MySQL, etc) using:
+
+```bash
+./build_and_run.sh
+```
+
+This script supports the following options:
+```
+--no-build          Skip the build process
+--no-fe-build       Skip the FE build process
+--no-helm-update    Skip helm repo update
+--local-fe          Run FE locally (For frontend developers)
+--help              Display help message
+```
+
+> [!NOTE]
+> The first time you run the `build_and_run` script, it can take a few minutes to install everything.
+
+To check the application is running, you can access the FE using: `http://localhost:5173`
+
+#### Advanced usage
+
+*Connecting to Clickhouse*
+You can run the `clickhouse-client` with:
+```bash
+kubectl exec -it chi-opik-clickhouse-cluster-0-0-0 clickhouse-client
+```
+
+After the client is connected, you can check the databases with 
+```bash
+show databases;
+```
+
+*Minikube commands*
+
+List the pods that are running
+```bash
+kubectl get pods
+```
+To restart a pod just delete the pod, k8s will start a new one
+```bash
+kubectl delete pod <pod name>
+```
+There is no clean way to delete the databases, so if you need to do that, it's better to delete the namespace and then install again.
+Run 
+```bash
+kubectl delete namespace opik 
+```
+and in parallel (in another terminal window/tab) run 
+```bash
+kubectl patch chi opik-clickhouse --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]'
+```
+after the namespace is deleted, run 
+```bash
+./build_and_run.sh --no-build
+```
+to install everything again
+
+Stop minikube
+```bash
+minikube stop
+```
+Next time you will start the minikube, it will run everything with the same configuration and data you had before.
+
+
 ### Contributing to the documentation
 
 The documentation is made up of three main parts:
@@ -267,6 +357,8 @@ npm run typecheck
 
 ### Contributing to the backend
 
+#### Running the backend
+
 The Opik backend is a Java application that is located in `apps/opik-backend`.
 
 In order to run the backend locally, you need to have `java` and `maven` installed. Once installed, you can run the backend locally using the following command:
@@ -277,7 +369,7 @@ cd apps/opik-backend
 # Build the Opik application
 mvn clean install
 
-# Run the Opik application - 
+# Start the Opik application
 java -jar target/opik-backend-{project.pom.version}.jar server config.yml
 ```
 Replace `{project.pom.version}` with the version of the project in the pom file. 
@@ -291,3 +383,21 @@ cd apps/opik-backend
 
 mvn test
 ```
+
+#### Advanced usage
+
+*Run migrations*
+
+In order to run DB migrations, you will need to run:
+* Check pending migrations `java -jar target/opik-backend-{project.pom.version}.jar {database} status config.yml`
+* Run migrations `java -jar target/opik-backend-{project.pom.version}.jar {database} migrate config.yml`
+* Create schema tag `java -jar target/opik-backend-{project.pom.version}.jar {database} tag config.yml {tag_name}`
+* Rollback migrations `java -jar target/opik-backend-{project.pom.version}.jar {database} rollback config.yml --count 1` OR `java -jar target/opik-backend-{project.pom.version}.jar {database} rollback config.yml --tag {tag_name}`
+
+Replace `{project.pom.version}` with the version of the project in the pom file. Replace `{database}` with db for MySQL migrations and with `dbAnalytics` for ClickHouse migrations.
+
+*Accessing Clickhouse*
+
+You can curl the ClickHouse REST endpoint with `echo 'SELECT version()' | curl -H 'X-ClickHouse-User: opik' -H 'X-ClickHouse-Key: opik' 'http://localhost:8123/' -d @-`.
+
+Sample result: `23.8.15.35`