CONTRIBUTING.md

   1 Thank you for your contribution. OpenEMR (and global healthcare) continues to get better because of people like you!
   2
   3 The maintainers of OpenEMR want to get your pull request in as seamlessly as possible, so please ensure your code is consistent with our [development policies](https://open-emr.org/wiki/index.php/Development_Policies).
   4
   5 ## Code Contributions (local development)
   6
   7 You will need a "local" version of OpenEMR to make changes to the source code. The easiest way to do this is with [Docker](https://hub.docker.com/r/openemr/openemr/):
   8
   9 ---
  10
  11 ### Starting with OpenEMR Development Docker Environment
  12 - For the highly recommended free course "You Can Be a OpenEMR Developer in 5 Easy Steps", click below:
  13
  14     [You Can Be a OpenEMR Developer in 5 Easy Steps](https://www.open-emr.org/blog/you-can-be-a-openemr-developer-in-5-easy-steps/)
  15
  16 - For the Video Tutorial, click below:
  17
  18     [![Getting Started Video Tutorial](Documentation/images/easy-dev-intro.png)](https://youtu.be/D4tXP5G9-sY)
  19
  20     - (Recommend using Ubuntu Desktop 22.04 for above video and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
  21
  22 1. [Create your own fork of OpenEMR](https://github.com/openemr/openemr/fork) (you will need a GitHub account) and `git clone` it to your local machine.
  23
  24     - For the Video Tutorial, click below:
  25
  26       [![Getting Started Video Tutorial](Documentation/images/easy-dev-git.png)](https://youtu.be/QhTlWMqPV1Q)
  27
  28       - (Recommend using Ubuntu Desktop 22.04 for above video and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
  29
  30     - If you haven't already, [install git](https://git-scm.com/downloads) for your system
  31         - (optional) If you want to set up the base services(e.g. git, docker, docker-compose, openemr-cmd, minkube and kubectl) easily, please try [openemr-env-installer](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-env-installer)
  32     - (optional) It's best to also add an `upstream` origin to keep your local fork up to date. [Check out this guide](https://oneemptymind.wordpress.com/2018/07/11/keeping-a-fork-up-to-date/) for more info.
  33 2. `cd openemr/docker/development-easy` (if you are running this on Raspberry Pi, then instead do `cd openemr/docker/development-easy-arm32` or `cd openemr/docker/development-easy-arm64`)
  34     - If you haven't already, [install Docker](https://docs.docker.com/install/) and [install compose](https://docs.docker.com/compose/install/) for your system
  35     - (optional) If you want to troubleshoot with the below steps easier, please also [install openemr-cmd](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-cmd) for your system
  36     - (optional) If you want to monitor and easily manage the docker environment, please also [install openemr-monitor](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-monitor) and [install portainer](https://github.com/openemr/openemr-devops/tree/master/utilities/portainer) for your system
  37     - (optional) If you want to migrate the running docker environment, please try [openemr-env-migrator](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-env-migrator)
  38     - (optional) If you want to set up with orchestration tool, please try [OpenEMR Kubernetes Orchestrations](https://github.com/openemr/openemr-devops/tree/master/kubernetes/minikube)
  39 3. Run `docker-compose up` from your command line
  40     - When the build is done, you'll see the following message:
  41     ```sh
  42     openemr_1  | Love OpenEMR? You can now support the project via the open collective:
  43     openemr_1  |  > https://opencollective.com/openemr/donate
  44     openemr_1  |
  45     openemr_1  | Starting cron daemon!
  46     openemr_1  | Starting apache!
  47     ```
  48 4. Navigate to `http://localhost:8300/` or `https://localhost:9300/` to login as `admin`. Password is `pass`.
  49 5. If you wish to connect to the sql database, this docker environment provides the following 2 options:
  50     - Navigate to `http://localhost:8310/` where you can login into phpMyAdmin.
  51     - Or you can directly connect to port 8320 via your favorite sql tool (Mysql Workbench etc.).
  52     - Use `username/user`: openemr, `password`: openemr .
  53 6. Make changes to any files on your local file system. Most changes will appear after a refresh of the page or iFrame you're working on.
  54
  55     - For the Video Tutorials, click below:
  56
  57       [![Getting Started Video Tutorial](Documentation/images/easy-dev-vscode-xdebug.png)](https://youtu.be/XJl7SQGNhpw)
  58
  59       [![Getting Started Video Tutorial](Documentation/images/easy-dev-advanced-vscode-xdebug.png)](https://youtu.be/0dEYDHWECMI)
  60
  61       - (Recommend using Ubuntu Desktop 22.04 for above videos and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
  62
  63     - An exception to this is if making changes to styling scripts in interface/themes/. In that case will need to clear web browser cache and run the following command to rebuild the theme files:
  64       ```sh
  65       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools build-themes'
  66       ```
  67 7. When you're done, it's best to clean up after yourself with `docker-compose down -v`
  68     - If you don't want to build from scratch every time, just use `docker-compose down` so your next `docker-compose up` will use the cached volumes.
  69 8. To ensure you are using the most recent dockers, recommend running below set of commands intermittently:
  70     ```console
  71     docker pull openemr/openemr:flex
  72     docker pull mariadb:10.11
  73     docker pull phpmyadmin/phpmyadmin
  74     docker pull couchdb
  75     docker pull openemr/dev-ldap:easy
  76     ```
  77 9. [Submit a PR](https://github.com/openemr/openemr/compare) from your fork into `openemr/openemr#master`!
  78
  79 We look forward to your contribution...
  80
  81 ---
  82
  83 ### Advanced Use of OpenEMR Development Docker Environment
  84
  85 The OpenEMR development docker environment has a very rich advanced feature set. See below Index for links to all the cool advanced stuff:
  86
  87 **Index for Advanced Use of OpenEMR Development Docker Environment**
  88
  89 ---
  90
  91 1. [Xdebug and profiling](#xdebug)
  92 2. [API development and testing](#api)
  93 3. [Testing other PHP versions](#other_php_versions)
  94 4. [Php syntax checking, psr12 checking, and automated testing](#dev_tools_tests)
  95 5. [Run the entire dev tool suite](#dev_tools_suite)
  96 6. [Run only all the automated tests](#dev_tools_auto)
  97 7. [Resetting OpenEMR and loading demo data](#dev_tools_reset)
  98 8. [Backup and restore OpenEMR data](#dev_tools_backup)
  99 9. [Send/receive snapshots](#dev_tools_send)
 100 10. [Create and add random patient data](#dev_tools_randompatients)
 101 11. [Add multisite bank](#dev_tools_bankmultisite)
 102 12. [Turn on and turn off support for multisite feature in setup.php](#dev_tools_multisite)
 103 13. [List the current multisite](#dev_tools_listmultisite)
 104 14. [Change the database character set and collation](#dev_tools_charset)
 105 15. [Test ssl certificate and force/unforce https](#dev_tools_https)
 106 16. [Place/remove testing sql ssl certificate and testing sql ssl client key/cert](#dev_tools_ssl)
 107 17. [CouchDB integration](#dev_tools_couchdb)
 108 18. [LDAP integration](#dev_tools_ldap)
 109 19. [Test webroot value](#dev_tools_webroot)
 110
 111 ---
 112
 113 1. <a name="xdebug"></a>Xdebug and profiling is supported for PHPStorm and VSCode.
 114
 115     - For the Video Tutorial, click below:
 116
 117       [![Getting Started Video Tutorial](Documentation/images/easy-dev-vscode-xdebug.png)](https://youtu.be/XJl7SQGNhpw)
 118
 119       - (Recommend using Ubuntu Desktop 22.04 for above video and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
 120
 121      - Firefox/Chrome install xdebug helper add on and enable
 122     - PHPStorm Settings->Language & Frameworks->PHP->Debug
 123         - Start listening
 124         - Untoggle "Break at first line in PHP scripts"
 125         - Untoggle both settings that start with "Force Break at first line..."
 126         - See [these images for more detail](https://github.com/openemr/openemr-devops/pull/283#issuecomment-779798156)
 127     - VSCode
 128         - Listen for XDebug
 129         - Use this `launch.json` [template](https://github.com/openemr/openemr-devops/issues/285#issuecomment-782899207)
 130     - Make sure port 9003 is open on your host operating system
 131     - Profiling output can be found in /tmp directory in the docker. Following will list the profiling output files:
 132       ```sh
 133       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-xdebug-profiles'
 134       ```
 135     - To check Xdebug log:
 136       ```sh
 137       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools xdebug-log'
 138       ```
 139 2. <a name="api"></a>API development and testing.
 140     - Swagger is including in OpenEMR to ease API documentation, development, and testing.
 141     - The following command will update the API documentation (derive documentation from [_rest_routes.inc.php](_rest_routes.inc.php) to [swagger/openemr-api.yaml](swagger/openemr-api.yaml)):
 142       ```sh
 143       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools build-api-docs'
 144       ```
 145     - Can go to Swagger at [https://localhost:9300/swagger](https://localhost:9300/swagger) where it is super easy to test the API:
 146         - First, click on 'Authorize' button.
 147         - Then click 'Select All' scopes.
 148         - Can then do the following from command line to get a client id and secret, which then can copy/paste into the fields:
 149           ```sh
 150           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools register-oauth2-client'
 151           ```
 152         - Then click 'Authorize' button and follow the flow and before you know it, you will be authorized to test the api endpoints!
 153     - There is also a mechanism to allow use of the above Swagger tool with multisite.
 154         - Before going to the Swagger gui linked above, run the following command (after running below command, the Swagger gui will then be configured to work with the selected multisite):
 155           ```sh
 156           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools set-swagger-to-multisite <multisite-name>'
 157           ```
 158         - To collect a client id and secret for the selected multisite, can then do:
 159           ```sh
 160           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools register-oauth2-client <multisite-name>'
 161           ```
 162         - When done testing with Swagger on the selected multisite, recommend setting swagger back to the default multisite to avoid changes to the swagger configuration script showing up in your local git repository:
 163           ```sh
 164           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools set-swagger-to-multisite'
 165           ```
 166     - There is also a dev tool to make it easy to test the API on the online OpenEMR demo farm. For example, what if you wanted to test the API at [https://eleven.openemr.io/a/openemr](https://eleven.openemr.io/a/openemr):
 167         - Go to [https://eleven.openemr.io/a/openemr/swagger](https://eleven.openemr.io/a/openemr/swagger/index.html) and follow the Swagger gui flow above. The following command can be used to get a client id and secret from that online demo:
 168           ```sh
 169           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools register-oauth2-client-demo https://eleven.openemr.io/a/openemr'
 170           ```
 171 3. <a name="other_php_versions"></a>Testing other PHP versions.
 172     - The standard `flex` docker used in the easy development environments is PHP 8.3. This can be modified by changing the image (`image: openemr/openemr:flex`) used in the docker-compose.yml script. To use PHP 8.1, then just need to change it to `image: openemr/openemr:flex-3.17`. To use PHP 8.2, then just need to change it to `image: openemr/openemr:flex-3.18`.
 173 4. <a name="dev_tools_tests"></a>Php syntax checking, psr12 checking, and automated testing.
 174     - To check PHP error logs:
 175       ```sh
 176       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools php-log'
 177       ```
 178     - To create a report of PSR12 code styling issues (this takes several minutes):
 179       ```sh
 180       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools psr12-report'
 181       ```
 182     - To fix PSR12 code styling issues (this takes several minutes):
 183       ```sh
 184       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools psr12-fix'
 185       ```
 186     - To create a report of theme styling issues:
 187       ```sh
 188       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools lint-themes-report'
 189       ```
 190     - To fix theme styling issues:
 191       ```sh
 192       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools lint-themes-fix'
 193       ```
 194     - To check PHP parsing errors (this takes several minutes):
 195       ```sh
 196       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools php-parserror'
 197       ```
 198     - To run unit testing:
 199       ```sh
 200       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools unit-test'
 201       ```
 202     - To run api testing:
 203       ```sh
 204       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools api-test'
 205       ```
 206     - To run e2e testing:
 207       ```sh
 208       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools e2e-test'
 209       ```
 210     - To run services testing:
 211       ```sh
 212       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools services-test'
 213       ```
 214     - To run fixtures testing:
 215       ```sh
 216       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools fixtures-test'
 217       ```
 218     - To run validators testing:
 219       ```sh
 220       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools validators-test'
 221       ```
 222     - To run controllers testing:
 223       ```sh
 224       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools controllers-test'
 225       ```
 226     - To run common testing:
 227       ```sh
 228       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools common-test'
 229       ```
 230 5. <a name="dev_tools_suite"></a>Run the entire dev tool suite (PSR12 fix, lint themes fix, PHP parse error, unit/API/e2e/services/fixtures/validators/controllers/common tests) in one command, run
 231     ```sh
 232     docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools clean-sweep'
 233     ```
 234 6. <a name="dev_tools_auto"></a>Run only all the automated tests (unit/API/e2e/services/fixtures/validators/controllers/common tests) in one command, run
 235     ```sh
 236     docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools clean-sweep-tests'
 237     ```
 238 7. <a name="dev_tools_reset"></a>Resetting OpenEMR and loading demo data.
 239     - For the Video Tutorial, click below:
 240
 241       [![Resetting and Demo Data Video Tutorial](Documentation/images/easy-dev-reset.png)](https://youtu.be/1ch84Ffmky8)
 242
 243       - (Recommend using Ubuntu Desktop 22.04 for above video and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
 244
 245     - To reset OpenEMR only (then can reinstall manually via setup.php in web browser):
 246       ```sh
 247       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset'
 248       ```
 249         - When running setup.php, need to use `mysql` for 'Server Host', `root` for 'Root Password', and `%` for 'User Hostname'.
 250     - To reset and reinstall OpenEMR:
 251       ```sh
 252       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset-install'
 253       ```
 254     - To reset and reinstall OpenEMR with demo data (this includes several users with access controls setup in addition to patient portal logins. [See HERE for those credentials](https://www.open-emr.org/wiki/index.php/Development_Demo#Demo_Credentials).):
 255       ```sh
 256       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools dev-reset-install-demodata'
 257       ```
 258         - hint: this is also a great way to test any changes a developer has made to the sql upgrade stuff (ie. such as sql/5_0_2-to-6_0_0_upgrade.sql)
 259 8. <a name="dev_tools_backup"></a>Backup and restore OpenEMR data (database and data on drive) via snapshots.
 260     - For the Video Tutorial, click below:
 261
 262       [![Snapshots and Capsules Video Tutorial](Documentation/images/easy-dev-snapshots-capsules.png)](https://youtu.be/n569Lw5I5us)
 263
 264       - (Recommend using Ubuntu Desktop 22.04 for above video and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
 265
 266      - Create a backup snapshot (using `example` below, but can use any alphanumeric identifier):
 267       ```sh
 268       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools backup example'
 269       ```
 270     - Restore from a snapshot (using `example` below, but can use any alphanumeric identifier)
 271       ```sh
 272       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools restore example'
 273       ```
 274     - To list the snapshots
 275       ```sh
 276       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-snapshots'
 277       ```
 278 9. <a name="dev_tools_send"></a>Send/receive snapshots (via capsules) that are created above in item 8.
 279     - For the Video Tutorial, click below:
 280
 281       [![Snapshots and Capsules Video Tutorial](Documentation/images/easy-dev-snapshots-capsules.png)](https://youtu.be/n569Lw5I5us)
 282
 283       - (Recommend using Ubuntu Desktop 22.04 for above video and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
 284
 285     - Here is how to grab a capsule from the docker, which can then store or share with friends.
 286         - List the capsules:
 287           ```sh
 288           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-capsules'
 289           ```
 290         - Copy the capsule from the docker to your current directory (using `example.tgz` below):
 291           ```sh
 292           docker cp $(docker ps | grep _openemr | cut -f 1 -d " "):/snapshots/example.tgz .
 293           ```
 294     - Here is how to send a capsule into the docker.
 295         - Copy the capsule from current directory into the docker (using `example.tgz` below):
 296           ```sh
 297           docker cp example.tgz $(docker ps | grep _openemr | cut -f 1 -d " "):/snapshots/
 298           ```
 299         - Restore from the new shiny snapshot (using `example` below):
 300           ```sh
 301           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools restore example'
 302           ```
 303         - Ensure run upgrade to ensure will work with current version OpenEMR:
 304           ```sh
 305           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools upgrade 5.0.2'
 306           ```
 307 10. <a name="dev_tools_randompatients"></a>Create and add random patient data. This will use synthea to create random patients that are then imported into OpenEMR. You can choose the number of patients. Note that each patient will take several seconds.
 308     - For the Video Tutorial, click below:
 309
 310       [![Creating Random Patients Video Tutorial](Documentation/images/easy-dev-random-pat.png)](https://youtu.be/cFBFXFm_Psg)
 311
 312       - (Recommend using Ubuntu Desktop 22.04 for above video and other videos in the [OpenEMR Easy Docker Development Environment Video Series](https://www.youtube.com/playlist?list=PLFiWG_dDadgQT7zjqvEqbXm1OiuubOVO8). Easiest way to do this is setting up a [Ubuntu Desktop 22.04 Virtual Machine on VirtualBox](https://ubuntu.com/tutorials/how-to-run-ubuntu-desktop-on-a-virtual-machine-using-virtualbox), which recommend configuring with 40GB hard drive, assigning 25% of computer memory, and assigning 25% of cpu cores to the virtual machine.)
 313
 314     - Create and add 100 random patients (defaults to development mode set to true, which is set be default to true; development mode will markedly improve performance by bypassing the import of the ccda document and bypassing the use of the audit_master and audit_details tables and will directly import the new patient data from the ccda. Note this should never be done on sites that already contain real data/use, and it will also turn off the audit log during the import.):
 315        ```sh
 316        docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools import-random-patients 100'
 317        ```
 318        or
 319        ```sh
 320        docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools import-random-patients 100 true'
 321        ```
 322     - Create and add 100 random patients (with development mode set to false)
 323        ```sh
 324        docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools import-random-patients 100 false'
 325        ```
 326 11. <a name="dev_tools_bankmultisite"></a>Create a bank of multisites with selected number of multisites that are all labelled from run1..runx. It will clone from the default instance. This can be helpful for testing of multisites and other larger scale testing.
 327     - Create 5 multisites (will be run1, run2, run3, run4, run5):
 328       ```sh
 329       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools generate-multisite-bank 5'
 330       ```
 331 12. <a name="dev_tools_multisite"></a>Turn on and turn off support for multisite feature (to allow setting up multisites in setup.php script).
 332     - Turn on support for multisite:
 333       ```sh
 334       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools enable-multisite'
 335       ```
 336     - Turn off support for multisite:
 337       ```sh
 338       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools disable-multisite'
 339       ```
 340 13. <a name="dev_tools_listmultisite"></a>The available multsites can be listed via following command:
 341     ```sh
 342     docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-multisites'
 343     ```
 344 14. <a name="dev_tools_charset"></a>Change the database character set and collation (character set is the encoding that is used to store data in the database; collation are a set of rules that the database uses to sort the stored data).
 345     - Best to demonstrate this devtool with examples.
 346         - Set character set to utf8mb4 and collation to utf8mb4_general_ci (this is default for OpenEMR 6 and higher):
 347           ```sh
 348           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8mb4 utf8mb4_general_ci'
 349           ```
 350         - Set character set to utf8mb4 and collation to utf8mb4_unicode_ci:
 351           ```sh
 352           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8mb4 utf8mb4_unicode_ci'
 353           ```
 354         - Set character set to utf8mb4 and collation to utf8mb4_vietnamese_ci:
 355           ```sh
 356           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8mb4 utf8mb4_vietnamese_ci'
 357           ```
 358         - Set character set to utf8 and collation to utf8_general_ci (this is default for OpenEMR 5 and lower):
 359           ```sh
 360           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools change-encoding-collation utf8 utf8_general_ci'
 361           ```
 362 15. <a name="dev_tools_https"></a>Test ssl certificate (to test client based certificates and revert back to default self signed certificate) and force/unforce https.
 363     - To test client based certificates, create a zip package of the certificate in OpenEMR at Administration->System->Certificates. Then can import this zip package (example `ssl.zip`) into the docker via:
 364       ```sh
 365       docker cp ssl.zip $(docker ps | grep _openemr | cut -f 1 -d " "):/certs/
 366       ```
 367     - To list the available certificate packages on docker:
 368       ```sh
 369       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools list-client-certs'
 370       ```
 371     - To install and configure a certificate package (example `ssl`):
 372       ```sh
 373       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools setup-client-cert ssl'
 374       ```
 375     - To revert back to selfsigned certicates (ie. revert the changes required for client based certificates):
 376       ```sh
 377       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools on-self-signed-cert'
 378       ```
 379     - To force https in apache script via redirect:
 380       ```sh
 381       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools force-https'
 382       ```
 383     - To revert the changes that forced https in apache script:
 384       ```sh
 385       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools un-force-https'
 386       ```
 387 16. <a name="dev_tools_ssl"></a>Place/remove testing sql ssl certificate and testing sql ssl client key/cert.
 388     - Place the testing sql ssl CA cert:
 389       ```sh
 390       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl'
 391       ```
 392     - Remove the testing sql ssl CA cert:
 393       ```sh
 394       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl-off'
 395       ```
 396     - Place the testing sql ssl CA cert and testing sql ssl client key/cert:
 397       ```sh
 398       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl-client'
 399       ```
 400     - Remove the testing sql ssl CA cert and testing sql ssl client key/cert:
 401       ```sh
 402       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools sql-ssl-client-off'
 403       ```
 404 17. <a name="dev_tools_couchdb"></a>CouchDB integration.
 405     - In OpenEMR, CouchDB is an option for the patients document storage. For this reason, a CouchDB docker is included in this OpenEMR docker development environment. You can visit the CouchDB GUI directly via http://localhost:5984/_utils/ or https://localhost:6984/_utils/ with username `admin` and password `password`. You can configure OpenEMR to use this CouchDB docker for patient document storage in OpenEMR at Administration->Globals->Documents:
 406         - Document Storage Method->CouchDB
 407     - After running the following devtools, 'dev-reset', 'dev-install', 'dev-reset-install', 'dev-reset-install-demodata', 'restore-snapshot', then need to restart the couchdb docker via the following command:
 408         ```sh
 409         docker restart $(docker ps | grep _couchdb_1 | cut -f 1 -d " ")
 410         ```
 411     - Developer tools to place/remove testing couchdb ssl certificate and testing couchdb ssl client key/cert.
 412         - Place the testing couchdb ssl CA cert:
 413           ```sh
 414           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl'
 415           ```
 416         - Remove the testing couchdb ssl CA cert:
 417           ```sh
 418           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl-off'
 419           ```
 420         - Place the testing couchdb ssl CA cert and testing couchdb ssl client key/cert:
 421           ```sh
 422           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl-client'
 423           ```
 424         - Remove the testing couchdb ssl CA cert and testing couchdb ssl client key/cert:
 425           ```sh
 426           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools couchdb-ssl-client-off'
 427           ```
 428 18. <a name="dev_tools_ldap"></a>LDAP integration.
 429     - In OpenEMR, LDAP is an option for authentication. If this is turned on, then this will be supported for the `admin` user, which will use the following password: `admin`
 430     - Turn on LDAP:
 431       ```sh
 432       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools enable-ldap'
 433       ```
 434     - Turn off LDAP:
 435       ```sh
 436       docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools disable-ldap'
 437       ```
 438     - Developer tools to place/remove testing ldap tls/ssl certificate and testing ldap tls/ssl client key/cert.
 439         - Place the testing ldap tls/ssl CA cert:
 440           ```sh
 441           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl'
 442           ```
 443         - Remove the testing ldap tls/ssl CA cert:
 444           ```sh
 445           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl-off'
 446           ```
 447         - Place the testing ldap tls/ssl CA cert and testing ldap tls/ssl client key/cert:
 448           ```sh
 449           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl-client'
 450           ```
 451         - Remove the testing ldap tls/ssl CA cert and testing ldap tls/ssl client key/cert:
 452           ```sh
 453           docker exec -i $(docker ps | grep _openemr | cut -f 1 -d " ") sh -c '/root/devtools ldap-ssl-client-off'
 454           ```
 455 19. <a name="dev_tools_webroot"></a>Test webroot value.
 456     - The default setup of the docker development environments are with a blank webroot, however, it is a good idea to also test with a webroot setting. There is an option to set the webroot to openemr.
 457     - Note this dev tool requires the use of the openemr-cmd script, which is discussed above and can find instructions to install and use openemr-cmd script at [install openemr-cmd](https://github.com/openemr/openemr-devops/tree/master/utilities/openemr-cmd).
 458     - Set webroot to blank:
 459       ```sh
 460       openemr-cmd change-webroot-blank
 461       ```
 462     - Set webroot to `openemr`:
 463       ```sh
 464       openemr-cmd change-webroot-openemr
 465       ```
 466
 467 ### Non-docker Use
 468
 469 If you do not want to use Docker, you can always install OpenEMR directly on your local environment. This will require installing additional dependencies for your operating system. For more info see [OpenEMR Development Versions](https://open-emr.org/wiki/index.php/OpenEMR_Installation_Guides#OpenEMR_Development_Versions) on the wiki.
 470
 471 ## Financial contributions
 472
 473 We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/openemr).
 474 Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.
 475
 476 ## Credits
 477
 478 ### Contributors
 479
 480 Thank you to all the people who have already contributed to openemr!
 481 <a href="https://github.com/openemr/openemr/graphs/contributors"><img src="https://opencollective.com/openemr/contributors.svg?width=890" /></a>
 482
 483 ### Backers
 484
 485 Thank you to all our backers! [[Become a backer](https://opencollective.com/openemr#backer)]
 486
 487 <a href="https://opencollective.com/openemr#backers" target="_blank"><img src="https://opencollective.com/openemr/backers.svg?width=890"></a>
 488
 489 ### Sponsors
 490
 491 Thank you to all our sponsors! (please ask your company to also support this open source project by [becoming a sponsor](https://opencollective.com/openemr#sponsor))
 492
 493 <a href="https://opencollective.com/openemr/sponsor/0/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/0/avatar.svg"></a>
 494 <a href="https://opencollective.com/openemr/sponsor/1/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/1/avatar.svg"></a>
 495 <a href="https://opencollective.com/openemr/sponsor/2/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/2/avatar.svg"></a>
 496 <a href="https://opencollective.com/openemr/sponsor/3/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/3/avatar.svg"></a>
 497 <a href="https://opencollective.com/openemr/sponsor/4/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/4/avatar.svg"></a>
 498 <a href="https://opencollective.com/openemr/sponsor/5/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/5/avatar.svg"></a>
 499 <a href="https://opencollective.com/openemr/sponsor/6/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/6/avatar.svg"></a>
 500 <a href="https://opencollective.com/openemr/sponsor/7/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/7/avatar.svg"></a>
 501 <a href="https://opencollective.com/openemr/sponsor/8/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/8/avatar.svg"></a>
 502 <a href="https://opencollective.com/openemr/sponsor/9/website" target="_blank"><img src="https://opencollective.com/openemr/sponsor/9/avatar.svg"></a>