| blob | 707a3a04c4853b9f03201c728f0fc2918a3300a9 |
1 # OpenEMR Local Development Docker
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!
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)._
11 ## Setup
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.
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)
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 Apache and PHP 7.1)
48 - http://localhost:8081 (with Apache and PHP 7.2)
49 - http://localhost:8085 (with Nginx and PHP-FPM 7.1)
50 - http://localhost:8086 (with Nginx and PHP-FPM 7.2)
51 - https://localhost:8090 with SSL (with Apache and PHP 7.1)
52 - https://localhost:8091 with SSL (with Apache and PHP 7.2)
53 - https://localhost:8095 with SSL (with Nginx and PHP-FPM 7.1) EXPERIMENTAL (not working yet)
54 - https://localhost:8096 with SSL (with Nginx and PHP-FPM 7.2) EXPERIMENTAL (not working yet)
56 **Step 4.** Setup up OpenEMR. The first time you run OpenEMR (and whenever you clear and replace your
57 synchronized openemr directory and restart the development docker). On the main
58 setup input screen:
59 - for `Server Host`, use either `mariadb` or `mysql` or `mariadb-dev` or `mysql-dev` or
60 `mariadb-old` or `mariadb-very-old` or `mariadb-very-very-old` or `mysql-old` or
61 `mysql-very-old` (you have all mariadb/mysql/mariadb-\*/mysql-\* dockers ready to go to make
62 testing either one easy; `mysql` is version 5.7 and `mysql-dev` is version 8; `mysql-old` is
63 version 5.6; `mysql-very-old` is version 5.5;`mariadb` is version 10.2 and `mariadb-dev` is
64 version 10.3; `mariadb-old` is version 10.1; `mariadb-very-old` is version 10.0;
65 `mariadb-very-very-old` is version 5.5)
66 - for `Root Pass`, use `root`
67 - for `User Hostname`, use `%`
69 ## Stop/Clean Out Dockers
70 There are frequently times where you will want to remove the dockers and start anew.
71 For example, when you change github branches and start testing/developing on a
72 different github branch. This is done by first running a command or script
73 to delete and replace the synchronized directory (ie. remove the /var/www/openemr
74 directory) and then restart the development docker:
75 ```bash
76 docker-compose down -v
77 docker-compose up -d
78 ```
80 ## Usage
82 ### Examine Containers
84 Run `$ docker ps` to see the OpenEMR and MySQL containers in the following format:
86 ```
87 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
88 499e2eec541d nginx "nginx -g 'daemon ..." 7 seconds ago Up 2 seconds 0.0.0.0:8085->80/tcp, 0.0.0.0:8086->81/tcp, 0.0.0.0:8095->443/tcp, 0.0.0.0:8096->444/tcp openemr_nginx_1
89 e05d57ecb0c4 mysql:8 "docker-entrypoint..." 7 seconds ago Up 4 seconds 3306/tcp openemr_mysql-dev_1
90 e4f0af5a2370 openemr/openemr:flex "./run_openemr.sh" 7 seconds ago Up 3 seconds 0.0.0.0:8080->80/tcp, 0.0.0.0:8090->443/tcp openemr_openemr-7-1_1
91 f626b616b23b mysql:5.6 "docker-entrypoint..." 7 seconds ago Up 4 seconds 3306/tcp openemr_mysql-old_1
92 3cc17e18ff1f mariadb:5.5 "docker-entrypoint..." 7 seconds ago Up 5 seconds 3306/tcp openemr_mariadb-very-very-old_1
93 f3d5ac8197b8 openemr/openemr:flex-edge "./run_openemr.sh" 7 seconds ago Up 3 seconds 0.0.0.0:8081->80/tcp, 0.0.0.0:8091->443/tcp openemr_openemr-7-2_1
94 9cc408ba7e90 mysql:5.5 "docker-entrypoint..." 7 seconds ago Up 4 seconds 3306/tcp openemr_mysql-very-old_1
95 053ae93971da mariadb:10.0 "docker-entrypoint..." 7 seconds ago Up 5 seconds 3306/tcp openemr_mariadb-very-old_1
96 9b3763c3e924 jodogne/orthanc-plugins "Orthanc /etc/orth..." 7 seconds ago Up 5 seconds 0.0.0.0:4242->4242/tcp, 0.0.0.0:8042->8042/tcp openemr_orthanc_1
97 cf21aa63d1d3 openemr/dev-php-fpm:7.2 "docker-php-entryp..." 7 seconds ago Up 5 seconds 9000/tcp openemr_dev-php-fpm-7-2_1
98 60f8da03ef4e mysql:5.7 "docker-entrypoint..." 7 seconds ago Up 5 seconds 3306/tcp openemr_mysql_1
99 f2dbad939dff mariadb:10.1 "docker-entrypoint..." 7 seconds ago Up 5 seconds 3306/tcp openemr_mariadb-old_1
100 d6495a3c29d7 openemr/dev-php-fpm:7.1 "docker-php-entryp..." 7 seconds ago Up 4 seconds 9000/tcp openemr_dev-php-fpm-7-1_1
101 dc55be0ac0d5 phpmyadmin/phpmyadmin "/run.sh phpmyadmin" 7 seconds ago Up 6 seconds 0.0.0.0:8100->80/tcp openemr_phpmyadmin_1
102 be4ca5eee6fd couchdb "tini -- /docker-e..." 7 seconds ago Up 6 seconds 0.0.0.0:5984->5984/tcp, 4369/tcp, 9100/tcp, 0.0.0.0:6984->6984/tcp openemr_couchdb_1
103 2f80ae27cd89 mariadb:10.2 "docker-entrypoint..." 7 seconds ago Up 5 seconds 3306/tcp openemr_mariadb_1
104 6aa06b9588f8 mariadb:10.3 "docker-entrypoint..." 7 seconds ago Up 6 seconds 3306/tcp openemr_mariadb-dev_1
105 ```
106 - Note the `NAMES` column is extremely important and how you run docker commands
107 on specific containers. For example, to go into a shell script in the
108 `openemr_openemr-7-1_1` container, would use:
109 ```bash
110 docker exec -it openemr_openemr-7-1_1 bash
111 ```
113 ### Bash Access
115 ```
116 $ docker exec -it <container_NAME> bash
117 ```
119 ### MySQL Client Access
120 GUI can be accessed via the phpMyAdmin at http://localhost:8100
122 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):
124 ```
125 $ docker exec -it <container_NAME> mysql -u root --password=root openemr
126 ```
128 ### Apache Error Log Tail
130 ```
131 $ docker exec -it <container_NAME> tail -f /var/log/apache2/error.log
132 ```
133 ...if you want the `access.log`, you can use this approach as well.
135 ### Recommended Development Setup
137 While there is no officially recommended toolset for programming OpenEMR,
138 many in the community have found
139 [PhpStorm](https://www.jetbrains.com/phpstorm/),
140 [Sublime Text](https://www.sublimetext.com/),
141 and [Vim](http://www.vim.org/) to be useful for coding. For database work,
142 [MySQL Workbench](https://dev.mysql.com/downloads/workbench/) or PhpMyAdmin
143 offers a smooth experience.
145 Many helpful tips and development "rules of thumb" can be found by reviewing
146 [OpenEMR Development](http://open-emr.org/wiki/index.php/OpenEMR_Wiki_Home_Page#Development).
147 Remember that learning to code against a very large and complex system is not a
148 task that will be completed over night. Feel free to post on
149 [the development forums](https://community.open-emr.org/c/openemr-development)
150 if you have any questions after reviewing the wiki.
152 ### Ports
154 - HTTP is running on port 80 in the OpenEMR containers and port 8080 on the
155 Apache PHP 7.1 host machine and port 8081 on the Apache PHP 7.2 host machine
156 and port 8085 on the Nginx PHP 7.1 host machine and port 8086 on the Nginx
157 PHP 7.2 host machine.
158 - HTTPS is running on port 443 in the OpenEMR containers and port 8090 on the
159 Apache PHP 7.1 host machine and port 8091 on the Apache PHP 7.2 host machine
160 and port 8095 on the Nginx PHP 7.1 host machine and port 8096 on the Nginx PHP
161 7.2 host machine.
162 - HTTP is running on port 80 in the PhpMyADMIN container and port 8100 on the
163 host machine.
164 - MySQL is running on port 3306 in the MariaDB/MySQL/MariaDB-\*/MySQL-\* containers.
166 All host machine ports can be changed by editing the `docker-compose.yml` file.
167 Host ports differ from the internal container ports by default to avoid conflicts
168 services potentially running on the host machine (a web server such as Nginx,
169 Tomcat, or Apache2 could be installed on the host machine that makes use of
170 port 80, for instance).
172 ### Additional Build Tools
174 Programmers looking to use OpenEMR's [Bower](http://www.open-emr.org/wiki/index.php/Bower)
175 and [Composer](http://www.open-emr.org/wiki/index.php/Composer) build tools can
176 simply `bash` into the OpenEMR container and use them as expected.
178 ### CouchDB
179 In OpenEMR, CouchDB is an option for the patients document storage. For this reason, a CouchDB
180 docker is included in this OpenEMR docker development environment. You can visit the CouchDB
181 GUI directly via http://localhost:5984/_utils/ with username `admin` and password `password`.
182 You can configure OpenEMR to use this CouchDB docker for patient document storage in OpenEMR
183 at Administration->Globals->Documents:
184 - Document Storage Method->CouchDB
185 - CouchDB HostName->admin
186 - CouchDB Password->password
187 - CouchDB Database can be set to any name you want
189 ## Ongoing Development
191 ### Orthanc
192 Developers are currently working on integrating the Orthanc PACS server into OpenEMR. This
193 feature is currently under development. Although it is not yet integrated with OpenEMR yet,
194 you can connect to the Orthanc application gui via http://localhost:8042/ with username `orthanc`
195 and password `orthanc`.
197 ## The Docker Development Environment is a work in progress
199 This is an ongoing work in progress and feel free to join the super exciting
200 OpenEMR container projects. Feel free to post PR's to update the
201 docker-compose.yml script or this documentation. Also feel free to post
202 updates on the openemr/openemr:flex or openemr/openemr:flex-edge dockers
203 which can be found at
204 https://github.com/openemr/openemr-devops/tree/master/docker/openemr