# medic-conf

> Configure Medic Mobile deployments

Latest version **3.6.0** (published 2021-04-27) · AGPL-3.0-only license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install medic-conf
pnpm add medic-conf
yarn add medic-conf
bun add medic-conf
```

Provides the commands `medic-conf`, `medic-logs`, `pngout-medic`, `shell-completion-for-medic-conf`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 3.6.0 |
| Published | 2021-04-27 |
| First published | 2017-10-31 |
| Weekly downloads | 0 |
| License | AGPL-3.0-only |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=8.10.0 |
| Dependencies | 30 |
| Unpacked size | 590 KB |
| Known vulnerabilities | 0 (+23 in 6 direct dependencies) |
| Install scripts | no |
| GitHub stars | 22 |
| Maintainers | garethbowen, scdf, hgalemayehu, abbyad, twd, newtewt, kennsippell, mrsarm, alxndrsn |

## Links

- npm: https://www.npmjs.com/package/medic-conf
- Repository: https://github.com/medic/medic-conf
- Homepage: https://github.com/medic/medic-conf#readme
- Issues: https://github.com/medic/medic-conf/issues
- npm.io page: https://npm.io/package/medic-conf

## Dependencies (30)

- [open](https://npm.io/package/open.md) ^7.0.2
- [svgo](https://npm.io/package/svgo.md) ^1.2.2
- [uuid](https://npm.io/package/uuid.md) ^3.3.3
- [eslint](https://npm.io/package/eslint.md) ^6.5.0
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.1
- [semver](https://npm.io/package/semver.md) ^6.1.1
- [xmldom](https://npm.io/package/xmldom.md) ^0.1.27
- [request](https://npm.io/package/request.md) ^2.88.0
- [webpack](https://npm.io/package/webpack.md) ^4.41.0
- [json2csv](https://npm.io/package/json2csv.md) ^4.5.1
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [@hapi/joi](https://npm.io/package/@hapi/joi.md) ^16.1.8
- [csv-parse](https://npm.io/package/csv-parse.md) ^4.4.3
- [iso-639-1](https://npm.io/package/iso-639-1.md) ^2.1.4
- [json-diff](https://npm.io/package/json-diff.md) ^0.5.4
- [pluralize](https://npm.io/package/pluralize.md) ^7.0.0
- [googleapis](https://npm.io/package/googleapis.md) ^43.0.0
- [mime-types](https://npm.io/package/mime-types.md) ^2.1.27
- [properties](https://npm.io/package/properties.md) ^1.2.1
- [dom-compare](https://npm.io/package/dom-compare.md) ^0.6.0
- [pouchdb-core](https://npm.io/package/pouchdb-core.md) ^7.1.1
- [eslint-loader](https://npm.io/package/eslint-loader.md) ^3.0.2
- [readline-sync](https://npm.io/package/readline-sync.md) ^1.4.10
- [canonical-json](https://npm.io/package/canonical-json.md) 0.0.4
- [pouchdb-mapreduce](https://npm.io/package/pouchdb-mapreduce.md) ^7.1.1
- [redact-basic-auth](https://npm.io/package/redact-basic-auth.md) ^1.0.0
- [json-stringify-safe](https://npm.io/package/json-stringify-safe.md) ^5.0.1
- [pouchdb-adapter-http](https://npm.io/package/pouchdb-adapter-http.md) ^7.1.1
- [request-promise-native](https://npm.io/package/request-promise-native.md) ^1.0.7
- [@medic/translation-checker](https://npm.io/package/@medic/translation-checker.md) 1.0.0

## Recent versions

- 3.6.0 (latest) — 2021-04-27
- 3.6.0-beta.1 (beta) — 2021-04-26
- 3.5.0 — 2021-04-12
- 3.4.1 — 2021-03-15
- 3.4.1-beta.1 — 2021-03-15
- 3.4.0 — 2021-03-15
- 3.3.0 — 2020-09-08
- 3.3.0-beta.1 — 2020-08-31
- 3.2.1 — 2020-05-18
- 3.2.0 — 2020-04-23
- 3.1.0 — 2020-01-07
- 3.0.7 — 2019-11-21
- 3.0.6 — 2019-10-01
- 3.0.5 — 2019-09-26
- 3.0.4 — 2019-08-20
- … 99 more at https://npm.io/package/medic-conf/versions

## README

Medic Project Configurer
========================

Medic Conf is a command-line interface tool to manage and configure your apps built using the [Core Framework](https://github.com/medic/cht-core) of the [Community Health Toolkit](https://communityhealthtoolkit.org).

# Requirements

* nodejs 8 or later
* python 2.7
* or Docker

# Installation

## Docker

	docker build -t medic-conf:v0 .
	docker run medic-conf:v0
	docker exec -it <container_name> /bin/bash

## Ubuntu

	npm install -g medic-conf
	sudo python -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic

## OSX

	npm install -g medic-conf
	pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic

## Windows

As Administrator:

	npm install -g medic-conf
	python -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic --upgrade

## Bash completion

To enable tab completion in bash, add the following to your `.bashrc`/`.bash_profile`:

	eval "$(medic-conf --shell-completion=bash)"

## Upgrading

To upgrade to the latest version

	npm install -g medic-conf

# Usage

`medic-conf` will upload the configuration **from your current directory**.

## Specifying the server to configure

If you are using the default actionset, or performing any actions that require a CHT instance to function (e.g. `upload-xyz` or `backup-xyz` actions) you must specify the server you'd like to function against.

### localhost

For developers, this is the instance defined in your `COUCH_URL` environment variable.

	medic-conf --local

### A specific Medic Mobile instance

For configuring against Medic Mobile-hosted instances.

	medic-conf --instance=instance-name.dev

Username `admin` is used. A prompt is shown for entering password.

If a different username is required, add the `--user` switch:

	--user user-name --instance=instance-name.dev

### An arbitrary URL

	medic-conf --url=https://username:password@example.com:12345

### Into an archive to be uploaded later

  medic-conf --archive

The resulting archive is consumable by Medic's API >v3.7 to create default configurations.

## Perform specific action(s)

	medic-conf <--archive|--local|--instance=instance-name|--url=url> <...action>

The list of available actions can be seen via `medic-conf --help`.

## Perform actions for specific forms

	medic-conf <--local|--instance=instance-name|--url=url> <...action> -- <...form>

## Protecting against configuration overwriting

_Added in v3.2.0_

In order to avoid overwriting someone elses configuration medic-conf records the last uploaded configuration snapshot in the `.snapshots` directory. The `remote.json` file should be committed to your repository along with the associated configuration change. When uploading future configuration if medic-conf detects the snapshot doesn't match the configuration on the server you will be prompted to overwrite or cancel.

# Currently supported

## Settings

* compile app settings from:
  - tasks
  - rules
  - schedules
  - contact-summary
  - purge
* app settings can also be defined in a more modular way by having the following files in app_settings folder:
	- base_settings.json
	- forms.json
	- schedules.json
* backup app settings from server
* upload app settings to server
* upload resources to server
* upload custom translations to the server
* upload privacy policies to server
* upload branding to server
* upload partners to server

## Forms

* fetch from Google Drive and save locally as `.xlsx`
* backup from server
* delete all forms from server
* delete specific form from server
* upload all app or contact forms to server
* upload specified app or contact forms to server

## Managing data and images

* convert CSV files with contacts and reports to JSON docs
* move contacts by downloading and making the changes locally first
* upload JSON files as docs on instance
* compress PNGs and SVGs in the current directory and its subdirectories

## Editing contacts across the hierarchy.
To edit existing couchdb documents, create a CSV file that contains the id's of the document you wish to update, and the columns of the document attribute(s) you wish to add/edit. By default, values are parsed as strings. To parse a CSV column as a JSON type, refer to the [Property Types](#property-types) section to see how you can parse the values to different types. Also refer to the [Excluded Columns](#excluded-columns) section to see how to exclude column(s) from being added to the docs.

Parameter | Description | Required
-- | -- | --
column(s) | Comma delimited list of columns you wish to add/edit. If this is not specified all columns will be added. | No
docDirectoryPath | This action outputs files to local disk at this destination | No. Default `json-docs`
file(s) | Comma delimited list of files you wish to process using edit-contacts. By default, contact.csv is searched for in the current directory and processed. | No.


### Example
1. Create a contact.csv file with your columns in the csv folder in your current path. The documentID column is a requirement. (The documentID column contains the document IDs to be fetched from couchdb.)

| documentID | is_in_emnch:bool |
| ----------------- | ---------------- |
| documentID1            | false            |
| documentID2            | false            |
| documentID3            | true             |

1. Use the following command to download and edit the documents:

```
medic-conf --instance=*instance* edit-contacts -- --column=*is_in_emnch* --docDirectoryPath=*my_folder*
```
1. Then upload the edited documents using the [upload-docs ](#examples) command.


# Project layout

This tool expects a project to be structured as follows:

	example-project/
		.eslintrc
		app_settings.json
		contact-summary.js
		privacy-policies.json
		privacy-policies/
		    language1.html
		    …
		purge.js
		resources.json
		resources/
			icon-one.png
			…
		targets.js
		tasks.js
		task-schedules.json
		forms/
			app/
				my_project_form.xlsx
				my_project_form.xml
				my_project_form.properties.json
				my_project_form-media/
					[extra files]
					…
			contact/
				person-create.xlsx
				person-create.xml
				person-create-media/
					[extra files]
					…
			…
			…
		translations/
			messages-xx.properties
			…

If you are starting from scratch you can initialise the file layout using the `initialise-project-layout` action:

    medic-conf initialise-project-layout

## Derived configs

Configuration can be inherited from another project, and then modified.  This allows the `app_settings.json` and contained files (`task-schedules.json`, `targets.json` etc.) to be imported, and then modified.

To achieve this, create a file called `settings.inherit.json` in your project's root directory with the following format:

	{
		"inherit": "../path/to/other/project",
		"replace": {
			"keys.to.replace": "value-to-replace-it-with"
		},
		"merge": {
			"complex.objects": {
				"will_be_merged": true
			}
		},
		"delete": [
			"all.keys.listed.here",
			"will.be.deleted"
		],
		"filter": {
			"object.at.this.key": [
				"will",
				"keep",
				"only",
				"these",
				"properties"
			]
		}
	}

# Fetching logs

Fetch logs from a CHT v2.x production server.

This is a standalone command installed alongside `medic-conf`.  For usage information, run `medic-logs --help`.

## Usage

	medic-logs <instance-name> <log-types...>

Accepted log types:

	api
	couchdb
	gardener
	nginx
	sentinel

# Development

To develop a new action or improve an existing one, check the ["Actions" doc](src/fn/README.md).

## Testing

Execute `npm test` to run static analysis checks and the test suite.

## Executing your local branch

1. Clone the project locally
1. Make changes to medic-conf or checkout a branch for testing
1. Test changes
	1. To test CLI changes locally you can run `node <project_dir>/src/bin/medic-conf.js`. This will run as if you installed via npm.
	1. To test changes that are imported in code run `npm install <project_dir>` to use the local version of medic-conf.

## Releasing

1. Create a pull request with prep for the new release. This should contain changes to release notes if required and anything else that needs to be done. As commit messages should be clear and readable for every change, [release-notes.md](./release-notes.md) does not need to be updated for every single change. Instead, it should include information about significant changes, breaking changes, changes to interfaces, changes in behavior, new feature details, etc.
1. Get the pull request reviewed and approved
1. Run `npm version patch`, `npm version minor`, or `npm version major` as appropriate. This will:
    - Update versions in `package.json` and `package-lock.json`
    - Commit those changes locally and tag that commit with the new version
1. Run `npm publish` to publish the new tag to npm
1. `git push && git push --tags` to push the npm generated commit and tag up to your pre-approved pull request
1. Merge the pull request back into master
1. Announce the release on the [CHT forum](https://forum.communityhealthtoolkit.org), under the "Product - Releases" category.

### Releasing betas

1. Checkout `master`
1. Run `npm version --no-git-tag-version <major>.<minor>.<patch>-beta.1`. This will only update the versions in `package.json` and `package-lock.json`. It will not create a git tag and not create an associated commit.
1. Run `npm publish --tag beta`. This will publish your beta tag to npm's beta channel.

To install from the beta channel, run `npm install medic-conf@beta`.

## Build status

Builds brought to you courtesy of GitHub actions. 

<img src="https://github.com/medic/medic-conf/actions/workflows/build.yml/badge.svg">

# Copyright

Copyright 2013-2019 Medic Mobile, Inc. <hello@medicmobile.org>

# License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

---
_Source: https://npm.io/package/medic-conf · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._