Deploying on PipeOps is seamless. The platform detects your app’s language, applies the appropriate buildpack, and launches your application using a default command. But sometimes, your app builds successfully, yet fails to deploy.
When deploying your app, one challenge you may face is not specifying how it should start. In most cases, this issue can be resolved by adding a simple Procfile to the root of your project. This guide explains what a Procfile is and how it helps fix deployment issues.
Using a Procfile to Define the Start Command
PipeOps uses buildpacks to automate language detection, dependencies, and start commands. However, buildpacks depend on standard project layouts. If your app deviates from that structure, like missing a start script, the build may succeed while the deployment phase fails.
A Procfile gives you full control over how your application is started. It overrides the default start command provided by the buildpack and lets you specify exactly what should run when your app boots.
This method is not limited to any single language. It works with Node.js, Go, Python, Java, Rust, and more.
What Is a Procfile?
A Procfile is a plain text file, named exactly Procfile (no file extension), placed in the root of your project.
Each line defines a process type and the command to run:
<process type>: <command>
process type: this is an alphanumeric name for your command, such as web.
command: this indicates the command the process type should execute on startup.
How to Create a Procfile
- In the root directory of your project, create a file called:
Procfile
Note that:
- It must be named exactly Procfile (case-sensitive, no .txt or .conf)
- It must be in the root, as it won't be detected from subfolders
- Inside the file, write the process type and start command:
web: <your-app-start-command>
Example:
For a Java Spring Boot application with an executable JAR file named app.jar in the target/ directory, the Procfile might look like:
web: java -jar target/app.jar
How this Works with PipeOps Buildpacks
When you deploy on PipeOps using the Recommended Build Method, here’s what happens:
-
PipeOps detects your app language via a buildpack.
-
It uses the buildpack’s default start command.
-
If a Procfile is present, your custom command takes precedence.
-
Your app runs as defined, giving you full control.
This makes the Procfile a powerful override mechanism.
Summary
A Procfile is not generally required to deploy applications as the platform automatically detects the app’s language and creates a default web process type to start the application server. However, including an explicit Procfile provides greater control and flexibility over how your app runs.