Skip to content
javahacks.dev
Play Framework

How to Deploy a Play Application With dist and Docker

Package a Play application with sbt dist or a Docker image, set the secret key and allowed hosts, and run it behind a reverse proxy in production.

6 min read
Summarize in AI
Flat illustration of shipping containers stacked on a ship, with the Docker, GitHub Actions and Kubernetes logos.

A Play application deploys as an ordinary JVM process. The checklist is short and every item matters: package it, set a secret, restrict hosts, put a proxy in front, and manage the process. This post follows it on Play 3.0. The server basics are in the Play tutorial, and container advice in writing a Dockerfile for Java the right way.

Package it

Shell
sbt dist

This writes target/universal/<app>-<version>.zip, containing the jars and start scripts. Unzip on the server:

Shell
unzip shop-1.0.zip
cd shop-1.0
bin/shop -Dplay.http.secret.key="$APP_SECRET" -Dhttp.port=9000

The script starts the JVM with the application classpath. Pass JVM options with -J-Xmx512m and Java system properties with -D. Needing only a JDK on the server makes this the simplest route.

The secret key

Play signs session cookies and CSRF tokens with a secret. In dev mode a placeholder is used. In production, Play refuses to start with the default:

Text
Configuration error: play.http.secret.key must be changed from the default in production mode

Generate a long random value (openssl rand -base64 48) and supply it through an environment variable. In application.conf:

Text
play.http.secret.key = ${?APP_SECRET}

Changing the secret invalidates existing sessions, so keep it stable between deploys and the same across all instances.

Allowed hosts

Text
play.filters.hosts.allowed = ["shop.example.test"]

The allowed hosts filter rejects requests whose Host header is not on the list, which protects against host header attacks. If you forget it behind a proxy, Play answers 400 for the real domain, a common surprise after deployment.

Put a reverse proxy in front

Terminate TLS and handle compression at nginx, a load balancer or Caddy. Tell Play to trust the forwarded headers so redirects and secure cookies use the public scheme:

Text
play.http.forwarded.trustedProxies = ["10.0.0.0/8"]

Set only the proxy ranges you control; trusting everything lets any client spoof its address.

A Docker image

The sbt native packager builds an image:

Shell
sbt Docker/publishLocal
docker run -e APP_SECRET=change-me -p 9000:9000 shop:1.0

Check the base image and the exposed port in build.sbt (dockerBaseImage, dockerExposedPorts). For a smaller image, a multi-stage Dockerfile is an alternative, covered in multi-stage builds for Java. Set the container memory limit and let the JVM size its heap from it; see JVM memory in containers.

Process management

Run the application under systemd, a container orchestrator or another supervisor, with restart on failure and a stop signal that lets Play shut down gracefully. Play writes a RUNNING_PID file; if a stale one remains after a crash, the next start refuses to run, so delete it or set -Dpidfile.path=/dev/null.

Logs and health

Play logs through Logback. Configure it to write to standard output in containers. Add a simple health route and use it for the load balancer's checks.

Check the package before you ship it

sbt dist produces a zip with the application and a start script, and inspecting it takes a minute and catches most packaging errors. The unpacked layout is stable: bin/ holds the launch scripts, lib/ the jars and conf/ the configuration.

Shell
sbt dist
unzip -q target/universal/orders-1.0.zip -d /tmp/orders
ls /tmp/orders/orders-1.0 /tmp/orders/orders-1.0/bin
ls /tmp/orders/orders-1.0/lib | wc -l

A missing jar in lib/ means a dependency was marked provided or excluded, and the application will fail at startup in production with a ClassNotFoundException that never appeared in development. Run the packaged application locally, with production settings, before it goes anywhere:

Shell
/tmp/orders/orders-1.0/bin/orders \
  -Dplay.http.secret.key="$(openssl rand -base64 48)" \
  -Dplay.filters.hosts.allowed.0=localhost \
  -Dhttp.port=9000
curl -i localhost:9000/health

If the application refuses to start, the error names the missing setting: Play in production mode requires play.http.secret.key to be set to something other than the development default, and it logs an error saying so. Treat that as the intended safeguard, not as an inconvenience.

Keep secrets and hosts out of the package

The secret key signs sessions and cookies, so a key baked into the zip is shared by every environment that runs it and is exposed to anyone who can read the artifact. Pass it at launch from the environment, read in application.conf with a substitution that has no default:

Text
play.http.secret.key = ${?APPLICATION_SECRET}
play.filters.hosts.allowed = ["orders.example.test", "localhost"]

The optional substitution ${?APPLICATION_SECRET} leaves the key unset if the variable is missing, so the application fails to start instead of running with a weak key. The allowed hosts filter rejects requests whose Host header is not on the list, which blocks host header attacks and the case of someone reaching the service by its raw IP. Behind a reverse proxy, add the public host name, and configure the proxy headers so Play knows the original scheme and address:

Text
play.http.forwarded.trustedProxies = ["10.0.0.0/8"]

A Docker image from the packaged application

The sbt native packager builds the image directly, or you can write the file yourself. A two-stage file keeps the build tools out of the final image and gives a reproducible result.

Dockerfile
FROM eclipse-temurin:25-jdk AS build
WORKDIR /src
COPY . .
RUN ./sbt dist && unzip -q target/universal/orders-1.0.zip -d /out

FROM eclipse-temurin:25-jre
RUN useradd --system --uid 1001 play
WORKDIR /app
COPY --from=build /out/orders-1.0 /app
USER play
EXPOSE 9000
ENV JAVA_OPTS="-XX:MaxRAMPercentage=75"
ENTRYPOINT ["/app/bin/orders", "-Dhttp.port=9000"]

MaxRAMPercentage sizes the heap from the container's memory limit, and the unprivileged user limits what a compromised process can do. Provide the secret at run time with docker run -e APPLICATION_SECRET=... or the orchestrator's secret mechanism, never with ENV in the file, because anything written in an image layer can be read by whoever can pull the image. Add a health route that returns 200 without touching external systems for the liveness probe, and one that checks the database for the readiness probe, and wire them in the orchestrator, so a restart does not depend on a person noticing.

Operating the process

A packaged Play application is a normal Java process, so operate it as one. Run it under a supervisor that restarts it on failure and stops it with a signal that lets it shut down cleanly. Play handles SIGTERM by running its shutdown hooks, stopping the server and waiting for in-flight requests up to play.server.akka.terminationTimeout (named pekko in Play 3). Set the container or unit's stop timeout above that, or the supervisor kills the process mid-request and the graceful shutdown never finishes. Write the process id file somewhere writable, and notice that RUNNING_PID in the application directory prevents a second start: a stale file left after a crash makes the next start fail with a message saying the application is already running. Delete it in the start script only after verifying the process is gone.

Log to standard output in a container and let the platform collect it; write rolling files under a directory outside the application folder otherwise. Keep a consistent field for the request id in every line so that one request can be followed across services.

Where this does not apply

Never use sbt run or sbt start for production. Platform-as-a-service environments use their own packaging; the build produces the same stage output with sbt stage. The Play production documentation and dist documentation are the primary sources.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.