Service: Web Runner - EyevinnOSC/community GitHub Wiki
Web Runner (serviceId eyevinn-web-runner) runs a Node.js application from a GitHub repository or from a zip file on S3 in Eyevinn Open Source Cloud. It clones the source, installs dependencies, builds and starts the app, and makes it available at a public URL. It is a long-running service instance. License: MIT.
- Deploy a Node.js web application from a public or private GitHub repository, optionally from a specific branch or sub-directory.
- Deploy from a zip file stored in an S3 bucket, for example on a MinIO instance.
- Glue other open web services together: orchestrate media workflows, provide custom webhooks or run a custom web application.
- Load configuration for the app as environment variables from an Application Config Service instance, including encrypted secret parameters.
- Use Node.js 18, 20, 22 or 24 and npm, pnpm or yarn.
Create the instance with create-service-instance using serviceId: "eyevinn-web-runner" and a config object. The instance name must be alphanumeric and at most 20 characters.
Optional dependencies, to create first if you use them: a MinIO instance (minio-minio) when the source zip file is on S3 (the pack associates S3EndpointUrl with MinIO's internal endpoint), and an Application Config Service instance (eyevinn-app-config-svc) for configuration.
If the source is a private GitHub repository, create a personal access token (see below) and store it with create-service-secret (serviceId: "eyevinn-web-runner"), then reference it as {{secrets.NAME}}.
GitHub source:
{
"name": "guide",
"SourceUrl": "https://github.com/<org>/<repo>#develop",
"GitHubToken": "{{secrets.ghtoken}}"
}GitHubToken is only needed for private repositories. Append #branch-name to deploy a specific branch; otherwise the default branch is used.
S3 source:
{
"name": "guide",
"SourceUrl": "s3://<bucket>/my-app.zip",
"AwsAccessKeyId": "<access-key-id>",
"AwsSecretAccessKey": "{{secrets.secretaccesskey}}",
"S3EndpointUrl": "https://<tenant>-<minio-instance>.minio-minio.auto.prod-se.osaas.io"
}Wait with wait-for-service-ready, then get the URL with describe-service-instance. Use get-logs-for-instance to follow checkout, install and build. Restart with restart-service-instance to rebuild from the current source.
With the OSC CLI:
osc create eyevinn-web-runner myadapter \
-o SourceUrl=https://github.com/EyevinnOSC/basic-auth-adapter \
-o GitHubToken="{{secrets.ghtoken}}" \
-o OscAccessToken="{{secrets.osctoken}}"| Option | Required | Type | Meaning |
|---|---|---|---|
| name | Yes | string | Name of the instance. Alphanumeric, at most 20 characters. |
| SourceUrl | Yes | string | Location of the source code: a GitHub repository URL (https://github.com/org/repo/, with optional #branch-name) or an S3 URL of a zip file with the Node.js application (s3://bucket/app.zip). |
| GitHubToken | No | string, sensitive | GitHub personal access token for cloning private repositories (and to avoid rate limits). Store it as a secret and pass {{secrets.NAME}}. |
| AwsAccessKeyId | No | string, sensitive | Access key id for S3 access. Required when the source is on S3. |
| AwsSecretAccessKey | No | string, sensitive | Secret access key for S3 access. Required when the source is on S3. Store it as a secret and pass {{secrets.NAME}}. |
| AwsRegion | No | string | AWS region of the S3 bucket. |
| S3EndpointUrl | No | string | Custom S3 endpoint URL for S3-compatible storage such as MinIO, for example https://<tenant>-<name>.minio-minio.auto.prod-se.osaas.io. Needed when the S3 source is not on AWS. |
| OscAccessToken | No | string, sensitive | OSC personal access token. Needed if the code in the Web Runner interacts with other OSC services, and required to load configuration from the Application Config Service via ConfigService. Create one on the API Access page (see Finding Your API Token). Store it as a secret. |
| ConfigService | No | string | Name of the Application Config Service instance to load environment variables from. |
| ConfigApiKey | No | string, sensitive | API key for the encrypted parameter store. When set together with OscAccessToken and ConfigService, secret parameters are decrypted before being injected as environment variables. |
| SubPath | No | string | Relative path inside the repository or zip file where the Node.js application is located, for monorepos or apps not in the root. The runner works from that directory for install, build and start. |
| AnalyticsService | No | string | Analytics service setting. The catalog gives no further description. |
Secrets: GitHubToken, AwsAccessKeyId, AwsSecretAccessKey, OscAccessToken and ConfigApiKey are marked sensitive. A {{secrets.NAME}} reference must be the whole field value. Changing a secret later does not restart a running instance; restart it to pick up the new value.
OSC injects these variables into the app after parameter store values are loaded, and only if not already set:
| Variable | Value | Description |
|---|---|---|
APP_URL |
https://{hostname} |
The public URL of your app. Only set if OSC_HOSTNAME is available. |
AUTH_URL |
https://{hostname}/api/auth |
Auth callback URL (useful for NextAuth/Auth.js). Customizable via the AUTH_PATH parameter. |
PORT |
8000 |
The port your app should listen on. |
If you set AUTH_URL or APP_URL in your parameter store, those values take precedence. The auto-injected AUTH_URL is compatible with NextAuth v5 (Auth.js). For NextAuth v4, set NEXTAUTH_URL in your parameter store instead.
Use the Application Config Service to manage configuration values. When the Web Runner starts, it looks up the Application Config Service instance named in ConfigService and loads its values as environment variables. For example, the values AWS_ACCESS_KEY_ID=admin and CHANNELURL=https://eyevinnlab.ce.prod.osaas.io/channels/mychannel/master.m3u8 become available as process.env.CHANNELURL in your code.
To fetch a configuration value at run time, call the config service API. This example gets the value channelurl from the Application Config instance tvappconfig:
import { Context } from "@osaas/client-core";
import { getEyevinnAppConfigSvcInstance } from "@osaas/client-services";
let configUrl: string | undefined = undefined;
export async function getChannelUrl() {
const ctx = new Context();
if (!configUrl) {
const configService = await getEyevinnAppConfigSvcInstance(ctx, 'tvappconfig');
configUrl = configService.url;
}
const response = await fetch(new URL('/api/v1/config/channelurl', configUrl), {
cache: 'no-store'
});
if (response.ok) {
const data = await response.json();
return data.value;
}
return undefined;
}Every time the instance starts it runs these steps in order:
| Step | What happens |
|---|---|
| 1. Source checkout | Clones your repository (or fetches updates if already cloned) |
| 2. App Config fetch | Loads your parameter-store values as environment variables |
| 3. Dependency install | Runs npm install (or pnpm install / yarn install if configured) |
| 4. Build | Runs npm run build if a build script exists in your package.json; also runs npm run build:app if present |
| 5. Start | Starts your app with the container's default start command (npm start) |
Parameter-store values are available at every step (install, build and runtime) because they are loaded in step 2.
NEXT_PUBLIC_ variables in Next.js apps:* these are baked into the client bundle at build time. Because App Config values are loaded before npm run build, you do not need a .env.production file; set the NEXT_PUBLIC_* values in your App Config Service instance. If you change one after the instance is running, restart the instance so it is picked up at build time.
NODE_ENV and tests: install, build and start run with NODE_ENV=production by default. The platform never runs npm test; tests only run during a deploy if one of your own scripts invokes them (the build and build:app scripts, their pre/post hooks, or the preinstall, postinstall and prepare hooks). Dependencies are installed with npm install --include=dev on the npm path. Vitest and Jest only set NODE_ENV=test when it is not already set, so tests expecting the test environment can fail under production. Either keep tests out of the scripts that run during install and build, or set the variable in the test script, for example NODE_ENV=test vitest run (or cross-env). Do not add NODE_ENV=test to your parameter store: it overrides the default for install and build but also applies to the running app.
Build and start commands: Web Runner has no OSC_BUILD_CMD or OSC_START_CMD overrides. The build is controlled by the build script in your package.json, and the start command is fixed to npm start (or the equivalent for your package manager). Change the scripts section of your package.json to change how the app is built or started.
By default Web Runner builds and runs on Node.js 24. If package.json declares engines.node naming a different major, Web Runner switches to it for install, build and start. Available majors are 18, 20, 22 and 24 (default); anything else, or a missing or unparseable field, uses 24.
{ "engines": { "node": "20" } }If Corepack's packageManager field is set, install, build and start use that package manager instead of npm:
{ "packageManager": "[email protected]" }{ "packageManager": "[email protected]" }Changes to engines.node or packageManager take effect at the next restart or rebuild.
Dependencies are installed at container start, after Application Config values are loaded into the environment, so a secret in your Config Service is available to npm install.
-
Commit an
.npmrcwith a registry-scoped auth line to the root of the repository (or the sub-folder of your app)://registry.npmjs.org/:_authToken=${NPM_TOKEN}or for GitHub Packages:
@myscope:registry=https://npm.pkg.github.com/ //npm.pkg.github.com/:_authToken=${NPM_TOKEN} -
Add
NPM_TOKEN(or your own variable name) as a secret parameter in your Application Config Service instance, so it is encrypted at rest.
Good to know:
- Scope the token to a registry host; a bare
_authTokenis not valid. - A missing variable fails silently: if the name in
.npmrcdoes not exactly match the parameter name, npm sends the literal${NPM_TOKEN}and the registry returns a generic 401. - npm is used unless you opt in to pnpm or yarn through
packageManager; without it, pnpm/yarn config files are not read and the.npmrcsyntax above applies. - For a sub-path (monorepo) deploy, place
.npmrcin the sub-folder where the app lives.
Package the project directory into a zip file, copy it to an S3 bucket and give the S3 URL and credentials in SourceUrl, AwsAccessKeyId and AwsSecretAccessKey (and S3EndpointUrl for MinIO).
% zip -r ../my-app.zip ./
Create a GitHub personal access token (classic): in GitHub open Settings, Developer settings, Personal access tokens, Tokens (classic), Generate new token (classic). Give it a descriptive note, an expiration, and the repo scope to access private repositories, then copy the token. Store it with create-service-secret (serviceId: "eyevinn-web-runner") and pass it as GitHubToken set to {{secrets.NAME}}.
- The instance start command is fixed to
npm startand cannot be overridden. - Only Node.js 18, 20, 22 and 24 are available.
- Changes to the source repository are picked up at the next restart or rebuild.