contrib/util/docker/README.md

   1 # OpenEMR Local Development Docker
   2
   3 This is a development Docker Compose solution for programming OpenEMR. New and
   4 existing contributors can enjoy the benefits of simply running/testing their
   5 local code with a single command!
   6
   7 _Note: This is only to be used for local development purposes. For
   8 production-grade docker deployment options, please check out
   9 [openemr-devops](https://github.com/openemr/openemr-devops)._
  10
  11 ## Setup
  12
  13 **Step 1.** Install [git](https://git-scm.com/downloads),
  14 [docker](https://www.docker.com/get-docker) and
  15 [compose](https://docs.docker.com/compose/install/) for your system. Also, make
  16 sure you have a [fork](https://help.github.com/articles/fork-a-repo/) of OpenEMR.
  17
  18 **Step 2.** Start OpenEMR.
  19 ```bash
  20 $ git clone git@github.com:YOUR_USERNAME/openemr.git
  21 ```
  22 There are 2 different schools of thought on where to run the docker from.
  23 - Option 1. Run the docker from within your git repository.(this is also where you edit
  24 scripts in your editor)
  25 ```bash
  26 $ cd openemr
  27 $ docker-compose up -d
  28 ```
  29 - Option 2. Run the docker from a separate directory that is synchronized with your git
  30 repository. For example, if used /var/www/openemr.
  31 ```bash
  32  $ cd /var/www/openemr
  33  $ docker-compose up -d
  34 ```
  35 - At this time, I highly recommend option 2 since running OpenEMR will change
  36 scripts, add files, add cache files, thus making it very tough to track your
  37 code change. Modern GUI Editors support this; for example PHPStorm can be
  38 set up to do this every time you save a script via
  39 [PHP Storm Customizing Upload](https://www.jetbrains.com/help/phpstorm/customizing-upload.html).
  40  - Option 2 also allows support to quickly change branches on a repository to
  41 develop/test other code. This is done by first running a command or script
  42 to delete and replace the synchronized directory (ie. remove the /var/www/openemr
  43 directory) and then restart the development docker (see below for how to do this)
  44
  45 **Step 3.** Open up OpenEMR in the latest Chrome or Firefox! You have several
  46 options to choose from:
  47 - http://localhost:8080 (with PHP 7.1)
  48 - http://localhost:8081 (with PHP 7.2)
  49 - https://localhost:8090 with SSL (with PHP 7.1)
  50 - https://localhost:8091 with SSL (with PHP 7.2)
  51
  52 **Step 4.** Setup up OpenEMR. The first time you run OpenEMR (and whenever you clear and replace your
  53 synchronized openemr directory and restart the development docker). On the main
  54 setup input screen:
  55  - for `Server Host`, use either `mariadb` or `mysql` or `mariadb-dev` or `mysql-dev` (you have all
  56  mariadb/mysql/mariadb-dev/mysql-dev dockers ready to go to make testing either one easy;
  57  `mysql` is version 5.7 and `mysql-dev` is version 8; `mariadb` is version 10.2 and
  58  `mariadb-dev` is version 10.3)
  59  - for `Root Pass`, use `root`
  60  - for `User Hostname`, use `%`
  61
  62 ## Stop/Clean Out Dockers
  63 There are frequently times where you will want to remove the dockers and start anew.
  64 For example, when you change github branches and start testing/developing on a
  65 different github branch. This is done by first running a command or script
  66 to delete and replace the synchronized directory (ie. remove the /var/www/openemr
  67 directory) and then restart the development docker:
  68 ```bash
  69 docker-compose down -v
  70 docker-compose up -d
  71 ```
  72
  73 ## Usage
  74
  75 ### Examine Containers
  76
  77 Run `$ docker ps` to see the OpenEMR and MySQL containers in the following format:
  78
  79 ```
  80 CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS                                         NAMES
  81 6e9cc265cc50        openemr/openemr:flex        "./run_openemr.sh"       6 seconds ago       Up 3 seconds        0.0.0.0:8080->80/tcp, 0.0.0.0:8090->443/tcp   openemr_openemr-7-1_1
  82 a343e24faa3c        couchdb                     "tini -- /docker-e..."   6 seconds ago       Up 4 seconds        4369/tcp, 5984/tcp, 9100/tcp                  openemr_couchdb_1
  83 ed8a7e048e01        mariadb:10.3                "docker-entrypoint..."   6 seconds ago       Up 4 seconds        3306/tcp                                      openemr_mariadb-dev_1
  84 c7d035e86ce3        openemr/openemr:flex-edge   "./run_openemr.sh"       6 seconds ago       Up 4 seconds        0.0.0.0:8081->80/tcp, 0.0.0.0:8091->443/tcp   openemr_openemr-7-2_1
  85 24b71e4526ae        mysql:5.7                   "docker-entrypoint..."   6 seconds ago       Up 5 seconds        3306/tcp                                      openemr_mysql_1
  86 dee6b2216f6d        phpmyadmin/phpmyadmin       "/run.sh phpmyadmin"     6 seconds ago       Up 4 seconds        0.0.0.0:8102->80/tcp                          openemr_phpmyadmin-mariadb-dev_1
  87 5d9a8fcf8a3b        mysql:8                     "docker-entrypoint..."   6 seconds ago       Up 5 seconds        3306/tcp                                      openemr_mysql-dev_1
  88 4ed037f35c86        phpmyadmin/phpmyadmin       "/run.sh phpmyadmin"     6 seconds ago       Up 4 seconds        0.0.0.0:8101->80/tcp                          openemr_phpmyadmin-mysql_1
  89 7ef17b801312        phpmyadmin/phpmyadmin       "/run.sh phpmyadmin"     6 seconds ago       Up 5 seconds        0.0.0.0:8103->80/tcp                          openemr_phpmyadmin-mysql-dev_1
  90 27eaca4ced97        phpmyadmin/phpmyadmin       "/run.sh phpmyadmin"     6 seconds ago       Up 5 seconds        0.0.0.0:8100->80/tcp                          openemr_phpmyadmin-mariadb_1
  91 e1591a57cfd4        mariadb:10.2                "docker-entrypoint..."   6 seconds ago       Up 5 seconds        3306/tcp                                      openemr_mariadb_1
  92 ```
  93  - Note the `NAMES` column is extremely important and how you run docker commands
  94 on specific containers. For example, to go into a shell script in the
  95 `openemr_openemr-7-1_1` container, would use:
  96 ```bash
  97 docker exec -it openemr_openemr-7-1_1 bash
  98 ```
  99
 100 ### Bash Access
 101
 102 ```
 103 $ docker exec -it <container_NAME> bash
 104 ```
 105
 106 ### MySQL Client Access
 107
 108 If you are interested in using the MySQL client line as opposed to a GUI program, execute the following (password is passed in/is simple because this is for local development purposes):
 109
 110 ```
 111 $ docker exec -it <container_NAME> mysql -u root --password=root openemr
 112 ```
 113
 114 ### Apache Error Log Tail
 115
 116 ```
 117 $ docker exec -it <container_NAME> tail -f /var/log/apache2/error.log
 118 ```
 119 ...if you want the `access.log`, you can use this approach as well.
 120
 121 ### Recommended Development Setup
 122
 123 While there is no officially recommended toolset for programming OpenEMR,
 124 many in the community have found
 125 [PhpStorm](https://www.jetbrains.com/phpstorm/),
 126 [Sublime Text](https://www.sublimetext.com/),
 127 and [Vim](http://www.vim.org/) to be useful for coding. For database work,
 128 [MySQL Workbench](https://dev.mysql.com/downloads/workbench/) offers a smooth experience.
 129
 130 Many helpful tips and development "rules of thumb" can be found by reviewing
 131 [OpenEMR Development](http://open-emr.org/wiki/index.php/OpenEMR_Wiki_Home_Page#Development).
 132 Remember that learning to code against a very large and complex system is not a
 133 task that will be completed over night. Feel free to post on
 134 [the development forums](https://community.open-emr.org/c/openemr-development)
 135 if you have any questions after reviewing the wiki.
 136
 137 ### Ports
 138
 139 - HTTP is running on port 80 in the OpenEMR containers and port 8080 on the
 140 PHP 7.1 host machine and port 8081 on the PHP 7.2 host machine.
 141 - HTTPS is running on port 443 in the OpenEMR containers and port 8090 on the
 142 PHP 7.1 host machine and port 8091 on the PHP 7.2 host machine.
 143 - HTTP is running on port 80 in the PhpMyADMIN containers and port 8100 on the
 144 MariaDB GUI host machine and port 8101 on the MySQL GUI host machine and port
 145 8102 on the MariaDB-dev GUI host machine and port 8103 on the MySQL-dev GUI
 146 host machine.
 147 - MySQL is running on port 3306 in the MariaDB/MySQL/MariaDB-dev/MySQL-dev containers.
 148
 149 All host machine ports can be changed by editing the `docker-compose.yml` file.
 150 Host ports differ from the internal container ports by default to avoid conflicts
 151 services potentially running on the host machine (a web server such as Nginx,
 152 Tomcat, or Apache2 could be installed on the host machine that makes use of
 153 port 80, for instance).
 154
 155 ### Additional Build Tools
 156
 157 Programmers looking to use OpenEMR's [Bower](http://www.open-emr.org/wiki/index.php/Bower)
 158 and [Composer](http://www.open-emr.org/wiki/index.php/Composer) build tools can
 159 simply `bash` into the OpenEMR container and use them as expected.
 160
 161 ### Reset Workspace
 162
 163 There are frequently times where you will want to remove the dockers and start anew.
 164 For example, when you change github branches and start testing/developing on a
 165 different github branch. This is done by first running a command or script
 166 to delete and replace the synchronized directory (ie. remove the /var/www/openemr
 167 directory) and then restart the development docker:
 168 ```bash
 169 docker-compose down -v
 170 docker-compose up -d
 171 ```
 172 ### Work in progress
 173
 174 This is an ongoing work in progress and feel free to join the super exciting
 175 OpenEMR container projects. Feel free to post PR's to update the
 176 docker-compose.yml script or this documentation. Also feel free to post
 177 updates on the openemr/openemr:flex or openemr/openemr:flex-edge dockers
 178 which can be found at
 179 https://github.com/openemr/openemr-devops/tree/master/docker/openemr