web-runner

Docker container that clones a GitHub repository containing a NodeJS web application. Build and runs the NodeJS application. Available as an open web service in Eyevinn Open Source Cloud.

---

Quick Demo: Open Source Cloud

Run this service in the cloud with a single click.

---

Usage

Build container image:

% docker build -t web-runner:local .

Source code on GitHub

Run container providing a GitHub url and token:

% docker run --rm \
  -e GITHUB_URL=https://github.com/<org>/<repo>/ \
  -e GITHUB_TOKEN=<token> \
  -p 8080:8080 web-runner:local

The web application is now available at http://localhost:8080

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 run container providing S3 URL and access credentials. In this example an S3 bucket on a MinIO server in OSC

% docker run --rm \
  -e SOURCE_URL=s3://code/my-app.zip \
  -e S3_ENDPOINT_URL=https://eyevinnlab-birme.minio-minio.auto.prod.osaas.io \
  -e AWS_ACCESS_KEY_ID=<username> \
  -e AWS_SECRET_ACCESS_KEY=<password> \
  -p 8080:8080 web-runner:local

The web application is now available at http://localhost:8080

Environment Variables

Variable	Required	Description
GITHUB_URL	Yes*	HTTPS URL to the GitHub repository to clone. Deprecated alias for SOURCE_URL.
SOURCE_URL	Yes*	URL to the source code. Accepts HTTPS git URLs (any host) or s3://bucket/path.zip.
GIT_TOKEN	No	Personal access token for cloning private repositories. Preferred over GITHUB_TOKEN.
GITHUB_TOKEN	No	Alias for GIT_TOKEN (kept for backward compatibility).
OSC_ACCESS_TOKEN	No	Service access token issued by Eyevinn OSC. Required when CONFIG_SVC is set to load environment variables from the Application Config Service.
CONFIG_API_KEY	No	API key for encrypted parameter store. When set alongside OSC_ACCESS_TOKEN and CONFIG_SVC, secret parameters are decrypted before being injected as environment variables.
CONFIG_SVC	No	Name of the Application Config Service parameter store to load environment variables from.
OSC_ENV	No	OSC environment (prod, stage, dev). Defaults to prod. Affects which token and config service endpoints are used.
OSC_HOSTNAME	No	Public hostname of the running container. Used to set APP_URL and AUTH_URL automatically when those variables are not explicitly set.
SUB_PATH	No	Relative path within the cloned repository to use as the working directory (for monorepos).
APP_URL	No	Override for the application base URL. Defaults to https://$OSC_HOSTNAME when OSC_HOSTNAME is set.
AUTH_URL	No	Override for the authentication endpoint URL. Defaults to https://$OSC_HOSTNAME/api/auth.
AUTH_PATH	No	Path suffix appended to OSC_HOSTNAME to form AUTH_URL. Used when the auth endpoint is not at /api/auth.
S3_ENDPOINT_URL	No	Custom S3-compatible endpoint URL (e.g. MinIO). Required when SOURCE_URL points to a non-AWS S3 bucket.
AWS_ACCESS_KEY_ID	No	Access key ID for S3 source downloads.
AWS_SECRET_ACCESS_KEY	No	Secret access key for S3 source downloads.

* Either GITHUB_URL or SOURCE_URL must be set.

Environment Variables at Build Time

Environment variables from the Application Config Service are loaded before npm install and npm run build. This means they are available at both build time and runtime.

For frameworks like Next.js that require environment variables during the build step (e.g. NEXT_PUBLIC_*), set them in your Application Config Service parameter store and they will be embedded in the build output automatically.

Private npm dependencies

Dependency installation (npm install) runs in docker-entrypoint.sh at container start, after Application Config Service values have been exported into the environment. This means private npm packages already work with no extra runner support: commit an .npmrc with a registry-scoped token, and provide the token value via the Application Config Service (as a secret parameter) or via env vars for local docker run usage.

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

or for GitHub Packages:

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

Notes:

• Tokens must be registry-scoped (//host/path/:_authToken=); a bare unscoped token is invalid.
• An unresolved ${VAR} is not treated as an error by npm, it's passed through literally and the registry will reject it as an auth failure (401), not a "missing variable" error. Double check the name matches the parameter/env var exactly.
• Only npm install is run against package-lock.json; pnpm/yarn-specific auth files are not read, use npm's .npmrc syntax regardless of your local package manager.
• With SUB_PATH set, place .npmrc inside the sub-path directory, since that's where npm install runs. The runner also writes config values to .env.osc in that directory, but that file is not consulted by npm.

Node version and package manager detection

The container defaults to Node.js 24 and npm, but honors two standard fields in the deployed app's package.json:

• engines.node — if the declared major version differs from the image default, the container switches to a bundled alternate Node major (18, 20, or 22) before installing and building. If the requested major isn't bundled, or the field can't be parsed, the image default is used.
• packageManager (the Corepack field, e.g. "pnpm@9.12.0" or "yarn@4.5.0") — when present, pnpm or yarn is used for install/build/start instead of npm. When absent, behavior is unchanged: npm install --include=dev and npm run build/build:app as before.

Contributing

See CONTRIBUTING

License

This project is licensed under the MIT License, see LICENSE.

Support

Join our community on Slack where you can post any questions regarding any of our open source projects. Eyevinn's consulting business can also offer you:

• Further development of this component
• Customization and integration of this component into your platform
• Support and maintenance agreement

Contact sales@eyevinn.se if you are interested.

About Eyevinn Technology

Eyevinn Technology is an independent consultant firm specialized in video and streaming. Independent in a way that we are not commercially tied to any platform or technology vendor. As our way to innovate and push the industry forward we develop proof-of-concepts and tools. The things we learn and the code we write we share with the industry in blogs and by open sourcing the code we have written.

Want to know more about Eyevinn and how it is to work here. Contact us at work@eyevinn.se!