cht-conf 3.16.0 → 3.16.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [3.16.1](https://github.com/medic/cht-conf/compare/v3.16.0...v3.16.1) (2023-03-18)
+
+
+### Bug Fixes
+
+* **#524:** Don't display usage() information for commands which run successfully ([5b265e7](https://github.com/medic/cht-conf/commit/5b265e753d035b326ff8d6bac0a9aabc923048fb)), closes [#524](https://github.com/medic/cht-conf/issues/524) [#524](https://github.com/medic/cht-conf/issues/524)
+
 # [3.16.0](https://github.com/medic/cht-conf/compare/v3.15.3...v3.16.0) (2023-03-09)
 
 

package/Dockerfile

@@ -1,23 +1,29 @@
-FROM ubuntu:18.04
-MAINTAINER DevOps "devops@medicmobile.org"
+FROM node:16-slim
 
+RUN apt update \
+    && apt install --no-install-recommends -y \
+      build-essential \
+      chromium \
+      curl \
+      git \
+      openssh-client \
+      python3-pip \
+      python3-setuptools \
+      python3-wheel \
+      xsltproc \
+    # Remove chromium to save space. We only installed it to get the transitive dependencies that are needed
+    # when running tests with puppeteer. (puppeteer-chromium-resolver will always download its own version of chromium)
+    && apt remove -y chromium \
+    && rm -rf /var/lib/apt/lists/*
 
-RUN echo "==> Installing Python dependencies" && \
-    apt-get update -y   && \
-    apt-get install --no-install-recommends -y -q \
-            build-essential python-setuptools     \
-            python python-pip python-dev          \
-            libffi-dev  libssl-dev                \
-            libxml2-dev libxslt1-dev zlib1g-dev   \
-            git wget python-wheel curl
+RUN python3 -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
 
-RUN echo "====> Installing cht-conf python stuff"    &&\
-    python -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
+RUN npm install -g cht-conf
 
-RUN curl -sL https://deb.nodesource.com/setup_12.x -o nodesource_setup.sh
-RUN bash nodesource_setup.sh
-RUN apt-get install -y nodejs
+# Using the 1000:1000 user is recommended for VSCode dev containers
+# https://code.visualstudio.com/remote/advancedcontainers/add-nonroot-user
+USER node
 
-RUN npm install -g cht-conf
+WORKDIR /workdir
 
-CMD ["tail", "-f", "/dev/null"]
+ENTRYPOINT ["cht"]

package/README.md

@@ -32,22 +32,75 @@ As Administrator:
 
 ### Docker
 
-**NB** - `cht-conf` in a Docker container should only be used if you're familiar with running containers. You will have to copy or mount your config files into the container in order to be able to use the `cht` call to interact with a remote CHT instance.
+CHT Conf can also be run from within a Docker container. This is useful if you are already familiar with Docker and do not wish to configure the various dependencies required for developing CHT apps on your local machine. The necessary dependencies are pre-packaged in the Docker image.
 
-Build and then run the `cht-conf` container:
+#### Building the image
 
-	docker build -t cht-conf:v0 .
-	docker run -d --name cht-conf cht-conf:v0
+Install [Docker](https://www.docker.com/). If you are using Windows, you also need to enable the [Windows Subsystem for Linux (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/install) to perform the following steps.
 
-You now have a container running in the background called `cht-conf`. You can get a shell on this container with:
+Using the terminal (or the WLS shell on Windows: _Start > wsl_), run the following commands to create a new project directory and build the Docker image:
 
-	docker exec -it cht-conf /bin/bash
+```shell
+mkdir -p ~/cht-project
+cd ~/cht-project
+curl https://raw.githubusercontent.com/medic/cht-conf/main/Dockerfile > Dockerfile
+docker build -t cht-ide .
+```
 
-And then you can run the utility with `cht`.  
+#### Using the image
 
-When you are done with the container, you can stop it with:
+The resulting Docker image can be used as a [VSCode Development Container](https://code.visualstudio.com/docs/devcontainers/containers) (easiest) or as a standalone Docker utility.
 
-	docker stop cht-conf
+##### VSCode Development Container
+
+If you want to develop CHT apps with VSCode, you can use the Docker image as a Development Container. This will allow you to use the `cht-conf` utility and its associated tech stack from within VSCode (without needing to install dependencies like NodeJS on your host system).
+
+[Install VSCode](https://code.visualstudio.com/) if you do not have it already.
+
+Using the terminal (or the WLS shell on Windows: _Start > wsl_), run the following commands from within your project directory (created above) to download the `.devcontainer.json` config file, install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), and open the project directory in VSCode:
+
+```shell
+cd ~/cht-project
+curl -s https://raw.githubusercontent.com/medic/cht-conf/main/devcontainer.cht-ide/.devcontainer.json > .devcontainer.json
+code --install-extension ms-vscode-remote.remote-containers
+code -n .
+```
+
+When opening VSCode, you may be prompted with the question:
+
+> **Do you trust the authors of the files in this folder?**
+
+Choose, "Yes, I trust the authors".
+
+Open the Command Palette in VSCode (_Ctrl+Shift+P_ or _Cmd+Shift+P_) and select `Reopen in Container`. This will open your workspace inside a container based on the `cht-ide` image. You can use the `cht` commands by opening a terminal in VSCode (_Ctrl+Shift+\`_ or _Cmd+Shift+\`_). If prompted "Do you trust the authors..." choose "Trust Folder & Continue".
+
+Run the following command in the VSCode terminal to bootstrap your new CHT project:
+
+```shell
+cht initialise-project-layout
+```
+
+###### Terminal environment
+
+When opening a terminal in VSCode in a development container, the terminal will be running on the _container environment_ by default. This is what gives you access to the various `cht` commands.  However, this also means you do NOT have access, within the default VSCode terminal, to commands from your _host environment_. So, for example, you cannot run `docker` commands since Docker is not installed inside the container.
+
+To open a terminal running on you _host environment_ in VSCode, open the Command Palette (_Ctrl+Shift+P_ or _Cmd+Shift+P_) and select `Create New Integrated Terminal (Local)`. Just remember that you will NOT be able to run `cht` commands from this terminal since cht-conf is not installed on your host machine.
+
+##### Standalone Docker utility
+
+If you are not using VSCode, you can use the Docker image as a standalone utility from the command line.  Instead of using the `cht ...` command, you can run `docker run -it --rm -v "$PWD":/workdir cht-ide ...`. This will create an ephemeral container with access to your current directory that will run the given cht command. (Do not include the `cht` part of the command, just your desired actions/parameters.)
+
+Run the following command inside the project directory to bootstrap your new CHT project:
+
+```shell
+docker run -it --rm -v "$PWD":/workdir cht-ide initialise-project-layout
+```
+
+#### Note on connecting to a local CHT instance
+
+When using `cht-conf` within a Docker container to connect to a CHT instance that is running on your local machine (e.g. a development instance), you cannot use the `--local` flag or `localhost` in your `--url` parameter (since these will be interpreted as "local to the container"). 
+
+It is recommended to run a local CHT instance using the [CHT Docker Helper script](https://docs.communityhealthtoolkit.org/apps/guides/hosting/4.x/app-developer/). You can connect to the resulting `...my.local-ip.co` URL from the Docker container (or the VSCode terminal). (Just make sure the port your CHT instance is hosted on is not blocked by your firewall). 
 
 ## Bash completion
 

package/devcontainer.cht-ide/.devcontainer.json

@@ -0,0 +1,6 @@
+{
+  "image": "cht-ide",
+  // Required to run tests with Puppeteer
+  // https://pptr.dev/guides/docker
+  "capAdd": ["SYS_ADMIN"]
+}

package/devcontainer.cht-ide/README.md

@@ -0,0 +1,3 @@
+# Dev Container Resources for CHT Apps
+
+This directory contains resources useful for developing CHT applications with [Dev Containers](https://containers.dev/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cht-conf",
-  "version": "3.16.0",
+  "version": "3.16.1",
   "description": "Configure CHT deployments",
   "main": "./src/lib/main.js",
   "engines": {

package/src/lib/get-api-url.js

@@ -1,21 +1,20 @@
 const userPrompt = require('./user-prompt');
 const url = require('url');
-const usage = require('../cli/usage');
 
 const emoji = require('./emoji');
-const { error, info } = require('./log');
+const { info } = require('./log');
+const usage = require('../cli/usage');
 
 const getApiUrl = (cmdArgs, env = {}) => {
   const specifiedModes = [cmdArgs.local, cmdArgs.instance, cmdArgs.url, cmdArgs.archive].filter(mode => mode);
   if (specifiedModes.length !== 1) {
-    error('Require exactly one of these parameter: --local --instance --url --archive');
     usage();
-    return false;
+    throw Error('One of these parameters is required: --local --instance --url --archive');
   }
 
   if (cmdArgs.user && !cmdArgs.instance) {
-    error('The --user switch can only be used if followed by --instance');
-    return false;
+    usage();
+    throw Error('The --user switch must be accompanied with --instance');
   }
 
   let instanceUrl;
@@ -26,8 +25,7 @@ const getApiUrl = (cmdArgs, env = {}) => {
     // See ./archiving-db.js
     instanceUrl = parseLocalUrl(env.COUCH_URL);
     if (instanceUrl.hostname !== 'localhost') {
-      error(`You asked to configure localhost, but the COUCH_URL env var is set to '${instanceUrl.hostname}'.  This may be a remote server.`);
-      return false;
+      throw Error(`--local was specified but COUCH_URL env var is set to '${instanceUrl.hostname}'.  Please use --url for remote servers.`);
     }
   } else if (cmdArgs.instance) {
     const password = userPrompt.question(`${emoji.key}  Password: `, { hideEchoBack: true });

package/src/lib/main.js

@@ -134,71 +134,16 @@ module.exports = async (argv, env) => {
   //
   // Build up actions
   //
-  let actions = cmdArgs._;
-  if (actions.length) {
-    const unsupported = actions.filter(a => !supportedActions.includes(a));
-    if(unsupported.length) {
-      throw new Error(`Unsupported action(s): ${unsupported.join(' ')}`);
-    }
-  } else {
-    actions = !cmdArgs.archive ? defaultActions : defaultArchiveActions;
-  }
-
-  if (cmdArgs['skip-git-check']) {
-    actions = actions.filter(a => a !== 'check-git');
-  }
-
   const skipValidate = cmdArgs['skip-validate'];
-  if(skipValidate) {
-    warn('Skipping all form validation.');
-    const validateActions = [
-      'validate-app-forms',
-      'validate-collect-forms',
-      'validate-contact-forms',
-      'validate-training-forms',
-    ];
-    actions = actions.filter(action => !validateActions.includes(action));
-  } else {
-    const addFormValidationIfNecessary = (formType) => {
-      const updateFormsIndex = actions.indexOf(`upload-${formType}-forms`);
-      if (updateFormsIndex >= 0 && actions.indexOf(`validate-${formType}-forms`) < 0) {
-        actions.splice(updateFormsIndex, 0, `validate-${formType}-forms`);
-      }
-    };
-    addFormValidationIfNecessary('app');
-    addFormValidationIfNecessary('collect');
-    addFormValidationIfNecessary('contact');
-    addFormValidationIfNecessary('training');
-  }
-
-  actions = actions.map(actionName => {
-    const action = require(`../fn/${actionName}`);
-
-    if (typeof action.execute !== 'function') {
-      throw new Error(`${actionName} has not been implemented correctly: no 'execute' function`);
-    }
-
-    if (!Object.hasOwnProperty.call(action, 'requiresInstance')) {
-      action.requiresInstance = true;
-    }
-
-    action.name = actionName;
-
-    return action;
-  });
+  const actions = buildActions(cmdArgs, skipValidate);
 
   //
   // Initialize the environment
   //
   const projectName = fs.path.basename(pathToProject);
 
-  const apiUrl = getApiUrl(cmdArgs, env);
   const requiresInstance = actions.some(action => action.requiresInstance);
-  if (requiresInstance) {
-    if (!apiUrl) {
-      throw new Error('Failed to obtain a url to the API');
-    }
-  }
+  const apiUrl = requiresInstance && getApiUrl(cmdArgs, env);
 
   let extraArgs = cmdArgs['--'];
   if (!extraArgs.length) {
@@ -252,5 +197,60 @@ module.exports = async (argv, env) => {
   }
 };
 
+function buildActions(cmdArgs, skipValidate) {
+  let actions = cmdArgs._;
+  if (actions.length) {
+    const unsupported = actions.filter(a => !supportedActions.includes(a));
+    if (unsupported.length) {
+      usage();
+      throw new Error(`Unsupported action(s): ${unsupported.join(' ')}`);
+    }
+  } else {
+    actions = !cmdArgs.archive ? defaultActions : defaultArchiveActions;
+  }
+
+  if (cmdArgs['skip-git-check']) {
+    actions = actions.filter(a => a !== 'check-git');
+  }
+
+  if(skipValidate) {
+    warn('Skipping all form validation.');
+    const validateActions = [
+      'validate-app-forms',
+      'validate-collect-forms',
+      'validate-contact-forms',
+      'validate-training-forms',
+    ];
+    actions = actions.filter(action => !validateActions.includes(action));
+  } else {
+    const addFormValidationIfNecessary = (formType) => {
+      const updateFormsIndex = actions.indexOf(`upload-${formType}-forms`);
+      if (updateFormsIndex >= 0 && actions.indexOf(`validate-${formType}-forms`) < 0) {
+        actions.splice(updateFormsIndex, 0, `validate-${formType}-forms`);
+      }
+    };
+    addFormValidationIfNecessary('app');
+    addFormValidationIfNecessary('collect');
+    addFormValidationIfNecessary('contact');
+    addFormValidationIfNecessary('training');
+  }
+
+  return actions.map(actionName => {
+    const action = require(`../fn/${actionName}`);
+
+    if (typeof action.execute !== 'function') {
+      throw new Error(`${actionName} has not been implemented correctly: no 'execute' function`);
+    }
+
+    if (!Object.hasOwnProperty.call(action, 'requiresInstance')) {
+      action.requiresInstance = true;
+    }
+
+    action.name = actionName;
+
+    return action;
+  });
+}
+
 // Exists for generic mocking purposes
 const executeAction = action => action.execute();