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