{"id":18981896,"url":"https://github.com/nodeshift/nodeshift","last_synced_at":"2025-04-05T17:09:06.886Z","repository":{"id":21019890,"uuid":"91605649","full_name":"nodeshift/nodeshift","owner":"nodeshift","description":"CLI application for OpenShift Node.js deployment 🚀 ","archived":false,"fork":false,"pushed_at":"2024-04-05T22:05:06.000Z","size":5481,"stargazers_count":82,"open_issues_count":25,"forks_count":29,"subscribers_count":10,"default_branch":"main","last_synced_at":"2024-04-14T21:54:10.717Z","etag":null,"topics":["cli","deployment","devops","docker","imagestreams","kubernetes","nodejs","openshift"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nodeshift.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2017-05-17T18:01:37.000Z","updated_at":"2024-04-11T14:43:39.000Z","dependencies_parsed_at":"2023-02-18T01:01:22.933Z","dependency_job_id":"3fae131e-00df-4668-b60f-5a36096c2a9a","html_url":"https://github.com/nodeshift/nodeshift","commit_stats":{"total_commits":574,"total_committers":19,"mean_commits":"30.210526315789473","dds":0.426829268292683,"last_synced_commit":"f63437e14c918056aafeec259d02f83bd361dd39"},"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fnodeshift","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fnodeshift/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fnodeshift/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nodeshift%2Fnodeshift/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nodeshift","download_url":"https://codeload.github.com/nodeshift/nodeshift/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","deployment","devops","docker","imagestreams","kubernetes","nodejs","openshift"],"created_at":"2024-11-08T16:11:38.533Z","updated_at":"2025-04-05T17:09:06.864Z","avatar_url":"https://github.com/nodeshift.png","language":"JavaScript","readme":"# Nodeshift\n\n![Node.js CI](https://github.com/nodeshift/nodeshift/workflows/Node.js%20CI/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/github/nodeshift/nodeshift/badge.svg?branch=main)](https://coveralls.io/github/nodeshift/nodeshift?branch=main)\n\n## What is it\n\nNodeshift is an opinionated command line application and programmable API that you can use to deploy Node.js projects to OpenShift and Kubernetes(minikube).\n\n## Prerequisites\n\n* Node.js - version 18.x or greater\n\n## Install\n\nTo install globally: `npm install -g nodeshift`\n\nUse with npx: `npx nodeshift`\n\nor to use in an npm script\n\n    npm install --save-dev nodeshift\n\n    // inside package.json\n    scripts: {\n      nodeshift: nodeshift\n    }\n\n    $ npm run nodeshift\n\n## Core Concepts\n\n### Commands \u0026 Goals\n\nBy default, if you run just `nodeshift`, it will run the `deploy` goal, which is a shortcut for running `resource`, `build` and `apply-resource`.\n\n**login** - will login to the cluster\n\n**logout** - will logout of the cluster\n\n**resource** - will parse and create the application resources files on disk\n\n**apply-resource** - does the resource goal and then deploys the resources to your running cluster\n\n**build** - archives the code, creates a build config and imagestream and pushes the binary to the cluster\n\n**deploy** -  a shortcut for running `resource`, `build` and `apply-resource`\n\n**undeploy** - removes resources that were deployed with the apply-resource command\n\n\n### Using Login and Logout\n\nBy default, the Nodeshift CLI will look for a kube config in `~/.kube/config`.  This is usually created when a user does an `oc login`,  but that requires the `oc` to be installed and the extra step of running the `oc login` command.  The Nodeshift CLI allows you to pass a username/password or a valid auth token along with the clusters API server address to authenticate requests without the need to run `oc login` first.\n\nWhile these parameters can be specified for each command, the `nodeshift login` command helps to simplify that.  You can now run `nodeshift login` with the parameters mentioned to first login, then run the usual `nodeshift deploy` without neededing to add the flags.\n\nCLI Usage - Login:\n\n```\n$ nodeshift login --username=developer --password=password --server=https://api.server\n\nor\n\n$ nodeshift login --token=12345 --server=https://api.server\n```\n\nCLI Usage - Logout\n\n```\n$ nodeshift logout\n```\n\nAPI usage using async/await would look something like this:\n\n```\nconst nodeshift = require('nodeshift');\n\nconst options = {\n  username: 'kubeadmin',\n  password: '...',\n  server: '...',\n  insecure: true\n};\n\n(async () =\u003e {\n  await nodeshift.login(options);\n  await nodeshift.deploy();\n  await nodeshift.logout();\n})();\n```\n\n### `.nodeshift` Directory\n\nThe `.nodeshift` directory contains your resource fragments.  These are `.yml` files that describe your services, deployments, routes, etc.  By default, nodeshift will create a `Service` and `Deployment` in memory, if none are provided.  A `Route` resource fragment should be provided or use the `expose` flag if you want to expose your application to the outside world.\n\nFor kubernetes based deployments,  a `Service` and `Deployment` will be created by default, if none are provided.  The `Service` is of a `LoadBalancer` type, so no `Ingress` is needed to expose the application.\n\n### Resource Fragments\n\nOpenShift resource fragments are user provided YAML files which describe and enhance your deployed resources.  They are enriched with metadata, labels and more by nodeshift.\n\nEach resource gets its own file, which contains some skeleton of a resource description. Nodeshift will enrich it and then combine all the resources into a single openshift.yml and openshift.json(located in ./tmp/nodeshift/resource/).\n\nThe resource object's `Kind`, if not given, will be extracted from the filename.\n\n### Enrichers\n\nEnrichers will add things to the resource fragments, like missing metadata and labels.  If your project uses git, then annotations with the git branch and commit hash will be added to the metadata.\n\nDefault Enrichers will also create a default Service and Deployment when none are provided.\n\nThe default port value is 8080, but that can be overridden with the `--deploy.port` flag.\n\nYou can also override this value by providing a .nodeshift/deployment.yaml resource file\n\n\n#### Resource Fragment Parameters\n\nSome Resource Fragments might need to have a value set at \"run time\".  For example, in the fragment below, we have the `${SSO_AUTH_SERVER_URL}` parameter:\n\n        apiVersion: v1\n        kind: Deployment\n        metadata:\n            name: nodejs-rest-http-secured\n        spec:\n          template:\n            spec:\n              containers:\n                - env:\n                  - name: SSO_AUTH_SERVER_URL\n                    value: \"${SSO_AUTH_SERVER_URL}\"\n                  - name: REALM\n                    value: master\n\nTo set that using nodeshift, use the `-d` option with a KEY=VALUE, like this:\n\n    nodeshift -d SSO_AUTH_SERVER_URL=https://sercure-url\n\n\u003c!-- For more on writing openshift templates, [see here](https://docs.openshift.org/latest/dev_guide/templates.html#writing-templates) --\u003e\n\n### Project Archive\n\nA user can specify exactly what files would like nodeshift to include to the archive it will generate by using the files property in package.json.\n\nIf a user does not use the files property in the package.json to filter what files they would like to include, then nodeshift by default will include everything except the **node_modules**, **.git** and **tmp** directories.\n\nNodeshift will also look for additional exclusion rules at a .gitignore file if there is one. Same thing with a .dockerignore file.\n\nIf both ignore files are present,  nodeshift will union them together and use that.\n\n### API\n\nAlong with the command line, there is also a public API.  The API mirrors the commands.\n\nAPI Docs - https://nodeshift.github.io/nodeshift/\n\n* resource\n\n* applyResource\n\n* build\n\n* deploy\n\n* undeploy\n\nOptions that you can specify on the command line, can also be passed as an options object to the API\n\nAll methods are Promise based and will return a JSON object with information about each goal that is run.\n\nFor example, if the `deploy` method was run, it would return something similar:\n\n    {\n        build: {\n            ... // build information\n        },\n        resources: [\n            ... // resources created\n        ],\n        appliedResources: [\n            ... // resources that were applied to the running cluster\n        ]\n    }\n\n#### Example Usage\n```javascript\nconst nodeshift = require('nodeshift');\n\n// Deploy an Application\nnodeshift.deploy().then((response) =\u003e {\n    console.log(response);\n    console.log('Application Deployed')\n}).catch((err) =\u003e {\n    console.log(err);\n})\n````\n_please note: Currently, once a route, service, deployment, deployment config, build config, and imagestream config are created, those are re-used. The only thing that changes from deployment to deployment is the source code.  For application resources, you can update them by undeploying and then deploying again.  BuildConfigs and Imagestreams can be re-created using the --build.recreate flag_\n\n#### Using with Kubernetes\n\nNodeshift can deploy Node.js applications to a Kubernetes Cluster using the `--kube` flag.\n\nThere are 2 options that can be passed.  `minikube` or `docker-desktop` . Passing just the `--kube` flag will default to minikube\n\nNodeshift expects that your code has a Dockerfile in its root directory.  Then deploying to kubernetes is as easy as running:\n\n`npx nodeshift --kube=minikube`\n\nNote on Minikube: This connects to Minikubes docker server, create a new container and then deploy and expose that container with a `Deployment` and `Service`\n\nTo learn more about [minikube](https://minikube.sigs.k8s.io/docs/start/).\n\nTo learn more about [docker-desktop](https://docs.docker.com/desktop/kubernetes/).\n\n\n#### Openshift Rest Client Configuration\n\nNodeshift uses the [Openshift Rest Client](https://github.com/nodeshift/openshift-rest-client) under the hood to make all REST calls to the cluster.  By default, the rest client will look at your `~/.kube/config` file to authenticate you.  This file will be created when you do an `oc login`.\n\nIf you don't want to use `oc` to login first, you can pass in a username, password, and the server of the cluster to authenticate against.  If you are using a cluster with a self-signed certificate(like code ready containers), then you will need to add the `insecure` flag.\n\nAlso note, that when accessing the cluster this way,  the namespace will default to `default`.  If you need to target another namespace,  use the `namespace.name` flag.  Just make sure the user you use has the appropriate permissions.\n\nAn example of this might look something like this:\n\n`npx nodeshift --username developer --password developer --server https://apiserver_for_cluster --insecure --namespace.name nodejs-examples`\n\nYou can also pass in a valid auth token using the `token` flag.  If both a token and username/password is specified,  the token will take the preference.\n\n`npx nodeshift --token 123456789  --server https://apiserver_for_cluster --insecure --namespace.name nodejs-examples`\n\n## Advanced Options\n\nWhile nodeshift is very opinionated about deployment parameters, both the CLI and the API accept options that allow you to customize nodeshift's behavior.\n\n#### version\nOutputs the current version of nodeshift\n\n#### projectLocation\nChanges the default location of where to look for your project. Defaults to your current working directory(CWD)\n\n#### configLocation\nThis option is passed through to the [Openshift Rest Client](https://www.npmjs.com/package/openshift-rest-client).  Defaults to the `~/.kube/config`\n\n#### token\nAuth token to pass into the openshift rest client for logging in with the API Server.  Overrides the username/password\n\n#### username\nusername to pass into the openshift rest client for logging in with the API Server.\n\n#### password\npassword to pass into the openshift rest client for logging in with the API Server.\n\n#### server\nserver to pass into the openshift rest client for logging in with the API Server.\n\n#### apiServer - Deprecated\nUse server instead. apiServer to pass into the openshift rest client for logging in with the API Server.\n\n#### insecure\nflag to pass into the openshift rest client for logging in with a self signed cert.  Only used with apiServer login.  default to false.\n\n#### forceLogin\nForce a login when using the apiServer login.  Only used with apiServer login.  default to false\n\n#### imageTag\nSpecify the tag of the docker image or image stream to use for the deployed application. defaults to latest.\nFor docker images these version tags correspond to the RHSCL tags of the [ubi8/nodejs s2i images](https://access.redhat.com/containers/#/registry.access.redhat.com/ubi8/nodejs-14)\n\n#### dockerImage\nSpecify the s2i builder image of Node.js to use for the deployed applications.  Defaults to [ubi8/nodejs s2i images](https://access.redhat.com/containers/#/registry.access.redhat.com/ubi8/nodejs-14)\n\n#### imageStream\nSpecify the image stream from which to get the s2i image of Node.js to use for the deployed application. If not specified defaults to\nusing a docker image instead.\n\n#### resourceProfile\nDefine a subdirectory below .nodeshift/ that indicates where OpenShift resources are stored\n\n#### outputImageStream\nThe name of the ImageStream to output to.  Defaults to project name from package.json\n\n#### outputImageStreamTag\nThe tag of the ImageStream to output to. Defaults to latest\n\n#### quiet\nsuppress INFO and TRACE lines from output logs.\n\n#### expose\noptions to create a default route, if non is provided.  Defaults to false\n\n#### removeAll\noption to remove builds, buildConfigs and Imagestreams.  Defaults to false - **Only for the `undeploy` Command**\n\n#### deploy.port\nFlag to update the default ports on the resource files. Defaults to 8080\n\n#### deploy.env\nFlag to pass deployment/deploymeny config environment variables as NAME=Value.  Can be used multiple times.  ex: `nodeshift --deploy.env NODE_ENV=development --deploy.env YARN_ENABLED=true`\n\n#### build.recreate\nFlag to recreate a BuildConfig or Imagestream.  Defaults to false. Choices are \"buildConfig\", \"imageStream\", false, true.  If true, both are re-created\n\n#### build.forcePull\nFlag to make your BuildConfig always pull a new image from dockerhub.  Defaults to false\n\n#### build.incremental\nFlag to perform incremental builds(if applicable), which means it reuses artifacts from previously-built images. Defaults to false\n\n#### build.env\nFlag to pass build config environment variables as NAME=Value.  Can be used multiple times.  ex: `nodeshift --build.env NODE_ENV=development --build.env YARN_ENABLED=true`\n\n#### build.strategy\nFlag to change the build strategy used.  Values can be Docker or Source.  Defaults to Source\n\n#### useDeploymentConfig\nFlag to deploy the application using a DeploymentConfig instead of a Deployment. Defaults to false\n\n#### knative\nEXPERIMENTAL. Flag to deploy an application as a Knative Serving Service.  Defaults to false\nSince this feature is experimental,  it is subject to change without a Major version release until it is fully stable.\n\n#### kube\nFlag to deploy an application to a vanilla kubernetes cluster.  At the moment only Minikube is supported.\n\n#### rh-metering\nFlag to add some metering labels to a deployment.  To change the nodeVersion label, use `--rh-metering.nodeVersion` flag.  Intended for use with Red Hat product images.  For more information on metering for Red Hat images, see [here](https://access.redhat.com/documentation/en-us/red_hat_build_of_node.js/14/html/release_notes_for_node.js_14/features-nodejs#node_js_metering_labels_for_openshift)\n\n#### help\nShows the below help\n\n        Usage: nodeshift [--options]\n\n        Commands:\n            nodeshift deploy          default command - deploy                   [default]\n            nodeshift build           build command\n            nodeshift resource        resource command\n            nodeshift apply-resource  apply resource command\n            nodeshift undeploy        undeploy resources\n            nodeshift login           login to the cluster\n            nodeshift logout          logout of the cluster\n\n        Options:\n            --version                Show version number                         [boolean]\n            --projectLocation        change the default location of the project   [string]\n            --kube                   Flag to deploy an application to a vanilla kubernetes\n                           cluster.  At the moment only Minikube is supported.\n                                                                                 [boolean]\n            --configLocation         change the default location of the config    [string]\n            --token                  auth token to pass into the openshift rest client for\n                                     logging in.  Overrides the username/password [string]\n            --username               username to pass into the openshift rest client for\n                                     logging in                                   [string]\n            --password               password to pass into the openshift rest client for\n                                     logging in                                   [string]\n            --apiServer              Deprecated - use the \"server\" flag instead. server address to pass into the openshift rest client\n                                     for logging in                               [string]\n            --server                 server address to pass into the openshift rest client\n                                     for logging in                               [string]\n            --insecure               flag to pass into the openshift rest client for\n                                     logging in with a self signed cert.  Only used with\n                                     apiServer login                             [boolean]\n            --forceLogin             Force a login when using the apiServer login[boolean]\n            --imageTag           The tag of the docker image to use for the deployed\n                                application.                 [string] [default: \"latest\"]\n                                                             [boolean] [default: false]\n            --resourceProfile        Define a subdirectory below .nodeshift/ that indicates\n                                     where Openshift resources are stored         [string]\n            --outputImageStream      The name of the ImageStream to output to.  Defaults\n                           to project name from package.json            [string]\n            --outputImageStreamTag   The tag of the ImageStream to output to.    [string]\n            --quiet                  suppress INFO and TRACE lines from output logs\n                                                                                [boolean]\n            --expose            flag to create a default Route and expose the default\n                       service [boolean] [choices: true, false] [default: false]\n            --namespace.displayName  flag to specify the project namespace display name to\n                           build/deploy into.  Overwrites any namespace settings\n                           in your OpenShift or Kubernetes configuration files\n                                                                        [string]\n            --namespace.create       flag to create the namespace if it does not exist.\n                           Only applicable for the build and deploy command.\n                           Must be used with namespace.name            [boolean]\n            --namespace.remove       flag to remove the user created namespace.  Only\n                           applicable for the undeploy command.  Must be used\n                           with namespace.name                         [boolean]\n            --namespace.name         flag to specify the project namespace name to\n                           build/deploy into.  Overwrites any namespace settings\n                           in your OpenShift or Kubernetes configuration files\n                                                                        [string]\n            --deploy.port        flag to update the default ports on the resource files.\n                       Defaults to 8080                          [default: 8080]\n            --build.recreate         flag to recreate a buildConfig or Imagestream\n                    [choices: \"buildConfig\", \"imageStream\", false, true] [default: false]\n            --build.forcePull        flag to make your BuildConfig always pull a new image\n                                    from dockerhub or not\n                                        [boolean] [choices: true, false] [default: false]\n            --build.incremental  flag to perform incremental builds, which means it reuses\n                                    artifacts from previously-built images\n                                        [boolean] [choices: true, false] [default: false]\n            --build.strategy         flag to change the build strategy.  Defaults to Source\n                                      [choices: \"Source\", \"Docker\"]\n            --metadata.out           determines what should be done with the response\n                                    metadata from OpenShift\n                    [string] [choices: \"stdout\", \"ignore\", \"\u003cfilename\u003e\"] [default: \"ignore\"]\n            --useDeploymentConfig          flag to deploy the application using a DeploymentConfig\n                           instead of a Deployment\n                               [boolean] [choices: true, false] [default: false]\n            --knative                EXPERIMENTAL. flag to deploy an application\n                           as a Knative Serving Service\n                               [boolean] [choices: true, false] [default: false]\n            --help                   Show help                                   [boolean]\n            --cmd                                                      [default: \"deploy\"]\n\n\n\n## Contributing\n\nPlease read the [contributing guide](./CONTRIBUTING.md)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeshift%2Fnodeshift","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnodeshift%2Fnodeshift","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnodeshift%2Fnodeshift/lists"}