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.
Deploy 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_URLof 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
githubas that’s the authentication method we will cover in this guide.
Additional required variables:
Client IDof the OAuth app.
Client secretfor 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:
1. Update the callback URL
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
Make sure you hit the
Update application button at the bottom of the page.
2. Push the database schema
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
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
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!