You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This project provides a serverless backend API for a client application using PowerSync.
6
+
As of January 2025, we've started adding optional backend functionality for PowerSync that handles writing to a backend database (with initial support for MongoDB) and generating JWTs.
7
7
8
-
For more information about CloudCode serverless functions, please visit [this page](https://docs.journeyapps.com/reference/cloudcode/triggering-a-cloudcode-task/trigger-cc-via-http).
8
+
This makes PowerSync easier to implement for developers who prefer not having to maintain their own backend code and infrastructure (PowerSync's [usual architecture](/installation/app-backend-setup) is to use your own backend to process writes and generate JWTs).
9
+
10
+
We are approaching this in phases, and phase 1 allows using the CloudCode feature of JourneyApps Platform, a [sibling product](https://www.powersync.com/company) of PowerSync. [CloudCode](https://docs.journeyapps.com/reference/cloudcode/cloudcode-overview) is a serverless cloud functions engine based on Node.js and AWS Lambda. It's provided as a fully-managed service running on the same cloud infrastructure as the rest of PowerSync Cloud. PowerSync and JourneyApps Platform share the same login system, so you don’t need to create a separate account to use CloudCode.
11
+
12
+
<Info>
13
+
We are currently making JourneyApps Platform CloudCode available for free to all our customers who use PowerSync with MongoDB. It does require a bit of "white glove" onboarding from our team. [Contact us](/resources/contact-us) if you want to use this functionality.
14
+
</Info>
15
+
16
+
Phase 2 on our roadmap involves fully integrating CloudCode into the PowerSync Cloud environment. For more details, see [this post on our blog](https://www.powersync.com/blog/turnkey-backend-functionality-conflict-resolution-for-powersync).
17
+
18
+
19
+
# Using CloudCode in JourneyApps Platform for MongoDB Backend Functionality
20
+
21
+
There is a MongoDB template available in CloudCode that provides the backend functionality needed for a PowerSync MongoDB implementation. Here is how to use it:
22
+
23
+
## Create a new JourneyApps Platform project
24
+
25
+
To create a new JourneyApps Platform project in order to use CloudCode:
9
26
10
-
# Create New CloudCode Project
11
-
To create a new CloudCode project, following the steps below:
12
27
<Steps>
13
28
<Step>
14
29
Navigate to the [JourneyApps Admin Portal](https://accounts.journeyapps.com/portal/admin). You should see a list of your projects if you've created any.
@@ -17,46 +32,40 @@ To create a new CloudCode project, following the steps below:
17
32
</Frame>
18
33
</Step>
19
34
<Step>
20
-
Select `Create Project` at the top right of the screen.
35
+
Select **Create Project** at the top right of the screen.
There are two options for how you can manage changes to your project:
39
-
1. `Basic (Revision)`: A simple workflow with basic restore points
40
-
2. `Advanced (Git)`: A git-based workflow with commits, branching and merging.
41
-
42
-
Select a `Version Control` option, `Git` provider and click `Next`.
43
-
For demonstration purposes we will choose `Basic` and `JourneyApps` as our Git provider.
53
+
There are options available for managing version control for the project. For simplicity we recommend selecting **Basic (Revisions)** and **JourneyApps** as the Git provider.
To base your project on a template, select `TypeScript` as your template language, and `MongoDB CRUD & Auth Backend` as your template. You can now create your app
50
-
by clicking `Create App`.
59
+
Select **TypeScript** as your template language, and `MongoDB CRUD & Auth Backend` as your template. Then click **Create App**.
1.`generate_keys` - This is a task that can be used to generate a private/public key pair which the `jwks` and `token` tasks require.
79
+
Here's the purpose of each task:
80
+
81
+
1.`generate_keys` - This is a task that can be used to generate a private/public key pair which the `jwks` and `token` tasks (see below) require.
71
82
72
83
<Warning>
73
-
This task does not expose an HTTP endpoint and should only be used for development and getting started.
84
+
The `generate_keys` task does not expose an HTTP endpoint and should only be used for development and getting started.
74
85
</Warning>
75
-
2.`jwks` - This exposes an HTTP endpoint which has a `GET` function which returns the public JWKS details.
76
-
3.`token` - This task exposes an HTTP endpoint which has a `GET` function. This tasks is used by a PowerSync client to generate a token to validate against the PowerSync Service.
77
-
For more information about custom authentication setups for PowerSync, please see [this page](https://docs.powersync.com/installation/authentication-setup/custom) from the PowerSync docs.
86
+
2.`jwks` - This task [exposes an HTTP endpoint](https://docs.journeyapps.com/reference/cloudcode/triggering-a-cloudcode-task/trigger-cc-via-http) which has a `GET` function which returns the public [JWKS](https://stytch.com/blog/understanding-jwks/) details.
87
+
3.`token` - This task exposes an HTTP endpoint which has a `GET` function. The task is used by a PowerSync client to generate a token to validate against the PowerSync Service.
88
+
For more information about custom authentication setups for PowerSync, please [see here](https://docs.powersync.com/installation/authentication-setup/custom).
78
89
4.`upload` - This task exposes an HTTP endpoint which has a `POST` function which is used to process the write events from a PowerSync client and writes it back to the source MongoDB database.
79
90
80
91
## Setup
81
92
82
93
### 1. Generate key pair
83
-
Before using the serverless functions you need to generate a public/private key pair. Do the following to generate the key pair:
94
+
Before using the CloudCode tasks, you need to generate a public/private key pair. Do the following to generate the key pair:
84
95
1. Open the `generate_keys` CloudCode task.
85
96
2. Select the **Test CloudCode Task** button at the top right. This will print the public and private key in the task logs window.
86
97
<Frame>
@@ -89,53 +100,56 @@ Before using the serverless functions you need to generate a public/private key
89
100
3. Copy and paste the `POWERSYNC_PUBLIC_KEY` and `POWERSYNC_PRIVATE_KEY` to a file — we'll need this in the next step.
90
101
91
102
<Note>
92
-
This step is only meant for testing and development because the keys are shown in the logs files.
103
+
This step is only meant for testing and development because the keys are shown in the log files.
93
104
For production, [generate a key pair locally](https://github.com/powersync-ja/powersync-jwks-example?tab=readme-ov-file#1-generate-a-key-pair) and move onto step 2 and 3.
94
105
</Note>
95
106
96
107
### 2. Configure a deployment
97
-
Before using the tasks, we need to configure a deployment.
98
-
1. At the top of the IDE, select the `Deployments` option.
99
-
2. Create a new deployment by selecting the `+` icon at the top right, _or_ use the default `Testing` deployment. You can configure different deployments for different environments.
100
-
3. Now select the `Deployment settings` button for the instance.
101
-
4. In the `Deployment settings` - `General` tab, capture a `Domain` value in the text field. The application will validate the domain name to make sure it's available.
102
-
5. Select `Save`.
103
-
6. Deploy the deployment: you can do so by selecting the `Deploy app` button, which can be found on the far right for each of the deployments you have configured. After the deployment is completed, it will take a few minutes for the domain to be available.
108
+
Before using the tasks, we need to configure a "deployment".
109
+
1. At the top of the IDE, select **Deployments**.
110
+
2. Create a new deployment by using the **+** button at the top right, _or_ use the default `Testing` deployment. You can configure different deployments for different environments (e.g. staging, production)
111
+
3. Now select the **Deployment settings** button for the instance.
112
+
4. In the **Deployment settings** - **General** tab, capture a **Domain** value in the text field. This domain name determines where the HTTP endpoints exposed by these CloudCode tasks can be accessed. The application will validate the domain name to make sure it's available.
113
+
5. Select **Save**.
114
+
6. Deploy the deployment: you can do so by selecting the **Deploy app** button, which can be found on the far right for each of the deployments you have configured. After the deployment is completed, it will take a few minutes for the domain to be available.
104
115
7. Your new domain will be available at `<domain_name>.poweredbyjourney.com`. Open the browser and navigate to the new domain. You should be presented with `Cannot GET /`, because there is no index route.
105
116
106
117
### 3. Configure environment variables
107
-
To add a new variable, do the following:
108
-
1. Head over to the `Deployment settings` option again.
3. Capture the variable name in the **Name** text field.
133
+
4. Capture the variable value in the **Value** text field.
134
+
5. (Suggested) Check the **Masked** checkbox to obfuscate the variable value for security purposes.
135
+
6. Repeat until all the variables are added.
136
+
137
+
To finalize the setup, do the following:
138
+
1. Select the **Save** button. This is important, otherwise the variables will not save.
139
+
2. Deploy the deployment: you can do so by selecting the **Deploy app** button.
140
+
128
141
### 4. Test
129
142
Open your browser and navigate to `<domain_name>.poweredbyjourney.com/jwks`.
130
-
You must set the JWKS url during to configure the PowerSync instance.
143
+
131
144
If the setup was successful, the `jwks` task will render the keys in JSON format. Make sure the format of your JWKS keys matches the format [in this example](https://hlstmcktecziostiaplz.supabase.co/functions/v1/powersync-jwks) JWKS endpoint.
132
145
133
146
## Usage
134
-
Make sure you've configured a deployment and set up environment variables as described in the **Setup** steps before before using the API.
147
+
Make sure you've configured a deployment and set up environment variables as described in the **Setup** steps above before using the HTTP API endpoints exposed by the CloudCode tasks:
135
148
136
149
### Token
137
-
You would call the `token` HTTP API endpoint when you implement the `fetchCredentials()` function on the client application.
138
-
Send a HTTP GET request to `<domain_name>.poweredbyjourney.com/token?user_id=<user_id>` to fetch a JWT for a user. You must provide a `user_id` in the query string of the request, as this is included in the JWT that is generated.
150
+
You would call the `token` HTTP API endpoint when you [implement](/installation/client-side-setup/integrating-with-your-backend) the `fetchCredentials()` function on the client application.
151
+
152
+
Send an HTTP GET request to `<domain_name>.poweredbyjourney.com/token?user_id=<user_id>` to fetch a JWT for a user. You must provide a `user_id` in the query string of the request, as this is included in the JWT that is generated.
139
153
140
154
The response of the request would look like this:
141
155
```json
@@ -144,14 +158,17 @@ The response of the request would look like this:
144
158
145
159
### JWKS
146
160
The `jwks` HTTP API endpoint is used by PowerSync to validate the token returned from the `<domain_name>.poweredbyjourney.com/token` endpoint. This URL must be set in the configuration of your PowerSync instance.
161
+
147
162
Send an HTTP GET request to `<domain_name>.poweredbyjourney.com/jwks`.
148
163
149
-
An example of the format can be found using [this link](https://hlstmcktecziostiaplz.supabase.co/functions/v1/powersync-jwks).
164
+
An example of the response format can be found using [this link](https://hlstmcktecziostiaplz.supabase.co/functions/v1/powersync-jwks).
150
165
151
166
### Upload
152
-
You would call the `upload` HTTP API endpoint when you implement the `uploadData()` function on the client application.
167
+
You would call the `upload` HTTP API endpoint when you [implement](/installation/client-side-setup/integrating-with-your-backend) the `uploadData()` function on the client application.
168
+
153
169
Send an HTTP POST request to `<domain_name>.poweredbyjourney.com/upload`.
154
-
The body of the payload should look like this:
170
+
171
+
The body of the request payload should look like this:
155
172
```
156
173
{
157
174
"op": "PUT",
@@ -167,16 +184,18 @@ The body of the payload should look like this:
167
184
168
185
The API will respond with HTTP status `200` if the write was successful.
169
186
170
-
## Modifying and making changes
171
187
172
-
If you need to make changes to the way the `upload` task writes data to the source MongoDB database, do the following:
188
+
## Customization required
189
+
190
+
You can make changes to the way the `upload` task writes data to the source MongoDB database. At a minimum, you will need to modify it to take your specific MongoDB database "schema" into consideration.
173
191
174
-
1. Open the `CloudCode` section at the top of the IDE.
192
+
Here is how:
193
+
194
+
1. Open the **CloudCode** section at the top of the IDE.
175
195
2. Select and expand the `upload` task in the panel on the left.
176
196
3. The `index.ts` contains the entry point function that accepts the HTTP request.
177
-
4. The `persister.ts` file connects to the MongoDB database and writes the data to the MongoDB database. You can update this file to introduce your database schema, etc.
197
+
4. The `persister.ts` file connects to the MongoDB database and writes the data to the MongoDB database. You can update this file to introduce your database schema. The default template has an example schema for a To-Do List application:
178
198
179
-
Example MongoDB database schema setup:
180
199
```typescript
181
200
/**
182
201
* Line 13 in upload/persister.ts
@@ -201,3 +220,8 @@ export const schema = {
201
220
}
202
221
};
203
222
```
223
+
224
+
## Production considerations
225
+
226
+
Before going into production with this solution, you will need to set up authentication on the HTTP endpoints exposed by the CloudCode tasks. Please [contact us](/resources/contact-us) for assistance.
0 commit comments