Scala’s Play Framework is a powerful tool for building scalable, high-performance web applications and REST APIs. Once you’ve built your API, deploying it can be a daunting task—especially if you’re aiming for minimal overhead and cost. Heroku offers an elegant solution with simple Git-based deployments, a flexible runtime environment, and built-in support for Java and Scala.

This guide walks you through how to deploy a Scala Play REST API to Heroku with step-by-step instructions and code examples.

Prerequisites

Before you begin, ensure the following tools are installed on your system:

• Java SDK (8 or 11) – Heroku supports Java 8 and Java 11 officially.

• SBT (Scala Build Tool) – Play uses SBT to build and run applications.

• Heroku CLI – Command-line interface to interact with your Heroku apps.

• Git – Used for version control and deploying code.

Verify each installation:

Also, sign up and log into Heroku if you haven’t already.

Creating a Simple Scala Play REST API

You can scaffold a Play app using the sbt new command. Open a terminal and run:

You’ll be prompted to name your project. Let’s say you name it play-api.

Navigate to your project directory:

Let’s create a simple REST endpoint. Open app/controllers/HomeController.scala and modify it:

Now update your conf/routes file:

Run the app locally to test:

Visit http://localhost:9000/hello/Heroku to confirm it’s working.

Configuring the Project for Heroku

Heroku supports Java and Scala through its Java Buildpack, but you must configure your Play app to be compatible.

1. Create a Procfile
   This tells Heroku how to start your app.

   bash

   echo "web: target/universal/stage/bin/play-api -Dplay.http.secret.key=\$SECRET_KEY" > Procfile


   Replace play-api with your app’s name if it’s different.

2. Add stage Task in build.sbt

   Add the following to the bottom of build.sbt:

   scala

   enablePlugins(JavaAppPackaging)


   Then in project/plugins.sbt, add:

   scala

   addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "1.9.16")


3. Specify Java Version

   Heroku detects your Java version using system.properties. Create the file:

   bash

   echo "java.runtime.version=11" > system.properties


4. Generate a Secret Key

   For production, Play requires a secret key:

   bash

   heroku config:set SECRET_KEY=$(openssl rand -base64 32)

Pushing to Git and Deploying to Heroku

Now that your project is configured for Heroku, you can push it.

1. Initialize Git Repository

   bash

   git init
git add .
git commit -m "Initial commit"


2. Create a Heroku App

   bash

   heroku create play-scala-api


3. Deploy Using Git

   Since we’re using sbt and Java buildpack, we need to compile and stage the app before pushing:

   bash

   sbt clean compile stage


   Then push it:

   bash

   git add .
git commit -m "Prepared for Heroku deployment"
git push heroku master


   ⚠️ If you are using newer Git defaults (main instead of master), adjust the command accordingly.

4. Open the App

   bash

   heroku open


   Or navigate to the URL shown in the output of heroku create.

Debugging and Logs

To view logs and troubleshoot:

This will show real-time logs from your deployed app.

Adding a Database (Optional)

Heroku supports PostgreSQL out of the box. You can add it like this:

Then update your application.conf to use the environment variables provided by Heroku:

Add the Postgres JDBC driver to your build.sbt:

Redeploy your app as usual after making changes.

Common Issues

• Memory errors during build: Scale your dyno or optimize your app’s memory usage.

• Missing SECRET_KEY: Ensure SECRET_KEY is set via heroku config:set.

• Wrong app name in Procfile: Double-check the app folder name matches what’s in the Procfile command.

Continuous Deployment (Optional)

For a more automated workflow, you can link your GitHub repository and enable automatic deployments via the Heroku Dashboard:

1. Go to your app on Heroku.

2. Navigate to Deploy > GitHub.

3. Connect your GitHub account and repository.

4. Enable Automatic Deploys.

Every push to your GitHub branch will trigger a new deployment.

Conclusion

Deploying a Scala Play REST API to Heroku combines the power and flexibility of the JVM ecosystem with the simplicity of cloud-native deployment. By leveraging Heroku’s Java buildpack and Git-based workflows, developers can rapidly move from local development to live production environments with minimal configuration.

This tutorial demonstrated:

• Creating a simple REST API using Play Framework.

• Configuring your Play app to be Heroku-compatible using SBT and the native packager.

• Deploying with Git and managing runtime settings like secret keys and environment variables.

• Extending the setup with optional services like PostgreSQL.

• Troubleshooting common problems and setting up continuous deployment.

With this deployment workflow in place, your team can focus on building features instead of managing infrastructure. Heroku’s platform does the heavy lifting—scaling, monitoring, and securing your app in production—while you enjoy a developer-friendly experience.

So whether you’re building an internal tool, a production microservice, or experimenting with Scala and Play, Heroku is a powerful and cost-effective way to take your API live.