Building > Getting started
Setting up a local environment to build and test CHT 4.x applications
Couch2pg is deprecated. For data synchronization, refer to CHT Sync.
This tutorial will take you through setting up a Couch2pg service.
By the end of the tutorial you should be able to:
CHT Couch2pg is a background process that moves data from Couchdb to Postgres through one way replication. It therefore, needs to have full read and write access to both the Postgres Database and Couchdb upstream. It is built in nodejs and can be set up as a background process using systemd. Review this architecture diagram to get a conceptual understanding of how couch2pg works.
COUCHDB_URL is the CouchDB instance URL with no trailing slash after /medic
, format: https://[user]:[password]@localhost:[port]/medic
POSTGRESQL_URL is the PostgreSQL instance URL, format: postgres://[user]:[password]@localhost:[port]/[database name]
COUCH2PG_SLEEP_MINS is the interval size in minutes Couch2pg will use to poll Couchdb.
COUCH2PG_DOC_LIMIT is the number of documents Couch2pg will fetch in each query.
COUCH2PG_RETRY_COUNT is the amount of times couch2pg should retry a failed connection before it fails.
COUCH2PG_CHANGES_LIMIT is the number of changes to query since the last sync operation.
To read more about environmental variables, see the CHT Couch2pg readme.
Before you begin, you need to have some useful software and tools that are required for things to work:
You should have a functioning CHT instance installed locally
You should have a working database with a user that has full creation rights on the database. A database POSTGRES_DB_NAME
and couch2pg
user can be created and access granted using the following query:
CREATE DATABASE POSTGRES_DB_NAME;
CREATE USER couch2pg WITH ENCRYPTED PASSWORD 'mypassword';
GRANT ALL PRIVILEGES ON DATABASE POSTGRES_DB_NAME TO couch2pg;
All steps below require you to have a local clone of the repo.
git clone https://github.com/medic/cht-couch2pg.git
Change directory into the repo’s directory where you cloned it: cd /path/to/cht-couch2pg
Install dependencies: npm ci
Export the four variables with the correct values:
export POSTGRESQL_URL=postgres://[user]:[password]@localhost:[port]/[database name]
export COUCHDB_URL=https://[user]:[password]@localhost:[port]/medic
export COUCH2PG_DOC_LIMIT=1000
export COUCH2PG_RETRY_COUNT=5
export COUCH2PG_SLEEP_MINS=120
export COUCH2PG_CHANGES_LIMIT=1000
node .
If you want to set and save all possible variables:
Copy sample.env
to couch2pg.env
: cp sample.env couch2pg.env
Edit couch2pg.env
to have all the variables you need.
POSTGRESQL_URL
shouldn’t be edited as it is defined by the variables above it.. ./couch2pg.env && node .
node . -i
. You will be prompted to answer questions to capture the same the environmental variables. For each question, you will be given suggestions for an answer.The simplest way to run couch2pg is with docker-compose
which only needs configuration of the CouchDB instance URL. The compose file will then create a PostgreSQL container, connect to the CouchDB server and proceed to download couchDB documents to the PostgreSQL container:
Change directory into the repo’s directory where you cloned it: cd /path/to/cht-couch2pg
Set the URL for CouchDB in the COUCHDB_URL
env variable. e.g.
export COUCHDB_URL=https://medic:password@192-168-68-26.local-ip.medicmobile.org:8442/medic
Run: docker-compose up
Connect to the PostgreSQL instance with login cht_couch2pg
, password cht_couch2pg_password
and database cht
.
POSTGRES_SERVER_NAME
, use login from COUCH2PG_USER
, password from COUCH2PG_USER_PASSWORD
and the database from POSTGRES_DB_NAME
.If the error Error: Unknown authenticationOk message typeMessage { name: 'authenticationOk', length: 23 }
is observed, it is because Postgres is setup to use a different password encryption algorithm compared to what Couch2pg uses. Couch2pg was made to work with md5
which is the default method in Postgres v10-13. However, on postgres v14 the default method is scram-sha-256
detailed in the notes.
The setting can be updated in the Postgres configuration file which is in /etc/postgresql/14/main/postgres.conf
in Ubuntu 20.04. The key password_encryption
should be set to md5. After updating the setting, restart the Postgres service.
To confirm that the role used with couch2pg has an md5 encrypted password use the query SELECT rolname, rolpassword FROM pg_authid
. The role password should start with md5.
Setting up a local environment to build and test CHT 4.x applications
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.