Deploy Beam on Railway

Beam is an open-source message board for your organization or project. Developed originally by our lovely friends at PlanetScale, they’ve created and opensourced a message board where you can create posts written in Markdown with support for images, and people can respond with a ♥️ or a comment. You can also set up triggers to send messages on Slack whenever a new post is published.

Before we can deploy Beam on Railway, we need to get the necessary credentials. Go to your developer settings on GitHub and click on the New OAuthApp button. For the callback URL, you can enter http://localhost:3000/api/auth/callback/github for now. We will update this once we’ve deployed our Beam instance on Railway.

To deploy your Beam instance on Railway, simply click the button above and enter the prompted environment variables and hit deploy. The required MySQL database is automagically provisioned for you.

Pre-configured environment variables:

• DATABASE_URL: Mapped to the MYSQL_URL of the MySQL database in your project.
• NEXT_APP_URL: The URL where your application can be reached.
• NEXTAUTH_URL: The canonical URL of your application.
• AUTH_PROVIDER: Pre-configured to github as that’s the authentication method we will cover in this guide.

Additional required variables:

• GITHUB_ID: The Client ID of the OAuth app.
• GITHUB_SECRET: The Client secret for the OAuth app.
• GITHUB_ALLOWED_ORG: The GitHub organization to which the users logging into this application will belong to.
• NEXTAUTH_SECRET: Used to encrypt the JWTs.

Once you hit the deploy button in the template, your app will be deployed successfully but it isn’t quite ready yet. Before you can start using it, you need to do two more things:

When we created our GitHub OAuth application, we set our callback URL to a localhost URL because we didn’t quite know what our application URL on Railway would be. Now that we’ve deployed our application, we can see our URL in the Domains tab inside our service.

The domain for our Beam instance

Copy this URL and update the Callback URL in your OAuth app. In my case, the new URL will be https://beam-production.up.railway.app/api/auth/callback/github. I also ended up updating my Homepage URL to be https://beam-production.up.railway.app/.

Make sure you hit the Update application button at the bottom of the page.

Clone the Beam repository Railway created for you on your local system and connect it to your Railway project using the Railway CLI by running:

railway link PROJECT_ID

Next, we will use the Prisma command to update the database schema for our MySQL instance on Railway:

railway run npx prisma db push

Once this command finishes running, your MySQL instance on Railway should have all the necessary tables.

Database tables for Beam

Now that we’ve completed all the required steps, we can access and sign in to our Beam instance. When you sign in, depending on your whether you are an organization member or owner for the organization you specified under the GITHUB_ALLOWED_ORG environment variable, you will be asked to either Request or Grant access. Make sure you do this before authorizing your own account. Failure to do so will result in an Access Denied error screen with the message You do not have permission to sign in.

GitHub organization access prompt

Once you’ve configured the organization access and signed into the application, you should be able to use it along with your team members.

Beam on Railway

Your Beam instance should now be live and completely usable. The members within your org can create posts, like them, and comment on them. You can also optionally enable image uploads using Cloudinary by setting the following environment variables:

• NEXT_PUBLIC_ENABLE_IMAGE_UPLOAD: Set the value to true.
• CLOUDINARY_CLOUD_NAME: The cloud name on Cloudinary.
• CLOUDINARY_API_KEY: Your Cloudinary API key.
• CLOUDINARY_API_SECRET: Your Cloudinary API secret.

Lastly, to configure notifications whenever a post is published, you can setup notifications on Slack.

We hope you found this tutorial useful and successfully deployed your Beam instance on Railway. If you have suggestions for more open-source self-hosted applications you’d like to see guides for, let us know on Discord!