From 2120b062d4bd72df8be8b3d3f8773c085a108192 Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Wed, 3 Dec 2025 12:45:10 -0700 Subject: [PATCH 1/4] Updated the Railway guide based on the changes that have been made to the template --- integration-guides/railway-+-powersync.mdx | 129 +++++++++------------ 1 file changed, 53 insertions(+), 76 deletions(-) diff --git a/integration-guides/railway-+-powersync.mdx b/integration-guides/railway-+-powersync.mdx index bac8a425..48f67d45 100644 --- a/integration-guides/railway-+-powersync.mdx +++ b/integration-guides/railway-+-powersync.mdx @@ -6,7 +6,7 @@ sidebarTitle: Railway Railway is an attractive alternative to managed solutions like Supabase, giving you more control without the complexity of full IaaS management. -### Step 1: Deploy on Railway +## Step 1: Deploy on Railway Find the PowerSync template on the Railway Marketplace, or click the button below to get started: @@ -17,6 +17,16 @@ Find the PowerSync template on the Railway Marketplace, or click the button belo horizontal /> +The starter template will deploy and boot with a default configuration for all of the services. You can always add more services to your project as you need them and update the configuration as you go. + +Once you've opened the deployed project in Railway, you'll see the following services: +- **PowerSync Service**: The PowerSync service is responsible for syncing data between the Postgres database and your client applications. +- **Postgres Source Data**: The Postgres source data is the database that contains your application data. +- **Postgres (PowerSync Bucket Storage)**: The Postgres (PowerSync Bucket Storage) is the database that contains your PowerSync bucket data. +- **Demo Node.js Backend**: The Node backend is the backend for your application and is responsible for generating JWT tokens and API requests that handle upload events from a connected client. +- **Execute Scripts**: The Execute Scripts service is used to apply schema changes to your PowerSync Postgres instance. + + This template automatically creates `lists` and `todos` tables in your Postgres database. The default Sync Rules are configured to sync these tables to your clients. @@ -54,86 +64,19 @@ Find the PowerSync template on the Railway Marketplace, or click the button belo **After adding tables with either option:** - 1. Update the Sync Rules in your YAML config (Step 2) to include the new tables - 2. Re-encode the YAML to base64 and update the `POWERSYNC_CONFIG_B64` environment variable + 1. Update the Sync Rules to include the new tables in the `sync_rules` section of your YAML config. + 2. Re-encode the YAML config to base64 and update the `POWERSYNC_CONFIG_B64` environment variable. See [Understanding the PowerSync Service Configuration](#understanding-the-powersync-service-configuration) for more details. -### Step 2: Configure PowerSync Service - - - You'll notice the PowerSync service deployment crashes initially. This is expected, the `POWERSYNC_CONFIG_B64` environment variable isn't set yet. - - -Let's fix this by generating the config, setting the variable, and restarting the service. - - - - Start with the configuration below and update the Sync Rules to match your schema: - - ```yaml - replication: - connections: - - type: postgresql - uri: ${POSTGRES_SOURCE_URL} - sslmode: disable - - storage: - type: postgresql - uri: ${POSTGRES_BUCKET_URL} - sslmode: disable +## Step 2: Test with the diagnostics app - port: 80 - - sync_rules: - content: | - bucket_definitions: - global: - data: - - SELECT * FROM lists - - SELECT * FROM todos - - client_auth: - jwks_uri: https://${BACKEND_PUBLIC_URL}/api/auth/keys - audience: - - https://${POWERSYNC_PUBLIC_URL} - ``` - - - - Replace each placeholder with the corresponding values from Railway: - - - - Click on **Postgres Source Data** → *Variables* → copy `DATABASE_URL` - - - Click on **Postgres (PowerSync Bucket Storage)** → *Variables* → copy `DATABASE_URL` - - - Click on **Node Backend** → *Settings* → *Networking* → copy the URL - - - Click on **PowerSync Service** → *Settings* → *Networking* → copy the URL - - - - - - Once you've replaced all placeholders: - - 1. Use a base64 encoding tool to encode the YAML file - 2. Copy the encoded string to the `POWERSYNC_CONFIG_B64` environment variable in the **PowerSync Service** - 3. Redeploy when prompted - - - -### Step 3: Test with the diagnostics app - -1. [Generate a development token](https://docs.powersync.com/tutorials/self-host/generate-dev-token) -2. Open the PowerSync Diagnostics App service +1. Generate a development token + - The `Demo Node.js Backend` service has a `/api/auth/token` endpoint you can hit to get a developmentJWT token. You can use this endpoint to generate a development token. + - You can also generate a development token by following the [Generate development token](/tutorials/self-host/generate-dev-token) tutorial. +2. Open the `PowerSync Diagnostics Client` service in the browser. 3. Paste your token to test your connection and Sync Rules -### Step 4: Connect Your Client +## Step 3: Connect Your Client Follow our guide to connect your app to your backend and PowerSync instance + +## Understanding the PowerSync Service Configuration + +The PowerSync Service configuration is written in YAML and converted to base64 to be used as an environment variable. + +If you need to make changes to the configuration, you can copy and edit the example YAML file below, [base64 encode](https://www.base64encode.org/) it, and update the `POWERSYNC_CONFIG_B64` environment variable in the `PowerSync Service` service. This will be required if you need to update the Sync Rules of your project. + +```yaml config.yaml +replication: + connections: + - type: postgresql + uri: !env PS_POSTGRES_SOURCE_URL + sslmode: disable + +storage: + type: postgresql + uri: !env PS_POSTGRES_BUCKET_URL + sslmode: disable + +port: 80 + +sync_rules: + content: | + bucket_definitions: + global: + data: + - SELECT * FROM lists + - SELECT * FROM todos + +client_auth: + jwks_uri: !env PS_AUTH_JWKS + audience: + - !env PS_AUTH_AUD +``` \ No newline at end of file From 886003422980429e5fcacdb20295a7ac3e65cc41 Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Wed, 3 Dec 2025 14:05:35 -0700 Subject: [PATCH 2/4] Implemented requested changes on the PR --- integration-guides/railway-+-powersync.mdx | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/integration-guides/railway-+-powersync.mdx b/integration-guides/railway-+-powersync.mdx index 48f67d45..6e5c0ae8 100644 --- a/integration-guides/railway-+-powersync.mdx +++ b/integration-guides/railway-+-powersync.mdx @@ -1,6 +1,6 @@ --- title: "Railway + PowerSync" -description: "Deploy PowerSync Service with a custom backend on Railway, including Postgres source database, bucket storage, and diagnostics app." +description: "Deploy PowerSync Service with a custom backend on Railway, including Postgres source database, bucket storage, and sync diagnostics app." sidebarTitle: Railway --- @@ -23,7 +23,8 @@ Once you've opened the deployed project in Railway, you'll see the following ser - **PowerSync Service**: The PowerSync service is responsible for syncing data between the Postgres database and your client applications. - **Postgres Source Data**: The Postgres source data is the database that contains your application data. - **Postgres (PowerSync Bucket Storage)**: The Postgres (PowerSync Bucket Storage) is the database that contains your PowerSync bucket data. -- **Demo Node.js Backend**: The Node backend is the backend for your application and is responsible for generating JWT tokens and API requests that handle upload events from a connected client. +- **Demo Node.js Backend**: The Node.js backend is the backend for your application and is responsible for generating JWT tokens and API requests that handle upload events from a connected client. Note that this backend is not secured at all, and is intended to be used for demo purposes only. +- **Sync Diagnostics App**: The Sync Diagnostics App is a web app that implements the [PowerSync Web SDK](/client-sdk-references/javascript-web) and allows you to test your PowerSync connection and see the data that is being synced. - **Execute Scripts**: The Execute Scripts service is used to apply schema changes to your PowerSync Postgres instance. @@ -68,12 +69,12 @@ Once you've opened the deployed project in Railway, you'll see the following ser 2. Re-encode the YAML config to base64 and update the `POWERSYNC_CONFIG_B64` environment variable. See [Understanding the PowerSync Service Configuration](#understanding-the-powersync-service-configuration) for more details. -## Step 2: Test with the diagnostics app +## Step 2: Test with the Sync Diagnostics App 1. Generate a development token - - The `Demo Node.js Backend` service has a `/api/auth/token` endpoint you can hit to get a developmentJWT token. You can use this endpoint to generate a development token. + - The `Demo Node.js Backend` service has a `/api/auth/token` endpoint you can hit to get a development JWT token. You can use this endpoint to generate a development token. - You can also generate a development token by following the [Generate development token](/tutorials/self-host/generate-dev-token) tutorial. -2. Open the `PowerSync Diagnostics Client` service in the browser. +2. Open the `Sync Diagnostics App` service in the browser. 3. Paste your token to test your connection and Sync Rules ## Step 3: Connect Your Client @@ -86,6 +87,10 @@ Once you've opened the deployed project in Railway, you'll see the following ser Follow our guide to connect your app to your backend and PowerSync instance +## Step 4: Implement your backend + +PowerSync is designed to integrate with your existing backend infrastructure for persisting client mutations to your backend database. See the [Backend Application Setup](/installation/app-backend-setup) guide for details. + ## Understanding the PowerSync Service Configuration The PowerSync Service configuration is written in YAML and converted to base64 to be used as an environment variable. From 6e623108e0a3ef4482ab923fb23c9eb9ff564fd3 Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Wed, 3 Dec 2025 14:32:25 -0700 Subject: [PATCH 3/4] Small changes --- integration-guides/railway-+-powersync.mdx | 24 ++++++++++++++-------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/integration-guides/railway-+-powersync.mdx b/integration-guides/railway-+-powersync.mdx index 6e5c0ae8..5c975786 100644 --- a/integration-guides/railway-+-powersync.mdx +++ b/integration-guides/railway-+-powersync.mdx @@ -1,14 +1,14 @@ --- title: "Railway + PowerSync" -description: "Deploy PowerSync Service with a custom backend on Railway, including Postgres source database, bucket storage, and sync diagnostics app." +description: "Deploy PowerSync Service with a custom backend on Railway, including Postgres source database, bucket storage, and sync diagnostics client." sidebarTitle: Railway --- -Railway is an attractive alternative to managed solutions like Supabase, giving you more control without the complexity of full IaaS management. +[Railway](https://railway.com/) is a self-hosting alternative to managed solutions like Supabase, giving you more control without the complexity of full IaaS management. ## Step 1: Deploy on Railway -Find the PowerSync template on the Railway Marketplace, or click the button below to get started: +Find the "PowerSync Starter (Postgres)" template on the Railway Marketplace, or click the button below to get started: -## Step 2: Test with the Sync Diagnostics App +## Step 2: Test with the Sync Diagnostics Client 1. Generate a development token - The `Demo Node.js Backend` service has a `/api/auth/token` endpoint you can hit to get a development JWT token. You can use this endpoint to generate a development token. - You can also generate a development token by following the [Generate development token](/tutorials/self-host/generate-dev-token) tutorial. -2. Open the `Sync Diagnostics App` service in the browser. +2. Open the `Sync Diagnostics Client` service in the browser. 3. Paste your token to test your connection and Sync Rules ## Step 3: Connect Your Client @@ -84,12 +84,18 @@ Once you've opened the deployed project in Railway, you'll see the following ser icon="plug" href="/installation/client-side-setup" > - Follow our guide to connect your app to your backend and PowerSync instance + Follow our guide to connect your app to your backend and PowerSync instance. See our guide to learn more about how to implement your client-side application. -## Step 4: Implement your backend +## Step 4: Implement your Backend -PowerSync is designed to integrate with your existing backend infrastructure for persisting client mutations to your backend database. See the [Backend Application Setup](/installation/app-backend-setup) guide for details. + + PowerSync is designed to integrate with your existing backend infrastructure for persisting client mutations to your backend database. See our guide to learn more about how to implement your backend application. + ## Understanding the PowerSync Service Configuration From 54fbff156ffb28da4625d966582cc2e6646c52f8 Mon Sep 17 00:00:00 2001 From: Mike Barnes Date: Wed, 3 Dec 2025 14:36:28 -0700 Subject: [PATCH 4/4] Updated subheading --- integration-guides/railway-+-powersync.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/integration-guides/railway-+-powersync.mdx b/integration-guides/railway-+-powersync.mdx index 5c975786..634037ad 100644 --- a/integration-guides/railway-+-powersync.mdx +++ b/integration-guides/railway-+-powersync.mdx @@ -4,7 +4,7 @@ description: "Deploy PowerSync Service with a custom backend on Railway, includi sidebarTitle: Railway --- -[Railway](https://railway.com/) is a self-hosting alternative to managed solutions like Supabase, giving you more control without the complexity of full IaaS management. +[Railway](https://railway.com/) is a managed cloud platform (PaaS) for deploying and scaling applications, services, and databases via containers. ## Step 1: Deploy on Railway