Runtime operations

Runtime operations allow you to trigger one-off commands or scripts on your project. Similar to crons, they run in the app container but not on a specific schedule. You can define runtime operations in your app configuration and trigger them at any time through the Platform.sh CLI.

For example, if you have a static website, you may want to set up a runtime operation to occasionally fetch content from a backend system without having to rebuild your whole app.

You can use runtime operations if you have Grid or Dedicated Gen 3 environments.

Define a runtime operation

To define a runtime operation, add a configuration similar to the following:

operations:
  RUNTIME_OPERATION_NAME:
    role: USER_ROLE
    commands:
      start: COMMAND

When you define a runtime operation, you can specify which users can trigger it according to their user role:

• viewer
• contributor
• admin

If you don’t set the role option when configuring your runtime operation, by default all users with the contributor role can trigger it.

For example, to allow admin users to clear the cache of a Drupal site, you could define an operation like the following:

operations:
    clear-rebuild:
        role: admin
        commands:
            start: drush cache:rebuild

The name of the runtime operation in this case is clear-rebuild.

For more possibilities, see other runtime operation examples.

Run a runtime operation

Once you’ve defined a runtime operation, you can trigger it through the Platform.sh CLI. To do so, run the following command:

platform operation:run RUNTIME_OPERATION_NAME --project PROJECT_ID --environment ENVIRONMENT_NAME

You can only trigger a runtime operation if you have permission to do so. Permissions are granted through the role option specified in the runtime operation configuration.

For example, to trigger the runtime operation defined previously, you could run the following command:

platform operation:run clear-rebuild --project PROJECT_ID --environment ENVIRONMENT_NAME

List your runtime operations

To list all the runtime operations available on an environment, run the following command:

platform operation:list --project PROJECT_ID --environment ENVIRONMENT_NAME

Runtime operation examples

Build your app when using a static site generator

This is because, as its framework is being built, your frontend needs to pull content-related data from your backend’s API (to generate all the static HTML pages your site is to serve). To accomplish this on Platform.sh, where each app goes through a build-deploy pipeline in parallel, your frontend’s build must be delayed until after your backend has fully deployed. It’s often delayed up until the post_deploy hook stage, when the filesystem is read-only.

You can use a runtime operation to trigger the second build step after the initial deployment of your app or after a redeployment. You can also trigger it when you need to fetch content from your backend but want to avoid going through the whole Platform.sh build and deploy processes again.

operations:
    gatsby-build:
        role: viewer
        commands:
            start: gatsby build

platform operation:run gatsby-build --project PROJECT_ID --environment ENVIRONMENT_NAME

operations:
    next-build:
        role: admin
        commands:
            # All below are valid, depending on your setup
            start: next build
            # start: npx next build
            # start: npm run build

platform operation:run next-build --project PROJECT_ID --environment ENVIRONMENT_NAME

Execute actions on your Node.js app

You can define runtime operations for common pm2 process manager tasks.

operations:
    pm2-ping:
        role: admin
        commands:
            start: |
                # Assuming pm2 start npm --no-daemon --watch --name $APP -- start -- -p $PORT
                APP=$(cat package.json | jq -r '.name')
                pm2 ping $APP                

platform operation:run pm2-ping --project PROJECT_ID --environment ENVIRONMENT_NAME

operations:
    pm2-reload:
        role: admin
        commands:
            start: |
                # Assuming pm2 start npm --no-daemon --watch --name $APP -- start -- -p $PORT
                APP=$(cat package.json | jq -r '.name')
                pm2 reload $APP                

platform operation:run pm2-reload --project PROJECT_ID --environment ENVIRONMENT_NAME

operations:
    pm2-restart:
        role: admin
        commands:
            start: |
                # Assuming pm2 start npm --no-daemon --watch --name $APP -- start -- -p $PORT
                APP=$(cat package.json | jq -r '.name')
                pm2 restart $APP                

platform operation:run pm2-restart --project PROJECT_ID --environment ENVIRONMENT_NAME

Define management commands on your Django project

On a Django project, you can define custom django-admin commands, for example to run a one-off management command (manual migration in the example above) outside of the Django ORM migration framework. To do so, define a runtime operation similar to the following:

name: app

type: python:3.9

operations:
    manual-migration:
        role: admin
        commands:
            start: python manage.py manual_migration

To trigger your runtime operation, run a command similar to the following:

platform operation:run manual-migration --project PROJECT_ID --environment ENVIRONMENT_NAME