{"id":15353230,"url":"https://github.com/lostintangent/azjs","last_synced_at":"2025-06-18T15:35:45.694Z","repository":{"id":19156465,"uuid":"86368366","full_name":"lostintangent/azjs","owner":"lostintangent","description":"An opinionated CLI for deploying and managing Node.js-based web apps and APIs on Azure","archived":false,"fork":false,"pushed_at":"2020-05-29T04:59:05.000Z","size":4760,"stargazers_count":6,"open_issues_count":14,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-15T05:55:06.531Z","etag":null,"topics":["azure","cli","nodejs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lostintangent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-27T18:10:09.000Z","updated_at":"2022-11-03T23:52:43.000Z","dependencies_parsed_at":"2022-07-27T00:02:05.662Z","dependency_job_id":null,"html_url":"https://github.com/lostintangent/azjs","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostintangent%2Fazjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostintangent%2Fazjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostintangent%2Fazjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lostintangent%2Fazjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lostintangent","download_url":"https://codeload.github.com/lostintangent/azjs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249016320,"owners_count":21198832,"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":["azure","cli","nodejs"],"created_at":"2024-10-01T12:13:28.755Z","updated_at":"2025-04-15T05:55:11.903Z","avatar_url":"https://github.com/lostintangent.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Az.js CLI\n\n[![Build Status](https://travis-ci.org/lostintangent/azjs.svg?branch=master)](https://travis-ci.org/lostintangent/azjs) [![Greenkeeper badge](https://badges.greenkeeper.io/lostintangent/azjs.svg)](https://greenkeeper.io/)\n\nAz.js is a command line tool which attempts to provide an opinionated (and hopefully simpler!) developer experience for deploying and managing Node.js apps on Azure. It is meant to experiment/play around with ideas to reduce the barrier of entry to cloud development, and therefore, is a compliment to the already awesome [Azure CLI 2.0](http://github.com/azure/azure-cli) (which supports a significantly richer set of scenarios and capabilities).\n\nThis CLI is very much inspired by the amazing work done by other tools such as [Docker](http://www.docker.com), [Now](http://zeit.co/now) and [Serverless](http://serverless.com), which are making great strides in the pursuit of simplicity, and are benchmarks for what CLI-driven workflows can and should look like moving forward.\n\n\u003cimg src=\"https://cloud.githubusercontent.com/assets/116461/25299168/31e0a546-26b1-11e7-9f09-a8acffdfdffe.png\" width=\"545px\" /\u003e\n\n## Pre-requisites\n\n* [Node.js](https://nodejs.org/en/) v6.9.0+, and the platform-specific tools needed to compile native NPM modules *(which you may already have)*:\n    * Windows - Run the following in an elevated prompt (`cmd.exe` or PowerShell): `npm i -g windows-build-tools`\n    * Ubuntu - Run `sudo apt-get install build-essential`\n    * macOS - Install Xcode\n* Azure account ([start a free trial with a $200 credit!](https://azure.microsoft.com/en-us/free))\n\n## Getting Started\n\nIn order to install the Az.js CLI, simply run the following NPM command, which will add the `azjs` command to your `PATH`:\n\n```shell\nnpm i -g azjs\n```\n\nThen, simply CD into a directory that contains a Node.js app and run the following command:\n\n```shell\nazjs deploy\n```\n\nYou will be asked to login to your Azure account, and authorize `azjs` to manage Azure resources on your behalf (e.g. create web apps). Paste the provided \"device code\" into the launched browser (it is automatically copied to your clipboard), complete the authentication process, and then return to your terminal, which will begin progressing with the deployment momentarily.\n\n\u003e Note: Once you're successfully authenticated, all subsequent CLI commands will re-use this same login session, which prevents you from needing to re-authenticate every time you'd like to deploy changes to your app.\n\nAs soon as the deploymented is finished, the terminal will begin streaming your app's stdout, and will display the URL you can use to immediately browse/test your deployed app.\n\n\u003cimg src=\"https://cloud.githubusercontent.com/assets/116461/25141329/1b7dfeca-2418-11e7-9920-bf07cc051eda.png\" width=\"600\" /\u003e\n\nIf your app uses MongoDB as its backing database (as many Node apps do!), and you'd like to provision a fully-managed, geo-replicable instance, you can simply run the following command in order to spin one up and inject it's connection string into your app via an environment variable named `MONGODB_URL` (view [reference below](#azjs-service) for more details of how this works):\n\n```shell\nazjs service create -t mongodb\n```\n\n\u003cimg src=\"https://cloud.githubusercontent.com/assets/116461/25141537/a8c42e08-2418-11e7-9c01-5330554afbaa.png\" width=\"700\" /\u003e\n\n\u003e Note: In order to see all of the service types that are supported, run `azjs service create -h` to see the options that the `-t` flag accepts (e.g. Redis)\n\nAfter your app has been running for a while, and you'd like to check it's telemetry and health, you can simply run the following command:\n\n```shell\nazjs monitor\n```\n\nThis will launch your browser, and navigate you directly to the telemetry dashboard for your app, within the Azure portal. From here, you can inspect your HTTP traffic, exceptions, performance metrics, etc. You can also configure alerts, so that you can be notified of interesting events in the future, which justify further investigation.\n\n\u003cimg src=\"https://cloud.githubusercontent.com/assets/116461/24817224/4b8158bc-1ba1-11e7-9ae0-44b2b7522c03.png\" width=\"600\" /\u003e\n\n\u003e Note: This monitoring support is provided by means of Application Insights, which you can find more information about [here](https://azure.microsoft.com/en-us/services/application-insights/).\n\nIf at some point you no longer need your app to be deployed on Azure, you can confidently remove all of your Azure resources (to prevent incurring any unexpected charges) by CDing into the app directory again and simply running the following command:\n\n```shell\nazjs remove\n```\n\nThis will delete all of the infrastructure that was originally provisioned by running `azjs`. This way, Az.js has a zero-imapct effect on your Azure account, unless you want it to.\n\n\u003cimg src=\"https://cloud.githubusercontent.com/assets/116461/24817537/76d3c616-1ba2-11e7-8928-ed5fb8c055a5.png\" width=\"225\" /\u003e\n\n## CLI Command Reference\n\n* [Browse](#azjs-browse)\n* [Cat](#azjs-cat)\n* [Deploy](#azjs-deploy)\n* [Exec](#azjs-exec)\n* [Export](#azjs-export)\n* [Logs](#azjs-logs)\n* [Logpoint](#azjs-logpoint)\n    * [Add](#azjs-logpoint-add)\n    * [Clear](#azjs-logpoint-clear)\n* [Monitor](#azjs-monitor)\n* [Portal](#azjs-portal)\n* [Remove](#azjs-remove)\n* [Restart](#azjs-restart)\n* [Service](#azjs-service)\n    * [Create](#azjs-service-create)\n    * [Remove](#azjs-service-remove)\n\n### azjs browse\n\nIf at any point you'd like to launch the latest deployment of your app, in your default browser, simply run the following command:\n\n```shell\nazjs browse\n```\n\n### azjs cat\n\nView the contents of a file on the remote server. This is useful if you'd like to set a [logpoint](#azjs-logpoint-add) for diagnostic purposes, but you need to determine the exact line number in a file you're interested in.\n\n```shell\nazjs cat -f app/routes.js\n```\n\n### azjs deploy\n\nWhen you want to deploy a web app and/or push changes to an existing web app, you can quickly do this by CDing into your app directory and running the following command:\n\n```shell\nazjs deploy\n```\n\nThis will zip up the contents of your web app and deploy them to Azure. It will then install your NPM dependencies, and begin displaying the log stream from your app's stdout.\n\n#### Local Git Deployment\n\nIf you'd like to track your app via a local Git repo, and push changes to your web app as if it was another remote, then simply run the following command:\n\n```shell\nazjs deploy --git\n```\n\nThis will behave exactly like the non-Git workflow, except it will also add a new Git remote to your repo called `azure` and then run a `git push` for you. If you'd like to suppress the automatic `git push`, simply pass the `--no-sync` flag, and do the push to the added `azure` remote as appropriate.\n\nAs you make changes to your app, you can simply run `git push azure master` in order to deploy them, as opposed to needing to run `azjs deploy` again.\n\n#### Remote Git Deployment\n\nIf you're already tracking your app via a remote Git repo (e.g. GitHub), you can \"connect\" your web app to that by running the following command:\n\n```shell\nazjs deploy --git-url \u003cGIT_REPO_URL\u003e\n```\n\nThis will behave similarly to the local Git deployment solution, however, instead of pushing changes directly to your web app, you would push changes to the specified Git repo, and allow the deployed web app to pull updates from it.\n\n### azjs exec\n\nWhile `azjs` provides numerous first-class commands for running specific operations (e.g. reading a remote file), there may be times where you want to execute an arbitrary shell command against the remote web app. To do this, you can simply run the following command:\n\n```shell\nazjs exec -c 'npm i -g gulp'\n```\n\nIf the command exits with a 0 status code, then its stdout will be printed to the terminal. Otherwise, it's stderr will be printed, so you can identify what went wrong.\n\n### azjs export\n\nWhile Az.js supports lots of app development workflows, there may be times where you'd like to \"pierce the viel\" of abstraction that it provides, and manage your app using other means. In order to ensure that any work you've done with Az.js isn't lost, you can run the following command, which will export the Azure deployment script needed to re-deploy it to another account and/or resource group at any time:\n\n```shell\nazjs export\n```\n\nBy default, this command will output an ARM template to stdout, but if you'd like to explicitly write it to a file (as opposed to piping it), you can also specify a file name to write to, like so:\n\n```shell\nazhs export -f myApp.json\n```\n\n### azjs logs\n\nWhile running `azjs deploy` and/or `azjs browse` will automatically begin streaming your app's stdout for you, if you'd like to re-open the log stream at any other time (e.g. you'd like to view the logs for an already deployed version of your app), you can simply run the following command:\n\n```shell\nazjs logs\n```\n\n### azjs logpoint\n\nAllows managing the dynamic logpoints that allow diagnosing your app in production.\n\n#### azjs logpoint add\n\nIf you forget to add a log statement to your app before deployment, you can dynamically add one by simply running the following command:\n\n```shell\nazjs logpoint add -f app/routes.js -l 22 -e req.path\n```\n\nOnce defined, this logpoint will be outputted to your log stream (e.g. when runnin `azjs logs`) in the same way that any \"statically\" defined log statement would be.\n\n#### azjs logpoint clear\n\nOnce you're finished with your logpoints, you can clear all of them by running the following command, which prevents your logs from being cluttered with unneccessary diagnostic messages:\n\n```shell\nazjs logpoint clear\n```\n\n### azjs monitor\n\nWhen you deploy an app with Az.js, it automatically configures monitoring for you, so that you can view basic telemetry (e.g. HTTP traffic, exceptions) without needing to do anything. In order to view your telemetry dashboard, you can simply run the following command:\n\n```shell\nazjs monitor\n```\n\n### azjs portal\n\nIf you'd like to view and/or manage your web app within the Azure portal (or are just curious), you can break out of the Az.js abstraction by running the following command:\n\n```shell\nazjs portal\n```\n\n### azjs remove\n\nWhen you no longer need an app deployed in Azure, you can quickly delete all of its backing resources by running the following command:\n\n```shell\nazjs remove\n```\n\n### azjs restart\n\nIf at any point, you'd like to restart the web app, in order to force changes to apply, you can simply run the following command:\n\n```shell\nazjs restart\n```\n\n### azjs service\n\nAllows managing the external services that your app uses (e.g. MongoDB, Redis)\n\n#### azjs service create\n\nProvisions a new instance of a specific service type (e.g. MongoDB, Redis) and \"binds\" it to your deployed web app. For example, to create a MongoDB database, simply run the following command:\n\n```shell\nazjs service create -t mongodb\n```\n\nThis will create the MongoDB service, and then inject the connection string into your web app, via an environment variable named `MONGODB_URL`. Therefore, as long as your app expects to find it's MongoDB connection via an environment variable (as any good 12 Factor App should), then you shouldn't need to make any code changes in order to benefit from this command.\n\n#### azjs service remove\n\nDeletes a previously provisioned service and unbinds it from your web app (e.g. removes any injected environment variables).\n\n## Authentication Reference\n\nThe `azjs` CLI defaults to using an interactive login experience, in order to provide a simple getting started experience. However, if you'd like to customize the exact credentials that `azjs` uses to manage your Azure account, you can specify a specific service principal to use for authentication, by setting the following four environment variables (using either of the listed aliases):\n\n* **azureSubId / ARM_SUBSRIPTION_ID** - The ID of the Azure subscription that you'd like to manage resources within\n* **azureServicePrincipalClientId / ARM_CLIENT_ID** - The name of the service principal\n* **azureServicePrincipalPassword / ARM_CLIENT_SECRET** - The password of the service principal\n* **azureServicePrincipalTenantId / ARM_TENANT_ID** - The ID of the tenant that the service principal was created in\n\n\u003e These are the same environment variables that are expected from the [Serverless](https://serverless.com/framework/docs/providers/azure/guide/credentials/) experience for Azure Functions (`azure*`), and the Terraform Azure builder (`ARM*`), so if you've already set these environment variables in order to use one or both of these tools, then `azjs` will automatically use the same credentials.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostintangent%2Fazjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flostintangent%2Fazjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flostintangent%2Fazjs/lists"}