CHT Upgrade Service

The CHT Upgrade Service provides an interface between CHT-Core API and Docker to allow easy startup and one-click upgrades from the CHT-Core Admin UI.

Requirements

• Docker
• docker-compose

Directories

To use the CHT Upgrade service, you need to have three directories:

1. CHT Core & CouchDB compose files
2. CouchDB database
3. Upgrade Service

Example Usage

Assuming you wanted to create a new project called cht-4-first-run in your user me's home directory, and you want to use the least amount of env vars, you would follow these steps below. It will create a self signed cert, use port 80 and port 443. If you're doing a lot of testing, you might want to ensure no other docker containers are running with docker kill $(docker ps -q). Then follow these steps:

1. Create a directory to house your CHT Core and CouchDB compose files. You need a unique pair of these per project you run. We'll use cht-4-first-run:

   mkdir -p ~/cht-4-first-run/compose
   cd ~/cht-4-first-run

2. Download CHT Core, CouchDB and Upgrade Service compose files into the new directory you just created:

   cd ~/cht-4-first-run
   curl -s -o ./compose/cht-couchdb.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:master/docker-compose/cht-couchdb.yml
   curl -s -o ./compose/cht-core.yml https://staging.dev.medicmobile.org/_couch/builds_4/medic:medic:master/docker-compose/cht-core.yml
   curl -s -o docker-compose.yml https://raw.githubusercontent.com/medic/cht-upgrade-service/main/docker-compose.yml

3. Create a file in ~/cht-4-first-run to house your variables. Call it .env and give it the following contents (Note these are insecure password - use secure password for production!). Note if you're trying to run this locally that you replace /home/me with your actual home dir path:

   CHT_COMPOSE_PROJECT_NAME=4-first-run
   COUCHDB_SECRET=password
   DOCKER_CONFIG_PATH=/home/me/cht-4-first-run/compose
   COUCHDB_DATA=/home/me/cht-4-first-run/couchd
   CHT_COMPOSE_PATH=/home/me/cht-4-first-run/compose
   COUCHDB_USER=medic
   COUCHDB_PASSWORD=password

4. Call up with docker:

   cd ~/cht-4-first-run
   docker compose up

   1. Your instance should now be available at localhost with login medic and password password. You will need to accept the self signed certificate the first time you access the instance.

Environment Variables

This is a list of all variables that can be used:

API

The API is only available on the cht-net docker network, and listens to port 5008.

GET /

Expected response: HTTP/1.1 200

{ "ok": true }

POST /upgrade

Accepts a payload that contains pairs of docker-compose file names and contents. It

• overwrites the files with the corresponding name in the CHT_COMPOSE_PATH folder
• validates the contents of each file before overwriting
• does not create new files, if a matching file does not already exist in CHT_COMPOSE_PATH folder, writing is skipped
• pulls docker images from every updated file (docker-compose pull -f <file>)
• when all files have been processed, executes a docker-compose up over all files in the folder, restarting the containers that have new images.

Request body: Accepts: application/json

{
  "docker_compose": {
    "<file_name1>": "<file contents>",
    "<file_name2>": "<file contents>"
  }
}

Expected successful response: HTTP/1.1 200

{
  "<file_name1>": { "ok": true },
  "<file_name2>": { "ok": true }
}

Expected successful response when a file is skipped: HTTP/1.1 200

{
  "<existent_file>": { "ok": true },
  "<non_existent_file>": { "ok": false, "reason": "Existing installation not found. Use '/install' API to install." }
}

Expected error response: HTTP/1.1 500

{
  "error": true,
  "reason": "<error details>"
}

POST /install

Accepts a payload that contains pairs of docker-compose file names and contents. It

• creates the files with the corresponding name in the CHT_COMPOSE_PATH folder
• validates the contents of each file before creation
• does not overwrite existing files, if a matching file already exists in CHT_COMPOSE_PATH folder, writing is skipped
• pulls docker images from every updated file (docker-compose pull -f <file>)
• when all files have been processed, does a docker-compose up over all files in the folder, which start the new containers.

Request body: Accepts: application/json

{
  "docker_compose": {
    "<file_name1>": "<file contents>",
    "<file_name2>": "<file contents>"
  }
}

Expected successful response: HTTP/1.1 200

{
  "<file_name1>": { "ok": true },
  "<file_name2>": { "ok": true }
}

Expected successful response when a file is skipped: HTTP/1.1 200

{
  "<existent_file>": { "ok": false, "reason": "Existing installation found. Use '/upgrade' API to upgrade." },
  "<non_existent_file>": { "ok": true }
}

Expected error response: HTTP/1.1 500

{
  "error": true,
  "reason": "<error details>"
}

POST /start

Starts all containers from all valid docker compose files in the CHT_COMPOSE_PATH folder.

Expected response: HTTP/1.1 200

{ "ok": true }