Small updates to the Railway integration guide.

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 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 managed cloud platform (PaaS) for deploying and scaling applications, services, and databases via containers.
 
-### 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:
+Find the "PowerSync Starter (Postgres)" template on the Railway Marketplace, or click the button below to get started:
 
 <Card
   title="Deploy on Railway"
@@ -17,6 +17,17 @@ 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.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 Client**: The Sync Diagnostics Client 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.
+
+
 <Note>
   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,91 +65,68 @@ 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.
 </Accordion>
 
-### Step 2: Configure PowerSync Service
-
-<Warning>
-  You'll notice the PowerSync service deployment crashes initially. This is expected, the `POWERSYNC_CONFIG_B64` environment variable isn't set yet.
-</Warning>
-
-Let's fix this by generating the config, setting the variable, and restarting the service.
+## Step 2: Test with the Sync Diagnostics Client
 
-<Steps>
-  <Step title="Copy the YAML config">
-    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
-
-    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}
-    ```
-  </Step>
-
-  <Step title="Replace the placeholders">
-    Replace each placeholder with the corresponding values from Railway:
-
-    <AccordionGroup>
-      <Accordion title="${POSTGRES_SOURCE_URL}">
-        Click on **Postgres Source Data** → *Variables* → copy `DATABASE_URL`
-      </Accordion>
-      <Accordion title="${POSTGRES_BUCKET_URL}">
-        Click on **Postgres (PowerSync Bucket Storage)** → *Variables* → copy `DATABASE_URL`
-      </Accordion>
-      <Accordion title="${BACKEND_PUBLIC_URL}">
-        Click on **Node Backend** → *Settings* → *Networking* → copy the URL
-      </Accordion>
-      <Accordion title="${POWERSYNC_PUBLIC_URL}">
-        Click on **PowerSync Service** → *Settings* → *Networking* → copy the URL
-      </Accordion>
-    </AccordionGroup>
-  </Step>
-
-  <Step title="Encode and deploy">
-    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>
-</Steps>
-
-### 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 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 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
 
 <Card
   title="Client-Side Setup"
   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.
 </Card>
+
+## Step 4: Implement your Backend
+
+<Card
+  title="Backend Application Setup"
+  icon="server"
+  href="/installation/app-backend-setup"
+>
+  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.
+</Card>
+
+## 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
+```