Procfile

This section explains how to use a Procfile to define and customize the launch processes for your applications on monolayer.

About Procfile Processes

A Procfile is a text file placed at the root of your application that maps process types to specific shell commands. monolayer reads this file during the build detection phase and registers the parsed commands as launch processes for your application.

To ensure proper detection of your processes, you must satisfy the following requirements:

• Exact file naming: The file name must be exactly Procfile with a capitalized 'P' and no file extension.
• Location: You must place the Procfile at the absolute root of your application directory. Files in subdirectories, files with extensions, or files with lowercase names (such as procfile) are not detected.

Procfile Syntax

Each line in your Procfile must follow the format below:

<process-type>: <command>

Your process types can contain letters, numbers, underscores (_), and hyphens (-). The process type must start at the beginning of the line. Leading whitespace before the process type is invalid.

The build system ignores blank lines and comment lines. Comment lines must begin with a # character. If you define the same process type multiple times, the last command defined in the file takes precedence.

Consider the following examples:

# The last migrateDatabase command defined takes precedence.
migrateDatabase: npm run db:migrate-old
migrateDatabase: npm run db:migrate

Procfile commands run through a shell environment. You can use compound commands and environment variable interpolation.

bootstrap: node scripts/bootstrap.js --env "$DEPLOY_ENV"

Lifecycle Processes to Configure

You can define specific processes in your Procfile to orchestrate various lifecycle events during deployment and runtime. monolayer automatically recognizes and manages the following special processes:

• bootstrap: Use this process to run initialization scripts or setup tasks (such as seeding initial data) when your application environment is set up (only once).

  bootstrap: _your-command_

• beforeRollout: Use this process to run actions immediately before rolling out the new deployment version of your application.

  beforeRollout: _your-command_

• afterRollout: Use this process to run secondary actions immediately after a successful application rollout (such as notifying Slack channels or warming up caches).

  afterRollout: _your-command_

• createDatabase: Use this process to define custom database creation commands. monolayer executes this command during the initial environment deployment (only once).

  createDatabase: _your-command_

• migrateDatabase: Use this process to define custom database schema migrations. monolayer executes this command during every deployment before the new application version is served.

  migrateDatabase: _your-command_

Supported Framework Integrations

The following table lists how different framework integrations handle Procfile processes:

Database Processes

When monolayer detects PostgreSQL usage, the system adds database process types automatically.

The createDatabase and migrateDatabase processes are non-default launch processes.

For React Router applications, monolayer adds database processes when PostgreSQL is active:

• If your package.json contains a db:create script, createDatabase runs your package manager's db:create command.
• If your package.json lacks db:create but contains a db:migrate script, createDatabase runs your package manager's db:migrate command.
• If your package.json contains a db:migrate script, migrateDatabase runs your package manager's db:migrate command.

For Python applications, monolayer adds database processes when PostgreSQL is active and an alembic.ini file exists:

• The createDatabase process runs alembic upgrade head.
• The migrateDatabase process runs alembic upgrade head.

If your Python application has a root Procfile, monolayer skips its automatic entrypoint heuristics, including database process contributions. You must define createDatabase and migrateDatabase in your Procfile if you require those processes for a Python application with a Procfile.

Procfile Examples

Review the following examples to customize your Procfile with lifecycle processes for your applications.

Listing 5-1 demonstrates defining the bootstrap process to run setup tasks or seed databases when your application starts up.

bootstrap: node scripts/seed.js

Listing 5-2 demonstrates defining the migrateDatabase process to execute schema migrations on every deployment.

migrateDatabase: npm run db:migrate

Listing 5-3 demonstrates configuring the beforeRollout process to run preparation tasks immediately before deploying the new version.

beforeRollout: node scripts/prepare-assets.js

Listing 5-4 demonstrates defining custom database creation with createDatabase and rollout notification tasks with afterRollout.

createDatabase: npm run db:create
afterRollout: node scripts/notify-slack.js

Listing 5-5 demonstrates combining multiple lifecycle processes in a single Procfile.

bootstrap: node scripts/seed.js
beforeRollout: node scripts/pre-deploy.js
afterRollout: node scripts/post-deploy.js
createDatabase: npm run db:create
migrateDatabase: npm run db:migrate