Getting Started

The open web service Web Runner enables you to run custom code in Eyevinn Open Source Cloud and provides a way to glue other open web services together. Orchestrate media workflows, provide custom webhooks, or deploy a custom web application online, and much more. Deploy your Node application from your public or private GitHub repository and make it instantly available. This tutorial walks you through how to get started deploying your web application with Eyevinn Open Source Cloud.

Prerequisites

• If you have not already done so, sign up for an OSC account.

Create web runner

Navigate to the open web service Web Runner in the OSC web console.

If the source code is on a private GitHub repository you need to first generate a GitHub personal access token and store it in as a service secret in Open Source Cloud first.

To launch your web application click on the tab "My web-runners" and then on the button "Create web-runner".

Enter the URL to your source code. It can be an URL to a GitHub repository or an S3 URL. If your GitHub repository is private you also need to enter a reference to the secret you created.

Instance Settings

Field	Description	Example Value
Name	The name of your Web Runner instance.	guide
SourceUrl	The S3 URL to your source code in a zip file or the URL to your GitHub repository containing the application code. To deploy a specific branch, append #branch-name to the repository URL (e.g. https://github.com/user/repo#develop). If no branch is specified, the default branch is used.	https://github.com/user/repo#develop
GitHubToken	A token used to authenticate access to the GitHub repository (optional).
AwsAccessKeyId	Access Key Id for S3 access (required when source is on S3 bucket).	birme
AwsSecretAccessKey	Secret Access Key for S3 access (required when source is on S3 bucket).	{{secret.secretaccesskey}}
AwsRegion	AWS Region for S3 access.
S3EndpointUrl	S3 Endpoint URL when S3 bucket on on AWS.	https://eyevinnlab-birme.minio-minio.auto.prod.osaas.io
OscAccessToken	(Optional) Access token required if the Web Runner needs to interact with other Eyevinn OSC services.	{{secrets.osctoken}}
ConfigService	(Optional) The name of your Application Config Service instance used to configure the app.	name-of-configure-service-instance

When setting up your instance, you are also able to enter OscAccessToken and ConfigService - these are both optional parameters. OscAccessToken is a personal access token you need to set if the code you want to run in your Web Runner interacts with other Eyevinn Open Source Cloud services. If you wish to set the OscAccessToken, you can locate it in your user settings in Eyevinn Open Source Cloud, under the "API" tab.

If you have created an instance of the Application Config Service and wish to use it to provide configuration for the application in your Web Runner, enter the name you gave the Config Service instance when creating it into the ConfigService field when creating your Web Runner. To learn more about configuring your Web Runner application, see the section below.

When you have entered the settings you want for your Web Runner instance, press "Create", and you will soon have an instance of your application running.

Now you have deployed an instance of your application. This instance will listen to file events on a MinIO bucket and create a VOD transcoding job when a new file is created.

Auto-Injected Environment Variables

OSC automatically injects the following environment variables into your Web Runner app. These are set after parameter store values are loaded, but only if the variable is 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.

Precedence: If you set AUTH_URL or APP_URL in your parameter store, those values take precedence and OSC will not override them. This lets you customize auth routing or use custom domains.

NextAuth/Auth.js users: OSC's auto-injected AUTH_URL is compatible with NextAuth v5 (Auth.js). For NextAuth v4, set NEXTAUTH_URL in your parameter store instead.

Configuring your application

To provide configuration to your application, you can use the Application Config open web service. With this service, you can manage configuration values and get the configuration values through the API it provides.

Provided as Environment Variables

When the Web Runner starts, it will look up an Application Config Service instance with the config service name provided when creating the Web Runner instance. If it is found, it will load the configuration values as environment variables. In the example above, it will add the following environment variables:

AWS_ACCESS_KEY_ID=admin
CHANNELURL=https://eyevinnlab.ce.prod.osaas.io/channels/mychannel/master.m3u8

These are now available in your application code process.env.CHANNELURL.

Manually fetch the config value

To manually fetch a configuration during run time, it can be done by accessing the config service API. Example code below to obtain the URL to a stream that is stored in the config value channelurl provided by the Application Config instance called tvappconfig.

mport { 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;
}

Build Pipeline and Environment Variables

Every time your Web Runner instance starts, it runs the following 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)

The key point is that parameter-store values are available at every step (install, build, and runtime) because they are loaded in Step 2, before anything else runs.

NEXT_PUBLIC_* variables and Next.js apps

In Next.js, NEXT_PUBLIC_* variables are baked into the client bundle at build time. Because OSC loads your App Config values before npm run build runs, you do not need a .env.production file. Set your NEXT_PUBLIC_* values in your App Config Service instance, and they will be present when next build executes and baked into the bundle correctly.

If you update a NEXT_PUBLIC_* value in App Config after your instance is already running, restart the instance so the new value is picked up at build time.

