Application Lifecycle
This page describes the four app types, the dev to staging to prod workflow with and without Git, how to promote and verify changes, and the write access rules for staging and preview apps.
Application Types
An OpenRun application can be one of four types:
| Type | Purpose |
|---|---|
| Development Apps | Used for developing apps, supports live reload from code changes on disk. |
| Production Apps | For production use. Can be created from Git-hosted source or from sources on local disk. |
| Staging Apps | For reviewing code and config changes before they are pushed to prod. Every prod app has one staging app. |
| Preview Apps | For creating a review environment for code changes, useful as part of code review. |
Lifecycle without Git
If not using git, a workflow would be:
- Create a dev mode app, like
openrun app create --dev --approve ~/myappcode /myapp_dev - Create a prod mode app, like
openrun app create --approve ~/myappcode /myapp - As code changes are saved to disk, the changes are immediately live at
https://localhost:25223/myapp_dev - When code is in a stable state, run
openrun app reload /myapp. This updates the staging app with the most recent code from the~/myappcodefolder. - The staging app is available at
https://stage.localhost:25223/myappfor verification. - To promote the code to prod, run
openrun app promote /myapp. The staged code is promoted to prod, live athttps://localhost:25223/myapp.
Having a staging environment helps catch code and config issues before the changes are live on prod. OpenRun implements versioning for prod apps, even when source is not from git.
Lifecycle With Git
If using git, a workflow would be:
- Create a dev mode app on the dev machine, like
openrun app create --dev --approve ~/myappcode /myapp_dev - Create a prod mode app on the prod server, like
openrun app create --approve github.com/myorg/repo /myapp - As code changes are saved to disk, the changes are immediately live at
https://localhost:25223/myapp_dev - When code is in a stable state, check in the dev code to git.
- Run
openrun app reload /myapp. This updates the staging app with the most recent code from themainbranch in git. - The staging app is live at
https://stage.localhost:25223/myapp. Verify the functionality of the staging app. - To promote the code to prod, run
openrun app promote /myapp. The staged code is promoted to prod, live athttps://localhost:25223/myapp.
To avoid the need to manually reload, set up a sync job which automatically updates existing apps and creates new apps.
Development Apps
Development mode apps are used for developing or updating OpenRun apps. The source for these apps has to be on local disk, it cannot be git. Any code or config changes are live reloaded immediately for dev apps. To create a dev mode app, add the --dev option to the app create command. For example,
openrun app create --dev --approve /home/user/mycode /myappProduction Apps
Without the --dev option, apps are created as production apps by default. Production apps can be created from Git sources or from local disk. In either case, the source code for the app is uploaded to the OpenRun metadata database. For example:
openrun app create --approve /home/user/mycode example.com:/creates a production app.
- After app creation, the original source location is not read until an
app reloadoperation is done to update the sources. - The source folder
/home/user/mycodecan be deleted if reload is not required, since the sources are present in the OpenRun metadata database. - Every production app automatically has one staging app associated with it.
Staging Apps
Staging apps are created for each production app, to verify config and code changes before they are made live in the prod app. For example, after the previous app create command, a call to app list with the --internal option will show two apps:
openrun app list --internal
Name Type Ver Auth AppPath
mycode PROD 1 NONE example.com:/
mycode STG 1 NONE stage.example.com:/The second app is the staging app for the first. app list shows only the main apps by default, the --internal option makes it show the linked apps.
By default, the staging app uses a staging subdomain (system.default_stage_domain, default stage) and the same path as the production app. So for an app at https://example.com/, the staging URL is https://stage.example.com/. For an app at https://example.com/utils/app1, the staging app URL is https://stage.example.com/utils/app1. For an app on its own subdomain, the stage label goes after the app’s label: the staging URL for https://app1.example.com/ is https://app1.stage.example.com/.
The staging location can be changed when creating the app. The server default is configured with system.stage_at. See staging domain for how the location is derived and the DNS and certificate setup for it.
app create option | Staging location |
|---|---|
--stage-at domain_suffix | The default. The stage label goes after the first label of the app’s domain: app1.stage.example.com for app1.example.com, stage.example.com for example.com |
--stage-at domain | The stage label goes in front of the app’s domain: stage.app1.example.com for app1.example.com. This was the default before domain_suffix, use it to keep that shape |
--stage-at path | The older path based location, where _cl_stage is suffixed to the production path |
--stage-at <domain> | The staging app is put on the specified domain |
The staging location is set when the app is created and does not change afterwards.
Promoting Changes
When there are code changes, running app reload will update the staging environment.
openrun app reload example.com:/
Reloaded apps: stage.example.com:/
1 app(s) reloaded, 0 app(s) approved, 0 app(s) promoted.The staging app is version 2 now, prod app is still at version 1.
openrun app list -i
Name Type Ver Auth AppPath
mycode PROD* 1 NONE example.com:/
mycode STG 2 NONE stage.example.com:/At this point, going to https://stage.example.com/ will show the updated code while https://example.com/ has not been updated.
* next to PROD indicates that there are staged changes waiting to be promoted to PROD.To promote the changes to prod, run app promote
openrun app promote example.com:/
Promoting example.com:/
1 app(s) promoted.The prod app is at the same version as the staging app now
openrun app list -i
Name Type Ver Auth AppPath
mycode PROD 2 NONE example.com:/
mycode STG 2 NONE stage.example.com:/app reload option | Effect |
|---|---|
--approve | Approve new permissions required by the code change. Without it, the reload fails if new permissions are required |
--promote | Promote the staged changes to prod in the same step |
--verify | Check that the reloaded app container starts successfully before promotion |
To reload, approve and promote in one step, run openrun app reload --approve --promote example.com:/. To verify before promoting:
openrun app reload --verify --promote example.com:/- For production apps, reload updates the staging app first. With
--verify, OpenRun reloads the staging container during verification. - If
--promoteis also set, the prod container is verified before promotion completes. - If verification fails for any matched app, the reload operation fails and the staged changes are not promoted.
--dry-rundoes not start containers, so verification is skipped in dry-run mode.
GitHub Reload
OpenRun supports GitHub, GitLab and other Git hosts, as well as local disk sources. The rules for fetching source code are:
- Sources starting with
http://,https://orgit@, and host paths such asgithub.com/org/repo, are treated as Git sources. Paths starting with/,.or~are local to the OpenRun server. See Git configuration for authentication and host-specific URL formats. - If OpenRun client and server are on different machines and local disk is being used, the code needs to be copied to the server node first.
- For GitHub source, the format is https://domain_name/org_name/repo_name/sub/folder, like
github.com/openrundev/openrun/examples/disk_usage. The sub_folder should contain theapp.starconfig file. - During
app createandapp reload, the commit id takes precedence over the branch name if both are specified. - During
app reload, if no branch and commit are specified, the newest code is checked out from the current branch.mainis used as current branch if no branch was previously specified for the app.
Preview Apps
Preview allows the creation of any number of linked preview apps for a main app. This is supported for apps created from Git sources. The commit id to use needs to be specified when creating the preview. For example,
openrun preview create 49182d4ca1cacbd8e3463a77c2174a6da1fb66c9 /myappcreates an app accessible at /myapp_cl_preview_49182d4ca1cacbd8e3463a77c2174a6da1fb66c9 which runs the app code in the specified commit id.
Preview apps cannot be changed once they are created. If a preview app requires new permissions, add the --approve option to the preview create command.
Write Mode Access
Staging and preview apps allow approved WRITE plugin calls by default. Plugin permissions and server-level restrictions still apply in either mode.
| Setting | Default | Meaning |
|---|---|---|
security.stage_enable_write_access | true | Whether new staging apps allow approved WRITE plugin calls |
security.preview_enable_write_access | true | Whether new preview apps allow approved WRITE plugin calls |
To create new apps with read-only staging and preview plugin access, set both options to false in openrun.toml.
How calls are classified: in read-only mode, only calls classified as READ are permitted.
- The HTTP plugin classifies GET/OPTIONS/HEAD as READ and POST/PUT/DELETE/PATCH as WRITE.
- The Exec plugin classifies
runas WRITE because the command may modify data. - Where the plugin defines an API as WRITE, the app permission can override the default type and define the operation to be a READ operation. For example, the disk_usage app runs the
ducommand, which is a read operation. The app config defines the run plugin call astype="READ", over-riding the default WRITE type defined in the plugin. If no type is specified in the permission, the type defined in the plugin takes effect.
Changing existing apps: these settings apply immediately and are not staged. Change all to the desired app glob pattern.
| Command | Effect |
|---|---|
openrun app settings stage-write-access false all | Restrict existing staging apps to READ calls |
openrun app settings preview-write-access false all | Restrict existing preview apps to READ calls |
openrun app settings preview-write-access true example.com:/ | Allow WRITE operations for the existing preview apps and any new preview apps created for example.com:/, if the permissions have been approved |
Use true to allow approved WRITE calls again.
Proxied apps: for Starlark apps these controls apply to plugin calls. For proxied (containerized) apps, a staging or preview app without write access refuses every proxied request whose method is not GET, HEAD or OPTIONS with 403; MCP calls authenticated with a bearer token are governed by RBAC and the app’s tool scopes instead. The container itself and its database are not made read-only. Use separate staging credentials and appropriately restricted service bindings to control database access.