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