Customizing build and start commands

Web Runner does not provide OSC_BUILD_CMD or OSC_START_CMD environment variables for overriding these commands. The build step is controlled by your package.json: if a build script exists, it runs automatically. The start command is fixed at the container level and always invokes npm start (or the equivalent for your chosen package manager).

To change how your app is built or started, update the scripts section of your package.json in your source repository.

Node.js Version and Package Manager

By default, Web Runner builds and runs your app on Node.js 24.

Choosing a Node.js version

If your package.json declares an engines.node field, Web Runner reads it and, if it names a different major version, switches to that version for install, build, and start. The following Node.js majors are available: 18, 20, 22, and 24 (default). For example:

{
  "engines": {
    "node": "20"
  }
}

will build and run your app on Node.js 20 instead of the default.

If engines.node requests a major that isn't one of 18, 20, 22, or 24, or the field is missing or cannot be parsed, your app runs on the default (Node.js 24).

Using pnpm or yarn

Web Runner also honors Corepack's packageManager field in package.json. If it is set, dependency install, build, and start use that package manager instead of npm:

{
  "packageManager": "pnpm@9.12.0"
}

{
  "packageManager": "yarn@4.5.0"
}

If packageManager is not set, Web Runner installs and runs your app with npm as before.

If your package.json has neither field, which is the case for most existing apps, nothing changes: your app builds and runs on Node.js 24 with npm install / npm run build / npm start.

Changing engines.node or packageManager takes effect on your next restart or rebuild, since these settings are read from your source code at build/start time.

Private npm dependencies

If your application depends on private npm packages (for example a package published on GitHub Packages or a private npm registry), you can already install them today, no platform changes required. Your app's dependencies are installed when the Web Runner container starts, after your Application Config Service values have been loaded into the environment, so any secret you store in your Config Service is available to npm install.

To set this up:

1. Commit an .npmrc file to the root of your repository (or to the sub-folder where your app lives, see below) with a registry-scoped auth line, for example:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

or, for a scoped package hosted on GitHub Packages:

@myscope:registry=https://npm.pkg.github.com/ //npm.pkg.github.com/:_authToken=${NPM_TOKEN}

1. Add NPM_TOKEN (or whatever variable name you used) as a parameter in your Application Config Service instance, and mark it as a secret parameter so it is encrypted at rest. npm will expand ${NPM_TOKEN} from the environment when it installs your dependencies.

Good to know

• Scope the token to a registry. A bare, unscoped _authToken in .npmrc is not valid; npm requires the token to be tied to a specific registry host, as in the examples above.
• A missing variable fails silently, not loudly. If the parameter name in .npmrc doesn't exactly match the name you used in your Config Service, npm doesn't complain about a missing variable. Instead it tries to authenticate with the literal text ${NPM_TOKEN} and the registry rejects it, which looks like a generic 401/authentication error. If your install fails with an auth error, double check the parameter name matches exactly.
• npm is used unless you opt in to pnpm or yarn. By default the Web Runner installs dependencies with npm install, based on your package-lock.json. If you declare a Corepack packageManager field in your package.json (see Node.js Version and Package Manager above), pnpm or yarn is used instead, and their own lockfiles and config files (pnpm-lock.yaml, .yarnrc.yml) are read. Without that field, pnpm/yarn-specific config files are not read and the npm-style .npmrc syntax shown above still applies.
• Using a sub-path (monorepo) deploy? Place the .npmrc file inside the sub-folder where your app actually lives, not the repository root, since that's where npm install runs.

Source Code on S3 bucket

Source code can be packaged into a zip file and uploaded to an S3 bucket. To create the zip file go to the projects directory and run.

% zip -r ../my-app.zip ./

Copy this file to the S3 bucket and then provide S3 URL and access credentials when creating the web runner.

Source Code on a private GitHub repository

Create a GitHub personal access token

To access your GitHub repository, you need to create a GitHub Personal Access Token first.

1. Verify your email address, if it hasn't been verified yet.
2. In the upper-right corner of any page on GitHub, click your profile photo, then click "Settings".
3. In the left sidebar, click "Developer settings".
4. In the left sidebar, under "Personal access tokens", click "Tokens (classic)".
5. Select "Generate new token", then click "Generate new token (classic)".
6. In the "Note" field, give your token a descriptive name.
7. To give your token an expiration, select "Expiration", then choose a default option or click "Custom" to enter a date.
8. Select the scopes you'd like to grant this token. To use your token to access repositories from the command line, select "repo". A token with no assigned scopes can only access public information. For more information, see Scopes for OAuth apps.
9. Click "Generate token" and copy it to the clipboard.

Store token as a Service Secret

Now navigate to the Web Runner service in the Eyevinn Open Source Cloud platform. Click on the tab "Service Secrets" and click on the button "New Secret". Give the secret a name and paste the GitHub token from your clipboard.