Runtime operations
Back to home
On this page
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 Upsun 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.
Define a runtime operation 
To define a runtime operation, add a configuration similar to the following:
applications:
myapp:
source:
root: "/"
operations:
RUNTIME_OPERATION_NAME:
role: USER_ROLE
commands:
start: COMMANDWhen you define a runtime operation,
you can specify which users can trigger it according to their user role:
viewercontributoradmin
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:
applications:
myapp:
source:
root: "/"
operations:
clear-rebuild:
role: admin
commands:
start: drush cache:rebuildThe name of the runtime operation in this case is clear-rebuild.
For more possibilities, see other runtime operation examples.
Run a runtime operation
First, make sure that you have defined a runtime operation. Then:
- Navigate to the environment where you want to run the operation.
- Click More.
- Click Run runtime operation.
- Select the operation you want to run.
- Click Run.
A runtime operation can be triggered through the Upsun CLI once it has been defined.
Run the following command:
upsun operation:run RUNTIME_OPERATION_NAME --project PROJECT_ID --environment ENVIRONMENT_NAMEYou 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. This can only be done if a runtime operation has been defined.
For example, to trigger the runtime operation defined previously, you could run the following command:
upsun 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:
upsun operation:list --project PROJECT_ID --environment ENVIRONMENT_NAME Runtime operation examples
Build your app when using a static site generator
During every Upsun deployment, a standard build step is run.
When you use a static site generator like Gatsby
or Next.js with a headless backend
you need to run a second build step to get your app ready for production.
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 Upsun, 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 Upsun build and deploy processes again.
Note
The following examples assume that the frontend and backend containers are included in the same environment.
This isn’t necessary for the commands to run successfully.
What is necessary is that the build destination for your frontend is writable at runtime
(meaning, you must define a mount for it).
If you don’t want to include a build within a mount (especially if your data source isn’t on Upsun),
you can use source operations to achieve a similar effect,
but through generating a new commit.
To run the Gatsby build step, define a runtime operation similar to the following:
applications:
# The name of the app container. Must be unique within a project.
myapp:
# The location of the application's code.
source:
root: "myapp"
operations:
gatsby-build:
role: viewer
commands:
start: gatsby buildTo trigger your runtime operation, run a command similar to the following:
upsun operation:run gatsby-build --project PROJECT_ID --environment ENVIRONMENT_NAMETo run the Next.js build step, define a runtime operation similar to the following:
applications:
# The name of the app container. Must be unique within a project.
myapp:
# The location of the application's code.
source:
root: "myapp"
operations:
next-build:
role: admin
commands:
# All below are valid, depending on your setup
start: next build
# start: npx next build
# start: npm run buildTo trigger your runtime operation, run a command similar to the following:
upsun 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.
To ping your Node.js app, define a runtime operation similar to the following:
applications:
# The name of the app container. Must be unique within a project.
myapp:
# The location of the application's code.
source:
root: "myapp"
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 To trigger your runtime operation, run a command similar to the following:
upsun operation:run pm2-ping --project PROJECT_ID --environment ENVIRONMENT_NAMETo reload your Node.js app, define a runtime operation similar to the following:
applications:
# The name of the app container. Must be unique within a project.
myapp:
# The location of the application's code.
source:
root: "myapp"
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 To trigger your runtime operation, run a command similar to the following:
upsun operation:run pm2-reload --project PROJECT_ID --environment ENVIRONMENT_NAMETo restart your Node.js app, define a runtime operation similar to the following:
applications:
# The name of the app container. Must be unique within a project.
myapp:
# The location of the application's code.
source:
root: "myapp"
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 To trigger your runtime operation, run a command similar to the following:
upsun 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:
applications:
myapp:
source:
root: "/"
type: python:3.9
operations:
manual-migration:
role: admin
commands:
start: python manage.py manual_migrationTo trigger your runtime operation, run a command similar to the following:
upsun operation:run manual-migration --project PROJECT_ID --environment ENVIRONMENT_NAME