Medic Conf is a command-line interface tool to manage and configure your apps built using the Core Framework of the Community Health Toolkit.
- nodejs 8 or later
- python 2.7
- or Docker
docker build -t medic-conf:v0 .
docker run medic-conf:v0
docker exec -it <container_name> /bin/bash
npm install -g medic-conf
sudo python -m pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
npm install -g medic-conf
pip install git+https://github.com/medic/pyxform.git@medic-conf-1.17#egg=pyxform-medic
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
To enable tab completion in bash, add the following to your .bashrc
/.bash_profile
:
eval "$(medic-conf --shell-completion=bash)"
To upgrade to the latest version
npm install -g medic-conf
medic-conf
will upload the configuration from your current directory.
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.
For developers, this is the instance defined in your COUCH_URL
environment variable.
medic-conf --local
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
medic-conf --url=https://username:password@example.com:12345
medic-conf --archive
The resulting archive is consumable by Medic's API >v3.7 to create default configurations.
medic-conf <--archive|--local|--instance=instance-name|--url=url> <...action>
The list of available actions can be seen via medic-conf --help
.
medic-conf <--local|--instance=instance-name|--url=url> <...action> -- <...form>
- compile app settings from:
- tasks
- rules
- schedules
- contact-summary
- purge
- backup app settings from server
- upload app settings to server
- upload resources to server
- upload custom translations to the server
- 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
- 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
This tool expects a project to be structured as follows:
example-project/
.eslintrc
app_settings.json
contact-summary.js
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
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"
]
}
}
Fetch logs from a production server.
This is a standalone command installed alongside medic-conf
. For usage information, run medic-logs --help
.
medic-logs <instance-name> <log-types...>
Accepted log types:
api
couchdb
gardener
nginx
sentinel
- Clone the project locally
- Make changes to medic-conf or checkout a branch for testing
- Test changes
- 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. - To test changes that are imported in code run
npm install <project_dir>
to use the local version of medic-conf.
- To test CLI changes locally you can run
- 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 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.
- Get the pull request reviewed and approved
- Run
npm version patch
,npm version minor
, ornpm version major
as appropriate. This will:- Update versions in
package.json
andpackage-lock.json
- Commit those changes locally and tag that commit with the new version
- "Compile" and publish the changes to npm
- Update versions in
git push && git push --tags
to push the npm generated commit and tag up to your pre-approved pull request- Merge the pull request back into master
Builds brought to you courtesy of Travis CI.
Copyright 2013-2019 Medic Mobile, Inc. hello@medicmobile.org
The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.