From 30a6d6723bedf5fe5ac81a55442982dfabb5bd4d Mon Sep 17 00:00:00 2001 From: johnymontana Date: Fri, 1 Nov 2024 12:55:19 -0600 Subject: [PATCH 1/5] Add instructions for working with Collections locally --- modus/search.mdx | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/modus/search.mdx b/modus/search.mdx index e80dfecc..bdf6a5e3 100644 --- a/modus/search.mdx +++ b/modus/search.mdx @@ -384,3 +384,45 @@ export function searchSimilarProducts( ``` + +## Local Development With Collections + +Data stored in Collections is persisted to a Postgres database. When using Collections in a Modus app deployed to the Hypermode platform this Postgres database is managed by Hypermode and no additional setup is required by the user. However, when developing with Modus locally or outside of the Hypermode platform a Postgres instance will need to be configured for the persistance layer. + +To start and configure a local Postgres instance for working with Collections locally using [Docker Compose](https://docs.docker.com/compose/) follow these steps: + +1. Clone the [Modus GitHub repository](https://github.com/hypermodeinc/modus): + +```sh +git clone https://github.com/hypermodeinc/modus.git +``` + +2. Start the Collections Postgres database using the local Docker Compose script: + +```sh +cd modus/runtime/tools/local +docker-compose up +``` + +3. Next, you will need to apply the database schema using the [golang-migrate](https://github.com/golang-migrate/migrate) utility. + +On MacOS, you can install this utility with the following: + +```sh +brew install golang-migrate +``` + +Then, you can apply the migration as follows: + +```sh +export POSTGRESQL_URL='postgresql://postgres:postgres@localhost:5433/my-runtime-db?sslmode=disable' +migrate -database ${POSTGRESQL_URL} -path ../../db/migrations up +``` + +4. Set the `MODUS_DB` environmet variable: + +```sh +export MODUS_DB=postgresql://postgres:postgres@localhost:5433/my-runtime-db?sslmode=disable +``` + +You can now use Collections locally in your Modus app. From 29bed233ac24dcd463d89b61a0d2cca388e44de0 Mon Sep 17 00:00:00 2001 From: johnymontana Date: Fri, 1 Nov 2024 14:14:55 -0600 Subject: [PATCH 2/5] Clarify Postgres usage for local Collections --- modus/search.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/modus/search.mdx b/modus/search.mdx index bdf6a5e3..bd6142e9 100644 --- a/modus/search.mdx +++ b/modus/search.mdx @@ -387,7 +387,9 @@ export function searchSimilarProducts( ## Local Development With Collections -Data stored in Collections is persisted to a Postgres database. When using Collections in a Modus app deployed to the Hypermode platform this Postgres database is managed by Hypermode and no additional setup is required by the user. However, when developing with Modus locally or outside of the Hypermode platform a Postgres instance will need to be configured for the persistance layer. +Data stored in Collections are persisted to a Postgres database. When using Collections in a Modus app deployed to the Hypermode platform this Postgres database is managed by Hypermode and no additional setup is required by the user. However, when developing with Modus locally or outside of the Hypermode platform a Postgres instance will need to be configured for the Collections persistence layer. + +No specific method for hosting this Postgres database is required as long as the appropirate database migration is applied (Step 3 below) and the `MODUS_DB` environment variable containing the connection string to your Postgres database is set (Step 4 below). The steps below describe using [Docker](https://www.docker.com/products/docker-desktop/) to start and configure a Postgres instance for local development with Collections. To start and configure a local Postgres instance for working with Collections locally using [Docker Compose](https://docs.docker.com/compose/) follow these steps: From cd56052b490b4220dbb1190d946874bb7b9136fe Mon Sep 17 00:00:00 2001 From: William Lyon Date: Sun, 3 Nov 2024 06:54:53 -0700 Subject: [PATCH 3/5] updates to conform to style guide --- modus/search.mdx | 47 +++++++++++++++---- styles/config/vocabularies/general/accept.txt | 1 + 2 files changed, 40 insertions(+), 8 deletions(-) diff --git a/modus/search.mdx b/modus/search.mdx index bd6142e9..b23dbe96 100644 --- a/modus/search.mdx +++ b/modus/search.mdx @@ -385,28 +385,53 @@ export function searchSimilarProducts( -## Local Development With Collections +## Develop locally with Collections -Data stored in Collections are persisted to a Postgres database. When using Collections in a Modus app deployed to the Hypermode platform this Postgres database is managed by Hypermode and no additional setup is required by the user. However, when developing with Modus locally or outside of the Hypermode platform a Postgres instance will need to be configured for the Collections persistence layer. +Data stored in Collections are persisted to a PostgreSQL database. When using +Collections in a Modus app deployed to the Hypermode platform this PostgreSQL +database is managed by Hypermode and no additional setup is required by the +user. However, when developing with Modus locally or outside of the Hypermode +platform a PostgreSQL instance is needed for the Collections persistence layer. -No specific method for hosting this Postgres database is required as long as the appropirate database migration is applied (Step 3 below) and the `MODUS_DB` environment variable containing the connection string to your Postgres database is set (Step 4 below). The steps below describe using [Docker](https://www.docker.com/products/docker-desktop/) to start and configure a Postgres instance for local development with Collections. +Any hosting method for this PostgreSQL database is sufficient, so feel free to +use your favorite method of installing and running PostgreSQL locally or in the +cloud. A database migration must be applied once the PostgreSQL database is +running (Step 3 below) and the `MODUS_DB` environment variable containing the +connection string to your PostgreSQL database is set (Step 4 below). The steps +below describe using [Docker](https://www.docker.com/products/docker-desktop/) +to start and configure a PostgreSQL instance for local development with +Collections. -To start and configure a local Postgres instance for working with Collections locally using [Docker Compose](https://docs.docker.com/compose/) follow these steps: +To start and configure a local PostgreSQL instance for working with Collections +locally using [Docker Compose](https://docs.docker.com/compose/) follow these +steps: -1. Clone the [Modus GitHub repository](https://github.com/hypermodeinc/modus): + + + + Clone the [Modus GitHub repository](https://github.com/hypermodeinc/modus): ```sh git clone https://github.com/hypermodeinc/modus.git ``` -2. Start the Collections Postgres database using the local Docker Compose script: + + + + +Start the Collections PostgreSQL database using the local Docker Compose script: ```sh cd modus/runtime/tools/local docker-compose up ``` -3. Next, you will need to apply the database schema using the [golang-migrate](https://github.com/golang-migrate/migrate) utility. + + + + +Next, apply the database schema using the +[golang-migrate](https://github.com/golang-migrate/migrate) utility. On MacOS, you can install this utility with the following: @@ -421,10 +446,16 @@ export POSTGRESQL_URL='postgresql://postgres:postgres@localhost:5433/my-runtime- migrate -database ${POSTGRESQL_URL} -path ../../db/migrations up ``` -4. Set the `MODUS_DB` environmet variable: + + + + Set the `MODUS_DB` environment variable: ```sh export MODUS_DB=postgresql://postgres:postgres@localhost:5433/my-runtime-db?sslmode=disable ``` + + + You can now use Collections locally in your Modus app. diff --git a/styles/config/vocabularies/general/accept.txt b/styles/config/vocabularies/general/accept.txt index c20a7f2f..7e0fad90 100644 --- a/styles/config/vocabularies/general/accept.txt +++ b/styles/config/vocabularies/general/accept.txt @@ -6,6 +6,7 @@ AWS boolean CLI|cli [Cc]onsole +Collections computeSimilarity CRUD [Dd]graph From faae8e037b48856edc8e88da4f57c1871e452c71 Mon Sep 17 00:00:00 2001 From: William Lyon Date: Sun, 3 Nov 2024 09:25:01 -0700 Subject: [PATCH 4/5] Use active voice to be consistent with style guide --- modus/search.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/modus/search.mdx b/modus/search.mdx index b23dbe96..6b48d742 100644 --- a/modus/search.mdx +++ b/modus/search.mdx @@ -387,20 +387,20 @@ export function searchSimilarProducts( ## Develop locally with Collections -Data stored in Collections are persisted to a PostgreSQL database. When using -Collections in a Modus app deployed to the Hypermode platform this PostgreSQL -database is managed by Hypermode and no additional setup is required by the -user. However, when developing with Modus locally or outside of the Hypermode -platform a PostgreSQL instance is needed for the Collections persistence layer. +While Collections expose a key-value interface for working with data, a +PostgreSQL database instance persists the data. When using Collections in a +Modus app deployed to the Hypermode platform, Hypermode manages this PostgreSQL +database and users don't need to perform any additional setup. However, when +developing with Modus locally or outside of the Hypermode platform, you need a +PostgreSQL instance for the Collections persistence layer. Any hosting method for this PostgreSQL database is sufficient, so feel free to use your favorite method of installing and running PostgreSQL locally or in the -cloud. A database migration must be applied once the PostgreSQL database is -running (Step 3 below) and the `MODUS_DB` environment variable containing the -connection string to your PostgreSQL database is set (Step 4 below). The steps -below describe using [Docker](https://www.docker.com/products/docker-desktop/) -to start and configure a PostgreSQL instance for local development with -Collections. +cloud. You must apply a database migration after you start the PostgreSQL +database (Step 3 below) and set the `MODUS_DB` environment variable with your +PostgreSQL database connection string (Step 4 below). The steps below describe +using [Docker](https://www.docker.com/products/docker-desktop/) to start and +configure a PostgreSQL instance for local development with Collections. To start and configure a local PostgreSQL instance for working with Collections locally using [Docker Compose](https://docs.docker.com/compose/) follow these From 33399e69e613e9201a6b46bbcb0628aa9eb43880 Mon Sep 17 00:00:00 2001 From: William Lyon Date: Sun, 3 Nov 2024 20:13:23 -0700 Subject: [PATCH 5/5] add note that postgresql dependency is temporary --- modus/search.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/modus/search.mdx b/modus/search.mdx index 6b48d742..46a38015 100644 --- a/modus/search.mdx +++ b/modus/search.mdx @@ -394,6 +394,11 @@ database and users don't need to perform any additional setup. However, when developing with Modus locally or outside of the Hypermode platform, you need a PostgreSQL instance for the Collections persistence layer. + + The dependency on PostgreSQL is temporary and we're working to replace it with + ModusDB, an embedded multi-model database, in an upcoming release. + + Any hosting method for this PostgreSQL database is sufficient, so feel free to use your favorite method of installing and running PostgreSQL locally or in the cloud. You must apply a database migration after you start the PostgreSQL