feat: add pulse railway starter app+ db docs

content/400-pulse/200-getting-started.mdx

@@ -16,9 +16,9 @@ toc: true
 
 </Admonition>
 
-You'll need the following to integrate Pulse into your application;
+You'll need the following to integrate Pulse into your application:
 
-- [Prisma Data Platform workspace](https://console.prisma.io)
+- A [Prisma Data Platform workspace](https://console.prisma.io).
 - [Prisma Client](/orm/prisma-client) version `4.16.1` or higher and [`@prisma/extension-pulse`](https://www.npmjs.com/package/@prisma/extension-pulse) version `1.0.1` or higher.
 - A publicly accessible PostgreSQL (version 12+) database with [logical replication](https://www.postgresql.org/docs/current/logical-replication-quick-setup.html) enabled. View our [setup guide](/pulse/database-setup/general-database-instructions#enable-logical-replication) on configuring logical replication for your database.
 

content/400-pulse/250-database-setup/300-railway.mdx

@@ -8,93 +8,128 @@ toc: true
 
 <TopBlock>
 
-[Railway.app](https://railway.app) offers an excellent [templates feature](https://railway.app/templates). If you wish to quickly start with Prisma Pulse, you can use either of two templates:
+Railway provides a useful feature known as [templates](https://railway.app/templates) to facilitate quick project setup. These templates allow users to package a service or a group of services into a format that can be easily reused and shared. We have two templates for Prisma Pulse that you can use:
 
 - [Prisma Pulse DB Only](https://railway.app/template/pulse-pg): Provides a fresh, pre-configured PostgreSQL database which you can use with Prisma Pulse.
 - [Prisma Pulse DB & App](https://railway.app/template/pulse-starter): Provides a pre-configured PostgreSQL database and a [Prisma Pulse starter app](https://github.com/prisma/pulse-starter).
 
 </TopBlock>
 
-## Setup using the template
+## Setup with template: "Prisma Pulse DB Only"
 
-<br />
+### Overview
 
-1. Deploy the [template](https://railway.app/template/pulse-pg) on Railway
+This section provides step-by-step instructions for setting up a Pulse-ready PostgreSQL database using the Railway template called: [Prisma Pulse DB Only](https://railway.app/template/pulse-pg).
 
-2. Click on the service called `restart-db-then-delete-me`.
+The template consists of two [services](https://docs.railway.app/reference/services):
 
-3. You will see a list of deployments under the **Deployments** tab.
-
-4. Click the most recent build's **View Logs** button.
-
-5. Click on the **Deploy Logs** tab.
-
-> If the service ran correctly, you should see a message in the logs that says "All done please restart the database" along with your `DATABASE_URL` connection string.
-
-6. Copy the `DATABASE_URL` connection string and save it for later. Then restart your Railway database.
-
-   - Click on your database.
-
-   - Navigate to the Deployments tab.
-
-   - Go into the three-dots menu on the latest deployment and click the `Restart` option.
+- **Postgres**: A PostgreSQL database that you'll be able to use with Prisma Pulse after going through the setup instructions.
+- **restart-and-delete-me**: This service contains a [script](https://github.com/prisma/pulse-railway-pg-config/blob/main/config-db.ts) that's executed once and configures the PostgreSQL database to make it usable with Prisma Pulse. Once the script has been executed, the instructions will tell you to delete this service since it won't be needed any more.
 
-7. After restarting your database. Click on the `restart-db-then-delete-me` service and navigate to the **Settings** tab.
-
-8. Scroll down to the bottom and click the red **Delete Service** button.
-
-   > Note: If you would like to use this service and the corresponding repository to create a new Prisma Pulse project. You can do so by cloning the repo from your GitHub account to your local machine.
-
-   - Once you have cloned the repository, you can run the following command:
-
-     ```bash
-
-     bash rm config-db.ts
-
-     ```
+### Instructions
 
-   - Then remove the script `start: ts-node config-db.ts` from the `scripts` object in the `package.json` file.
-
-     > This is to prevent the script from running every time you push up to the repo associated with the `restart-db-then-delete-me` service.
+1. Deploy the [template](https://railway.app/template/pulse-pg) on Railway.
+2. Once the deployment has finished, click on the service called **restart-db-then-delete-me**.
+3. You will see a list of deployments under the **Deployments** tab.
+4. Click the most recent deployment's **View Logs** button.
+5. Click on the **Deploy Logs** tab. If the service ran correctly, you should see a message in the logs that says:
+   ```terminal no-copy
+   All done please restart the database and delete this service.
+   Here is the DATABASE_URL
+   postgresql://postgres:[email protected]:28606/railway
+   ```
+   > **Note**:
+   > The `DATABASE_URL` can also be found by clicking on the **Postgres** Service and navigating to the **Variables** tab, then clicking the copy icon next to `DATABASE_URL` environment variable value.
+   > ![](../images/railway-database-url.png)
+6. Copy the `DATABASE_URL` connection string and save it for later. Then restart your Railway database for the changes to be reflected:
+   1. Click on the **Postgres** service that represents your deployed database.
+   2. Navigate to the **Deployments** tab.
+   3. Click on the three-dots menu on the latest deployment and click the **Restart** option.
+7. After restarting your database, click on the **restart-db-then-delete-me** service and navigate to the **Settings** tab.
+8. Scroll down to the bottom and click the red **Delete service** button.
+9. You now have a Pulse-compatible PostgreSQL database running on Railway. You can now follow the instructions on the [Getting started](/pulse/getting-started) page.
+
+## Setup with template: "Prisma Pulse DB & App"
+
+### Overview
+
+This section provides step-by-step instructions for setting up a Pulse starter project with a Pulse-ready PostgreSQL database using the Railway template called: [Prisma Pulse DB & App](https://railway.app/template/pulse-starter).
+The template consists of three [services](https://docs.railway.app/reference/services):
+
+- **Pulse-Starter**: A Typescript app with a basic setup for using Prisma Pulse. You can find the repo for it [on GitHub](https://github.com/prisma/pulse-starter/tree/main).
+- **Postgres**: A PostgreSQL database that you'll be able to use with Prisma Pulse after going through the setup instructions.
+- **restart-and-delete-me**: This service contains a [script](https://github.com/prisma/pulse-railway-pg-config/blob/main/config-db.ts) that's executed once and configures the PostgreSQL database to make it usable with Prisma Pulse. Once the script has been executed, the instructions will tell you to delete this service since it won't be needed any more.
+
+### Instructions
+
+1. Deploy the [template](https://railway.app/template/pulse-starter) on Railway.
+2. You'll be navigated to a page prompting configuration for both the **restart-db-then-delete-me** and **pulse-starter** service:
+   ![Configure Railway template](../images/railway-template-configure.png)
+   1. For the **restart-db-then-delete-me** service, click on the **Configure** button and then save the configuration by clicking on **Save Config**.
+   2. On the **pulse-starter** service, locate and click the **Configure** button. Within the **Environment variables** section, you'll find an option to include the `PULSE_API_KEY` environment variable. Keep the `PULSE_API_KEY` field blank for the time being. Once you've set up the database and obtained the database URL from the [Prisma Data Platform](https://console.prisma.io/), you can then add the `PULSE_API_KEY` to the **pulse-starter** service. With the empty field for the Pulse API key, click **Save Config**.
+   3. Click on the **Deploy** button.
+3. To set up the database and make it Pulse-ready, complete the steps outlined in the [previous section](#setup-with-template-prisma-pulse-db-only), starting from **step 2.** till **step 8.**, then follow the instructions below.
+4. Go to the [Platform Console](https://console.prisma.io/) and select the project in which you want to activate Pulse. If you don't have a project yet, create a new project via the **New project** button.
+5. Navigate to the project's environment in which Pulse should be activated. If you just created a new project, the only available environment is the **Production** environment.
+6. Click **Enable Pulse** on the environment's page.
+7. Paste the `DATABASE_URL` that you acquired before into the **Database connection string** field. Then, finish the process by clicking **Enable Pulse**.
+8. Pulse is now enabled in your project's environment. Click **Generate API key** to obtain the API key that you need in order to use Pulse in your TypeScript starter app.
+9. Save the `PULSE_API_KEY` for later and click **I've securely stored my connection string**.
+10. Back in the Railway UI, click on the **pulse-starter** service.
+    > **Note**: You'll likely find that the build failed for the **pulse-starter** service. This is because the Prisma Pulse API key wasn't provided. Do not worry, this is to be expected and not a problem for the next steps.
+11. Click on the **Variables** tab.
+12. Create your `PULSE_API_KEY` environment variable: Click the **New Variable** button, create the `PULSE_API_KEY` environment variable, and then paste the value of the `PULSE_API_KEY` that you obtained in the Platform Console. Then save the changes by clicking the **Add** button.
+13. With the `PULSE_API_KEY` environment variable in place, you need to rebuild the **pulse-starter** service for the environment variable to take effect:
+14. Click on the **Deployments** tab.
+15. Click on the three-dots menu on the deployment that failed. Then click **Redeploy**.
+16. When the deployment starts, click the **View Logs** button.
+17. Then click on the **Deploy Logs** tab to follow the deployment of the Pulse starter app.
+
+Once the deployment is finished, your Pulse starter app should be running and any database events events will be logged under the **Deploy Logs** tab of the **pulse-starter** service.
+
+To see an event in action, you need to make changes to the `User` table. You can follow the steps below to do that from the Railway UI:
+
+1. Click on the **Postgres** service on your Railway project.
+2. Click on the **Data** tab.
+3. Select the **User** table and click **Add Row**.
+4. Fill out an **email** and a **name**, then click **Insert**.
+5. Return to the **Deploy Logs** of your **pulse-starter** service.
+6. You should be able to see an output from Prisma Pulse for the user being created:
+   ```json
+   just received an event: {
+     action: "create",
+     created: { id: 1, email: "test", name: "[email protected]" },
+     id: 03/34334,
+     modelName: "User"
+   }
+   ```
 
 ## Setup without using a template
 
-<br />
-
 1. Change the PostgreSQL database settings
 
-   You can run these queries in the Railway Database **Query** tab, using the [railway cli](https://docs.railway.app/databases/postgresql), or any other way you might run queries on your database.
+   You can run these queries using a tool such as [pgAdmin](https://www.pgadmin.org/), [dbeaver](https://dbeaver.io/), or any other way you might run queries on your database.
 
    - Set the <inlinecode>[wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html)</inlinecode> to `logical`:
-
      ```sql
      ALTER SYSTEM SET wal_level = logical;
      ```
-
    - Set the <inlinecode>[max_replication_slots](https://www.postgresql.org/docs/current/runtime-config-replication.html)</inlinecode> to `20`:
-
      ```sql
      ALTER SYSTEM SET max_replication_slots = 20;
      ```
-
    - Set the <inlinecode>[wal_keep_size](https://www.postgresql.org/docs/current/runtime-config-replication.html)</inlinecode> to `2048`:
-
      ```sql
      ALTER SYSTEM SET wal_keep_size = 2048;
      ```
-
    - Reload the PostgreSQL configuration:
-
      ```sql
      SELECT pg_reload_conf();
      ```
 
-2. Restart your database
-
-   - Click on your database.
-
-   - Navigate to the Deployments tab.
-
-   - Go into the three-dots menu on the latest deployment and click the `Restart` option.
-
-After setting up your Railway database, you have to use the [connection string](https://docs.railway.app/guides/postgresql#tcp-proxy-connection) provided by Railway that allows public access your PostgreSQL database.
+2. You have to restart your database for the changes to be reflected. To restart your database using the Railway UI:
+   1. Click on your database.
+   2. Navigate to the **Deployments** tab.
+   3. Click on the three-dots menu on the latest deployment and click the **Restart** option.
+3. After setting up your Railway database, you have to use the [connection string](https://docs.railway.app/guides/postgresql#tcp-proxy-connection) provided by Railway that allows public access to your PostgreSQL database.
+4. You now have a Pulse-compatible PostgreSQL database running on Railway. You can now follow the instructions on the [Getting started](/pulse/getting-started) page.