feat: add pulse railway starter app+ db docs

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

@@ -8,93 +8,112 @@ 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.app](https://railway.app) 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 />
+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).
 
-1. Deploy the [template](https://railway.app/template/pulse-pg) on Railway
+The template consists of two [services](https://docs.railway.app/reference/services):
 
-2. Click on the service called `restart-db-then-delete-me`.
+- **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.
 
+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 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.
-
+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.
-
-   - Click on your database.
-
-   - Navigate to the Deployments tab.
-
-   - Go into 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.
-
-   > 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
-
-     ```
-
-   - 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. Click on the **Postgres** service that represents your deployed database.
+   2. Navigate to the **Deployments** tab.
+   3. Go into 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"
+
+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.
+
+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.
+   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 **2.**, then follow the instructions below.
+4. Go to the [Platform Console](https://console.prisma.io/) and activate Pulse in a Platform environment. Next, use the `DATABASE_URL` acquired from earlier steps to generate a `PULSE_API_KEY`.
+5. 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 as the database wasn’t Prisma Pulse ready.
+   > Do not worry, this is to be expected and not a problem for the next steps.
+6. Click on the **Variables** tab.
+7. Manage your `PULSE_API_KEY` environment variable:
+   1. If you do not have the variable, click the **New Variable** button, create the `PULSE_API_KEY` environment variable, and then paste the `API_KEY`. Then save the changes by clicking the **Add** button.
+   2. If you have the variable, click the three vertical dots on the `PULSE_API_KEY` row and select **Edit**. Then paste in the `API_KEY` and click the check mark icon (☑️).
+8. Rebuild the **pulse-starter** service
+   1. Click on the **Deployments** tab.
+   2. Click on the three verticle dots on the deployment that failed. Then click **Redeploy**.
+   3. When the deployment starts, click the **View Logs** button.
+   4. Then click on the **Deploy Logs** tab.
+9. See an event in action
+   1. Click on the **Postgres** service on your railway.app project.
+   2. Click on the **Data** tab.
+   3. Click 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"
+   }
+   ```
+10. You now have a Pulse-compatible PostgreSQL database and the starter project running on **[railway.app](https://railway.app/template/railway.app)**.
 
 ## 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.
+   1. Click on your database.
+   2. Navigate to the **Deployments** tab.
+   3. 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.