Important note: This is an evolving software prototype that has been extensively tested and is now being used in a live environment. Nevertheless, if you choose to run this software in a live production environment yourself, be prepared to continuously monitor for and deal with encountered issues.
Specifically, the security, scalability, cross-browser compatibility, user interface responsiveness, performance, data consistency assurance, safe multi-user concurrency, proper versioning, and platform independence may need additional attention.
O R D E R is a web-based software platform for development of clinical, administrative, research, and educational multi-user applications.
It includes several functional applications tied by LDAP/AD-capable single sign-on:
-
Employee Directory
-
Vacation Request Approval / Vacation Day Carryover Approval / Away Calendar System
-
Call Log Book for resident physicians on call
-
Fellowship Application and Recommendation Letter Submission / Candidate Interview Evaluation System
-
Residency Application (ERAS) and Candidate Interview Evaluation System
-
Translational Research Project Approval, Work Order Processing, and Invoicing system
-
Dashboards System for displaying categorized chart groups to authorized users
-
Critical Result Notification and Acknowledgement Tracking
-
De-identifier / Honest Broker System for Accession Numbers
-
Glass Slide Scan Ordering System
The core data models of the key objects are provided in UML and JPG formats, although additional attributes not shown on these diagrams may have been added since their creation.
If you discover a specific issue, post it here.
If you would like to contribute documentation using the Markdown format, please feel free to do so.
The source files are available at github.com/victorbrodsky/order-lab.
- Victor Brodsky (@victorbrodsky)
- Oleg Ivanov (@cinava)
- Acknowledgments
Installation instructions for deploying a Linux-based server using a local Linux client (tested on a local Ubuntu OS)
Warning: This software was initially developed and tested in a Windows-based environment to accommodate existing servers. It is now running on Red Hat (CentOS) Linux. To ease further development and testing, the Packer-based deployment script for a Digital Ocean virtual machine (VM) is provided. Additional testing may be necessary to discover and address unresolved issues associated with cross-platform compatibility (for example, with specific Linux distributions or Windows versions). The installation instructions assume the use of a Linux platform on your local machine (such as Ubuntu). If you are using a different operating system such as Windows or OSX, you may need to first create a local Ubuntu virtual machine with VirtualBox or another tool. The specific commercial server hosting provider was chosen as an example for convenience.
-
Sign up for Digital Ocean and obtain an API access key token. It should look similar to this one: e4561f1b44faa16c2b43e94c5685e5960e852326b921883765b3b0e11111f705
-
Download and uncompress or clone the source code from github.com/victorbrodsky/order-lab to a folder of your choice by running the following commands in the Terminal / shell:
sudo apt install -y git git clone https://github.com/victorbrodsky/order-lab.git
-
Install Packer and doctl by following the recommended installation instructions or by using snap:
snap install packer snap install doctl
Make sure to add both to your PATH. Alternatively, you can check for the latest versions of each Packer and doctl, substitute the versions into the commands below instead of the now current 1.6.5 and 1.54.0 (as of 12/15/2020), and run them:
wget -P ~/Downloads https://releases.hashicorp.com/packer/1.6.5/packer_1.6.5_linux_amd64.zip sudo mkdir /usr/local/packer sudo unzip ~/Downloads/packer_1.6.5_linux_amd64.zip -d /usr/local/packer wget -P ~/Downloads https://github.com/digitalocean/doctl/releases/download/v1.54.0/doctl-1.54.0-linux-amd64.tar.gz sudo mkdir /usr/local/doctl sudo tar xf ~/Downloads/doctl-1.54.0-linux-amd64.tar.gz -C /usr/local/doctl echo "export PATH=\"\$PATH:/usr/local/packer:/usr/local/doctl\"" >> ~/.bashrc source ~/.bashrc
-
Optionally edit order-lab/packer/parameters.yml in this project's folder to set desired values (especially for passwords). Make sure to disable sleep mode in your local Linux operating system to allow the script in the next step to complete successfully (it takes a while to run as it communicates with the remote servers). If you used "git clone" command to download the source code, use the following command in the terminal:
cd order-lab/packer
to get into the /packer folder or if you downloaded the source code and unzipped the zip file, use:
cd order-lab-master/packer
-
Decide whether you want to (a) use no domain name and no https/SSL, accessing the server via its IP, (b) use your domain name and https/SSL certificate, or (c) use your domain name and no https/SSL certificate, and follow the instructions in the corresponding step (a), (b), or (c) below:
(a) Run /packer/deploy-order-digital-ocean.sh via one of the following commands (make sure to substitute your API token, database user name, and the database password. If "dbusername" and "dbpassword" are not provided, the default "symfony"/"symfony" values are used.):
CentOS (--os is set to CentOS on the server by default): bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword Ubuntu: bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --os ubuntu
(b) First, obtain a domain name from a registrar (for example from Google Domains) if you don't have one already and follow these instructions to add the nameservers of your Digital Ocean webhost. It may take up to 48 hours for the domain name to start working. Next, get an SSL certificate from a Certificate Authority such as Let's Encrypt or Comodo using the Certificate Signing Request (CSR). You can also generate a local certificate for testing purposes. Copy the SSL Certificate file (www.example.com.crt) and SSL Private Key file (www.example.com.key) to the /packer folder. The SSL Private Key file (www.example.com.key) is the one that was initially generated when preparing the Certificate Signing Request (CSR), likely via a command similar to this one:
openssl genrsa -out www.example.com.key 2048
which was then followed by:
openssl req -new -sha256 -key www.example.com.key -out www.example.com.csr
to generate the second Certificate Signing Request (CSR) file, later used to obtain the third SSL certificate file (www.example.com.crt) from your Certificate Authority. Once both the www.example.com.crt and the www.example.com.key files are in the /packer folder, run one of the following commands in the terminal (make sure to first substitute your API token (from step 1 above), database user name (such as "dbusername"), the database password (such as "dbpassword"), your domain name (such as "example.com"), and the SSL certificate and private key file names below.):
CentOS (--os is set to CentOS on the server by default): bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol https --domainname example.com --sslcertificate www.example.com.crt --sslprivatekey www.example.com.key Ubuntu: bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol https --domainname example.com --sslcertificate www.example.com.crt --sslprivatekey www.example.com.key --os ubuntu
(c) Obtain a domain name from a registrar (for example from Google Domains) if you don't have one already and follow these instructions to add the nameservers of your Digital Ocean webhost. It may take up to 48 hours for the domain name to start working. Run one of the following commands in the terminal (first make sure to substitute your API token, database user name, the database password, and your domain name (such as "example.com") instead of "example.com" below. If "dbusername" and "dbpassword" are not provided, the default "symfony"/"symfony" values are used.):
CentOS (--os is set to CentOS on the server by default): bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol http --domainname example.com Ubuntu: bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol http --domainname example.com --os ubuntu
Note: If you get your SSL certificate from Let's Encrypt, make sure to follow their recommendation to ensure the certificate gets updated in a timely fashion and to avoid expiration. certbot and a symfony bundle are available. In the past, uncommenting (removing "#" from the beginning of) the line 289 in /order-lab/orderflex/app/config/security.yml file was necessary to enable SSL, but everything should be done automatically now. The "Connection Channel" variable on the Site Settings web page being set to either “https” or "http" after installation controls whether SSL (https://) is used or not.
For reference, this is the full list of parameters for the server installation script deploy-order-digital-ocean.sh:
--token: API-TOKEN-FROM-STEP-1 (must be provided)
--os: centos or ubuntu server operating system (default is centos)
--parameters: parameters.yml file name (default parameters.yml)
--dbuser: optional (default is symfony)
--dbpass: optional (default is symfony)
--protocol: optional (default is http)
--domainname: domain name (optional)
--sslcertificate: ssl certificate file (optional)
--sslprivatekey: ssl private key file (optional)
-
If the browser window with this URL does not open automatically at the end of the previous step, visit http://IPADDRESS/order/directory/admin/first-time-login-generation-init/ (or either http://example.com/order/directory/admin/first-time-login-generation-init/ or https://example.com/order/directory/admin/first-time-login-generation-init/ depending on whether you used the domain name and the ssl certificate in the command above) to generate the initial Administrator account, where IPADDRESS is the IP address of the server. Wait until the site redirects to the log in screen (it might take some time.)
-
Log into the application with the user name "Administrator" and the password "1234567890" at http://IPADDRESS/order/directory/ (make sure to select "Local User" above the user name field first). You should see the http://IPADDRESS/order/directory/settings/initial-configuration page asking you to supply the initial variables for your instance. If you choose to use Gmail's SMTP server to enable the site to send email notifications, make sure to enable 2-step-verification, generate an 'app password', and disable 2-step-verification to get the "app password" and enter it on the Site Settings page. You can test your email settings later by visiting http://IPADDRESS/order/directory/send-a-test-email/ and sending a test email message. Upon submission of this initial configuration form, visit http://IPADDRESS/order/directory/admin/update-system-cache-assets/ to enable the site footer to reflect the values you supplied. Make sure to change the default password for the Administrator account either on this initial configuration page or by visiting the account's profile page http://IPADDRESS/order/directory/user/2 and clicking 'Edit'. Set the server's "Environment" variable's value to "live", "dev" or "test" in Admin->Site Settings->Platform Settings http://IPADDRESS/order/directory/settings/.
-
Populate the database tables with default values by logging into the Employee Directory site (http://IPADDRESS/order/directory/) as the Administrator, selecting "Admin" > 'Site Settings' in the top navigation bar, and arriving at (http://IPADDRESS/order/directory/settings/). Near the bottom of the page under the 'Miscellaneous' heading, in the "Main Lists" section, click each link in the order listed, and confirm the action in each resulting window, then wait for each function to finish:
- Populate Country and City Lists (http://IPADDRESS/order/directory/admin/populate-country-city-list-with-default-values)
- Populate All Lists With Default Values (Part A) (http://IPADDRESS/order/directory/admin/populate-all-lists-with-default-values)
- Populate All Lists With Default Values (Part B) (http://IPADDRESS/order/scan/admin/populate-all-lists-with-default-values)
- c) Import Antibodies for the Postgres database (http://IPADDRESS/order/translational-research/generate-antibody-list/ihc_antibody_postgresql.sql)
- Pre-generate form node tree fields for Call Log Book (http://IPADDRESS/order/directory/admin/list/generate-form-node-tree/)
- Pre-generate form node tree fields for Dermatopathology Critical Result Notification (https://IPADDRESS/directory/admin/list/generate-dermatopathology-form-node-tree/)
- Pre-generate a new Fellowship Type if it does not exist (https://IPADDRESS/fellowship-applications/create-default-fellowship-type)
- Pre-generate a new Business/Vacation group if it does not exist (https://IPADDRESS/vacation-request/generate-default-group)
- Pre-generate cron jobs (Email, Fellowship Import, Unpaid Invoices) (https://IPADDRESS/directory/admin/list/generate-cron-jobs/)
- Pre-generate status cron job (check for Maintenance) (https://IPADDRESS/directory/admin/list/generate-cron-jobs/status)
- Pre-initialize dashboard charts (assign roles, topics, types) (https://IPADDRESS/directory/admin/list/init-dashboard-charts)
-
Select the sites you would like to be accessible on the homepage besides the "Employee Directory" by visiting https://IPADDRESS/order/directory/admin/list-manager/id/2 , clicking the "Action" button to the right of the desired site name, and clicking "Edit", then putting a checkmark in the "Show Link On Home Page" and "Show Link in Navbar" fields, and clicking the "Update" button.
-
To enable submission of applications for the Fellowship application site via Google services, use the files in the /order-lab/orderflex/src/Oleg/FellAppBundle/Util/GoogleForm folder with the Google Apps Script. Make sure to add your Google Apps Script API key on the Site Settings page http://IPADDRESS/order/directory/settings/.
-
If bulk import of the initial set of users is desired, download the ImportUsersTemplate.xlsx file from the /importLists folder, fill it out with the user details, and upload it back to the site via the the Navigation bar's "Admin > Import Users" (http://IPADDRESS/order/directory/import-users/spreadsheet) function on the Employee Directory site.
-
In order to later update to the latest version, connect to your server via:
ssh root@YOUR-IP-OR-DOMAIN-NAME
(you may be asked to change your password if connecting for the first time), then run:
cd /usr/local/bin/order-lab git pull cd orderflex bash deploy_prod.sh
Note: If you choose to use MySQL database on Linux instead of the default Postgres, you will need to increase the size of the sort buffer by setting "sort_buffer_size" to 512K in /etc/mysql/my.cnf.
Installation instructions for deploying a Linux-based server using a local MacOS X client (tested on a local MacOS X)
MacOS X instructions were tested on version 10.12.3 'Sierra'.
-
Sign up for Digital Ocean and obtain an API access key token. It should look similar to this one: e4561f1b44faa16c2b43e94c5685e5960e852326b921883765b3b0e11111f705
-
Choose a folder that will be used for installation of ORDER. This folder will be referred to as '/ORDER_LOCATION/' in these instructions, which you will need to replace with the actual file path of the location you select.
a) Download order-lab source code by clicking the "Clone or Download" button, followed by "Download as Zip". Double click the "order-lab-master" zip file, extract the contents, then move the folder to '/ORDER_LOCATION/'. Alternatively, if it is not installed already, install Git by either installing Xcode or by entering 'git' in the Terminal application's window and following the instructions to install the "command line developer tools". After Git is installed, change the directory to your chosen '/ORDER_LOCATION/' and run the git clone command in the Terminal window:
cd /ORDER_LOCATION/ git clone https://github.com/victorbrodsky/order-lab.git
-
'Homebrew' can be used to install the necessary software: Packer and doctl. This can be performed through the Terminal application. To install Homebrew, open Terminal and enter the following command followed by the return key. It will take several minutes to install.
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-
Install Packer and Doctl with the following Homebrew commands in the Terminal, entered one at a time:
brew install packer brew install doctl
-
Optionally edit /ORDER_LOCATION/order-lab-master/packer/parameters.yml (or /ORDER_LOCATION/order-lab/packer/parameters.yml if you used git clone command to download the source code) in this project's folder to set desired values (especially for passwords) using a text editor such as TextEdit and save. Make sure to disable sleep mode in your local OSX operating system (using a tool like Amphetamine or using your preferred method) to allow the script in the next step to complete successfully (it takes a while to run as it communicates with the remote servers). If you used "git clone" command to download the source code, use:
cd order-lab/packer
to get into the /packer folder or if you downloaded the source code and unzipped the zip file, use:
cd order-lab-master/packer
-
Decide whether you want to (a) use no domain name and no https/SSL, accessing the server via its IP (b) use your domain name and https/SSL certificate, or (c) use your domain name and no https/SSL certificate, and follow the instructions in the corresponding step (a), (b), or (c) below:
(a) Run /packer/deploy-order-digital-ocean.sh via one of the following commands (make sure to substitute your API token, database user name, and the database password. If "dbusername" and "dbpassword" are not provided, the default "symfony"/"symfony" values are used.):
CentOS (--os is set to CentOS on the server by default): bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword Ubuntu: bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --os ubuntu
(b) Obtain a domain name from a registrar (for example from Google Domains) if you don't have one already and follow these instructions to add the nameservers of your Digital Ocean webhost. It may take up to 48 hours for the domain name to start working. Get an SSL certificate from a Certificate Authority such as Let's Encrypt or Comodo using the Certificate Signing Request (CSR). You can also generate a local certificate for testing purposes. Copy the SSL Certificate file (www.example.com.crt) and SSL Private Key file (www.example.com.key) to the /packer folder. The SSL Private Key file (www.example.com.key) is the one that was generated when preparing the Certificate Signing Request (CSR), likely via a command similar to this one:
openssl genrsa -out www.example.com.key 2048
which was then followed by:
openssl req -new -sha256 -key www.example.com.key -out www.example.com.csr
to generate the Certificate Signing Request (CSR)file, later used to obtain the SSL certificate file (www.example.com.crt) from your Certificate Authority. Once both the www.example.com.crt and the www.example.com.key files are in the /packer folder, run one of the following commands in the terminal (make sure to substitute your API token (from step 1 above), database user name (such as "symfony"), the database password (such as "symfony"), your domain name (such as "example.com"), and the SSL certificate and private key file names below.):
CentOS (--os is set to CentOS on the server by default): bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol https --domainname example.com --sslcertificate www.example.com.crt --sslprivatekey www.example.com.key Ubuntu: bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol https --domainname example.com --sslcertificate www.example.com.crt --sslprivatekey www.example.com.key --os ubuntu
(c) Obtain a domain name from a registrar (for example from Google Domains) if you don't have one already and follow these instructions to add the nameservers of your Digital Ocean webhost. It may take up to 48 hours for the domain name to start working. Run one of the following commands in the terminal (make sure to substitute your API token, database user name, the database password, and your domain name (such as "example.com") instead of "example.com" below. If "dbusername" and "dbpassword" are not provided, the default "symfony"/"symfony" values are used.):
CentOS (--os is set to CentOS on the server by default): bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol http --domainname example.com Ubuntu: bash deploy-order-digital-ocean.sh --token API-TOKEN-FROM-STEP-1 --parameters parameters.yml --dbuser dbusername --dbpass dbpassword --protocol http --domainname example.com --os ubuntu
Note: If you get your SSL certificate from Let's Encrypt, make sure to follow their recommendation to ensure the certificate gets updated in a timely fashion and to avoid expiration. certbot and a symfony bundle are available. In the past, uncommenting (removing "#" from the beginning of) the line 289 in /order-lab/orderflex/app/config/security.yml file was necessary to enable SSL, but everything should be done automatically now and is controlled via the "Connection Channel" variable in Site Settings being set to either “https” or "http".
For reference, this is the full list of parameters for the server installation script deploy-order-digital-ocean.sh:
--token: API-TOKEN-FROM-STEP-1 (must be provided)
--os: centos or ubuntu server operating system (default is centos)
--parameters: parameters.yml file name (default parameters.yml)
--dbuser: optional (default is symfony)
--dbpass: optional (default is symfony)
--protocol: optional (default is http)
--domainname: domain name (optional)
--sslcertificate: ssl certificate file (optional)
--sslprivatekey: ssl private key file (optional)
-
If the browser window with this URL does not open automatically at the end of the previous step, visit http://IPADDRESS/order/directory/admin/first-time-login-generation-init/ (or either http://example.com/order/directory/admin/first-time-login-generation-init/ or https://example.com/order/directory/admin/first-time-login-generation-init/ depending whether you used the domain name and the ssl certificate in the command above) to generate the initial Administrator account, where IPADDRESS is the IP address of the server. Wait until the site redirects to the log in screen (it might take a while.)
-
Select "Local User" above the user name field and log into the application with the user name "Administrator" and the password "1234567890" at http://IPADDRESS/order/directory/ (or http://example.com/order/directory/ or https://example.com/order/directory/ depending on whether you used your domain name and SSL certificates during set up). You should see the http://IPADDRESS/order/directory/settings/initial-configuration page asking you to supply the initial variables for your instance. If you choose to use Gmail's SMTP server to enable the site to send email notifications, make sure to enable 2-step-verification, generate an 'app password', and disable 2-step-verification to get the "app password" and enter it on the Site Settings page. You can test your email settings later by visiting http://IPADDRESS/order/directory/send-a-test-email/ and sending a test email message. Upon submission of this initial configuration form, visit http://IPADDRESS/order/directory/admin/update-system-cache-assets/ to enable the site footer to reflect the values you supplied. Make sure to change the default password for the Administrator account either on this initial configuration page or by visiting the account's profile page http://IPADDRESS/order/directory/user/2 and clicking 'Edit', then set the server's "Environment" variable's value to "live", "dev" or "test" in Admin->Site Settings->Platform Settings http://IPADDRESS/order/directory/settings/.
-
Populate the database tables with default values by logging into the Employee Directory site as the Administrator, selecting "Admin" > 'Site Settings' in the top navigation bar, and arriving at (http://IPADDRESS/order/directory/settings/). Near the bottom of the page under the 'Miscellaneous' heading, in the "Main Lists" section, click each link in the order listed, and confirm the action in each resulting window, then wait for each function to finish:
- Populate Country and City Lists (http://IPADDRESS/order/directory/admin/populate-country-city-list-with-default-values)
- Populate All Lists With Default Values (Part A) (http://IPADDRESS/order/directory/admin/populate-all-lists-with-default-values)
- Populate All Lists With Default Values (Part B) (http://IPADDRESS/order/scan/admin/populate-all-lists-with-default-values)
- c) Import Antibodies for the Postgres database (http://IPADDRESS/order/translational-research/generate-antibody-list/ihc_antibody_postgresql.sql)
- Pre-generate form node tree fields for Call Log Book (http://IPADDRESS/order/directory/admin/list/generate-form-node-tree/)
- Pre-generate form node tree fields for Dermatopathology Critical Result Notification (https://IPADDRESS/directory/admin/list/generate-dermatopathology-form-node-tree/)
- Pre-generate a new Fellowship Type if it does not exist (https://IPADDRESS/fellowship-applications/create-default-fellowship-type)
- Pre-generate a new Business/Vacation group if it does not exist (https://IPADDRESS/vacation-request/generate-default-group)
- Pre-generate cron jobs (Email, Fellowship Import, Unpaid Invoices) (https://IPADDRESS/directory/admin/list/generate-cron-jobs/)
- Pre-generate status cron job (check for Maintenance) (https://IPADDRESS/directory/admin/list/generate-cron-jobs/status)
- Pre-initialize dashboard charts (assign roles, topics, types) (https://IPADDRESS/directory/admin/list/init-dashboard-charts)
-
Select the sites you would like to be accessible on the homepage besides the "Employee Directory" by visiting https://IPADDRESS/order/directory/admin/list-manager/id/2 , clicking the "Action" button to the right of the desired site name, and clicking "Edit", then putting a checkmark in the "Show Link On Home Page" and "Show Link in Navbar" fields, followed by clicking the "Update" button.
-
To enable submission of applications for the Fellowship application site via Google services, use the files in the /order-lab/orderflex/src/Oleg/FellAppBundle/Util/GoogleForm folder with the Google Apps Script. Make sure to add your Google Apps Script API key on the Site Settings page http://IPADDRESS/order/directory/settings/. To use the Google SMTP Email Server to send email notifications, generate the Google API key on the Google site as follows: enable 2-step verification, generate Google App specific password, and disable 2-step verification, then enter the Google "App specific password" (API key) on the Site Settings page.
-
If bulk import of the initial set of users is desired, download the ImportUsersTemplate.xlsx file from the /importLists folder, fill it out with the user details, and upload it back via the the Navigation bar's "Admin > Import Users" (http://IPADDRESS/order/directory/import-users/spreadsheet) function on the Employee Directory site.
-
In order to later update to the latest version, connect to your server via:
ssh root@YOUR-IP-OR-DOMAIN-NAME
(you may be asked to change your password if connecting for the first time), then run:
cd /usr/local/bin/order-lab git pull cd orderflex bash deploy_prod.sh
Note: If you choose to use MySQL database on Linux instead of Postgres, you will need to increase the size of the sort buffer by setting "sort_buffer_size" to 512K in /etc/mysql/my.cnf.
For reference: installation instructions for deploying an older version for Symfony 3.4 and PHP 5.6 on Linux (Digital Ocean)
Symfony 3.4 with PHP 5.6:
- git clone --single-branch --branch sf3.4-php5.6-windows https://github.com/victorbrodsky/order-lab.git
- cd order-lab/packer
- bash deploy-order-digital-ocean.sh --token yourapitoken --os centos
For reference: installation instructions for deploying an older version for Symfony 4 and PHP 7.4 on Linux (Digital Ocean)
Symfony 4.4 with PHP 7.4:
- git clone --single-branch --branch sf4-php7 https://github.com/victorbrodsky/order-lab.git
- cd order-lab/packer
- bash deploy-order-digital-ocean.sh --token yourapitoken --os centos
Tested on Windows 10 and Windows 7
-
Choose a folder on the server that will be used for installation of ORDER. This folder will be referred to as "C:\ORDER_LOCATION" in these instructions, and you will need to replace its name with the actual file path of the location you select. Several files will need to be downloaded and installed.
a) Download the installer for git version control appropriate for your version of Windows. Run the installer with the standard installation options. (Tested with version 2.12.0.)
b) Install all of the Microsoft Visual C++ Redistributable Packages relevant to your Windows version.
For 64 bit Windows (x64) install both these 64 bit versions and the 32 bit versions below:
- VC9 2008 SP1 Package (x64)
- VC 2008 SP1 ATL Package (x64)
- VC 2008 SP1 MFC Package (x64)
- VC10 2010 SP1 Package (x64)
- VC11 2012 Update 4 (x64)
- VC13 2013 Update 5 (x64)
- VC16 2015-2019 (VC16 x64) 14.20.27508
For 32 bit Windows (x86):
- VC9 2008 SP1 Package (x86)
- VC 2008 SP1 ATL Package (x86)
- VC 2008 SP1 MFC Package (x86)
- VC10 2010 SP1 Package (x86)
- VC11 2012 Update 4 (x86)
- VC13 2013 Update 5 (x86)
- VC16 2015-2019 (VC16 x86) 14.20.27508
c) Install an Apache-PHP-MySQL stack of your choice (for example: AMPPS, WAMP, or XAMPP. PHP version 5.6.7 was initially tested with earlier versions, but PHP version 7.1 (and more recently 7.4) appears to work as well and avoids the "PHP Fatal error: Allowed memory size of X bytes exhausted..." after running "composer update" in the later installation steps. MSSQL Server and Postgres have been tested as well. The following instructions will assume AMPPS with PHP 5.6.7 were chosen.
d) Download the installer for AMPPS Apache-PHP-MySQL stack appropriate for your version of Windows. Run the installer with the standard installation options. After installation, open AMPPS, and when prompted to install "C++ Redistributable Visual Studio", select "Yes". (Tested with version 3.6.)
e) Download order-lab source code by clicking the "Clone or Download" button, followed by "Download as Zip". Right click the "order-lab-master" zip file and select "Extract All...". Select the folder you have chosen for installation ("C:\ORDER_LOCATION") as the destination for the extracted files. Alternatively, change the directory to your chosen 'ORDER_LOCATION' and run the git clone command in the Command Prompt window (although note that using git to clone the repository will place the code in a folder titled "order-lab" as opposed to un-zipping the downloaded zip file which places it into "order-lab-master" folder by default, so make sure to use the correct path to your source code copy in the later installation steps):
cd C:\ORDER_LOCATION git clone https://github.com/victorbrodsky/order-lab.git
-
Configure AMPPS. At this point, AMPPS should be open, and Apache web server, PHP, and MySQL should display as "Running". If Apache or MySQL is not running, turn it on by clicking the switch to the left of its name in the AMPPS tray menu.
a) Select PHP version 5.6.7. In AMPPS, select Options (an icon that appears as a grid of squares near the top of the AMPPS window) and select "Change PHP Version". Select "PHP 5.6.7". After restarting, Apache, PHP, and MySQL should return to the "Running" state. You can also select PHP version 7.1 to avoid the "PHP Fatal error: Allowed memory size of X bytes exhausted..." after running "composer update" in the later installation steps.
b) Configure the php.ini file. Click on the gear icon the right of "Php-!" in the AMPPS application window. Click the wrench icon ("Configuration") to the right of the gear icon. The php.ini file will open in a text editor. Find the line matching ";date.timezone = " and replace it with date.timezone = "UTC". Other timezone values are available here but "UTC" should work.
c) Enable the ldap extensions, international support, the GD library extension, and the file info extension by removing the semicolon at the beginning of the following lines in php.ini (if a semicolon is present), saving the php.ini file, and restarting the Apache web server:
;extension=php_ldap.dll ;extension=php_intl.dll ;extension=php_gd2.dll ;extension=php_fileinfo.dll
d) Set UTC as a default timezone: date.timezone="UTC"
e) Temporarily modify the value of the memory_limit in php.ini by editing the existing line or add the following line to the php.ini to enable the later "composer update" command in step 4c to complete successfully. You can comment this line out later by specifying "memory_limit = 2048M" and restarting the Apache web server.
memory_limit = -1
f) If an option other than AMPPS is being used, the following configuration step may be necessary. If AMPPS is being used, skip this step.
The pdo extension may need to be enabled. For PHP version 5.6 "php_pdo_sqlsrv_56_ts.dll" and "php_sqlsrv_56_ts.dll" files should be placed in PHP/ext folder, and the following lines added to php.ini:
extension=php_sqlsrv_56_ts.dll extension=php_pdo_sqlsrv_56_ts.dll
For the older PHP version 5.4 "php_pdo_sqlsrv_54_ts.dll" and "php_sqlsrv_54_ts.dll" should be placed in PHP/ext folder, and the following lines added to php.ini:
extension=php_sqlsrv_54_ts.dll extension=php_pdo_sqlsrv_54_ts.dll
If you are using MSSQL Server, you will need to download and install the Microsoft ODBC Driver 11 for SQL Server for PHP to access the database:
For 64 bit (x64) Operating Systems use the x64\msodbcsql.msi installation file For 32 bit (x86) Operating Systems use the x86\msodbcsql.msi installation file
You may need to download and enable OPcache if you are not using AMPPS (in which it is already enabled by default). Note: this step is required if OPcache is not running. PHP configuration can be verified on the http://IPADDRESS/order/order/info.php page after step 3.
For PHP version 5.4 download OPcache and enable it; for PHP version 5.6 just enable OPCache by adding this line to php.ini:
zend_extension="PATH-TO-WEB-SERVER\WebServer\PHP\Ext\php_opcache.dll"
g) Make sure that Apache can find and load icu*.dll files from the PHP base folder. One possible solution is to copy these files to Apache's "bin" folder:
* icudt49.dll * icuin49.dll * icuio49.dll * icule49.dll * iculx49.dll * icutu49.dll * icuuc49.dll
h) Set up an alias on the server directing Apache if the url contains some subdomain or prefix such as 'www.example.com/order'. In the AMPPS tray menu, click the globe icon at the top of the window to open http://localhost/AMPPS/ in the web browser (recent versions of Firefox or Chrome are preferred). From this AMPPS Home page, various server settings can be configured. Open "Alias Manager", click "Add New", enter "order" under "Alias Name" and "C:/ORDER_LOCATION/order-lab-master/orderflex/web" (or "C:/ORDER_LOCATION/order-lab/orderflex/web" if you cloned using git) under "Path" (using backslashes in the file path, rather than forward slashes). Click "Create Alias". Now create a second alias with the name "ORDER" and the same path.
If you are not using AMPPS, different Apache-PHP-MySQL stacks may require modifying the httpd.conf file directly by setting the alias to the order-lab www folder as follows:
If you unzipped the downloaded source code:
<VirtualHost *:80> DocumentRoot "C:\ORDER_LOCATION\order-lab-master\orderflex\web\" <Directory "C:\ORDER_LOCATION\order-lab-master\orderflex\web\" Options +FollowSymLinks -Includes AllowOverride All Require all granted </Directory> Alias /order "C:\ORDER_LOCATION\order-lab-master\orderflex\web\" Alias /ORDER "C:\ORDER_LOCATION\order-lab-master\orderflex\web\" RewriteRule ^/ORDER(.*)$ /order$1 [R=301] ErrorLog ${APACHE_LOG_DIR}/error.log CustomLog ${APACHE_LOG_DIR}/access.log combined </VirtualHost>
Or if you cloned the source code using the git clone command:
<VirtualHost *:80> DocumentRoot "C:\ORDER_LOCATION\order-lab-master\orderflex\web\" <Directory "C:\ORDER_LOCATION\order-lab\orderflex\web\" Options +FollowSymLinks -Includes AllowOverride All Require all granted </Directory> Alias /order "C:\ORDER_LOCATION\order-lab\orderflex\web\" Alias /ORDER "C:\ORDER_LOCATION\order-lab\orderflex\web\" RewriteRule ^/ORDER(.*)$ /order$1 [R=301] ErrorLog ${APACHE_LOG_DIR}/error.log CustomLog ${APACHE_LOG_DIR}/access.log combined </VirtualHost>
i) Restart the apache server and make sure Apache and PHP are running.
j) Create the database and the database user. On the AMPPS Home page, open "Add Database". Enter the name "ScanOrder" for the database. Click "Create". Open the "Databases" tab. Click "Check Privileges" to the right of the newly created "ScanOrder" database. Click "Add user". Enter "symfony2" as the "User Name". Change the "Host" to "Local". Enter "symfony2" (for example) as the password, and confirm the password. Ensure the option "Grant all privileges on database "Scanorder"" is checked. Check the box for "Global Privileges" "Check All". Click "Go" at the bottom of the page to create the database user.
-
Download Composer and install. Run the installer (tested with version 1.4.1). When prompted to "Choose the command-line PHP you want to use", browse to the file location "C:\Program Files (x86)\AMPPS\php\php.exe". For other options, choose the default configuration.
-
Update and configure Symfony:
a) AMPPS uses MySQL and not MSSQL, so this parameter must be changed: Open the file "C:\ORDER_LOCATION\order-lab-master\orderflex\app\config\parameters.yml" (or "C:\ORDER_LOCATION\order-lab\orderflex\app\config\parameters.yml" if you used the git clone command) in a text editor. Replace the line "database_driver: pdo_sqlsrv" (useful for MSSQL Server) with "database_driver: pdo_mysql" (to use MySQL server we are using for these instructions). Save and close the file.
b) Open a Windows Command Prompt. Change the directory to the orderflex folder by entering the command:
cd C:\ORDER_LOCATION\order-lab-master\orderflex\
or, if you used the git clone command, run:
cd C:\ORDER_LOCATION\order-lab\orderflex\
c) Update symfony vendors by entering the command:
composer self-update
When it is complete, enter the command:
composer update
The update will take several minutes. If you see the "PHP Fatal error: Allowed memory size of X bytes exhausted..." error, you may need to temporarily add the "memory_limit = -1" line to php.ini, restart Apache web server (or switch to PHP version 7.1) and try running "composer update" again. It should run until it reaches the point where it will prompt for missing parameters by displaying:
database_driver (pdo_sqlsrv): Some parameters are missing. Please provide them.
When prompted for the following values, type in the value to the right of the semicolon below and press the return key. When prompted for other values not listed below, leave them blank and press the return key. These values are located in Symfony's parameters file (app/config/parameters.yml) and set the defined Database configuration values (make sure to enter the "database_password: " that matches the one you chose in step 2i above):
database_host: 127.0.0.1 database_port: null database_name: ScanOrder database_user: symfony2 database_password: symfony2 mailer_transport: smtp mailer_host: 127.0.0.1 mailer_user: null mailer_password: null locale: en delivery_strategy: realtime
-
Deployment
a) Run the deployment script: Open a Windows File Explorer window and navigate to "C:\ORDER_LOCATION\order-lab-master\orderflex" (or to "C:\ORDER_LOCATION\order-lab\orderflex" if you used the git clone command). Right click on an empty space in the window, and select "Git Bash here". In the Git Bash window that opens, enter the command "bash ./deploy_prod.sh". The script will take several minutes to run. "Deploy complete." will appear when it is finished.
b) Create the Administrator account with password 1234567890 by opening the following URL in your browser (specify the server's IP or domain name instead of "localhost"):
http://localhost/order/directory/admin/first-time-login-generation-init/ Wait until the site re-directs to the log in screen (it might take a while.)
c) Log into the application with the user name "Administrator" and the password "1234567890" at http://IPADDRESS/order/directory/ (make sure to select "Local User" above the user name field first). You should see the http://IPADDRESS/order/directory/settings/initial-configuration page asking you to supply the initial variables for your instance. If you choose to use Gmail's SMTP server to enable the site to send email notifications, make sure to enable 2-step-verification, generate an 'app password', and disable 2-step-verification to get the "app password" and enter it on the Site Settings page. You can test your email settings later by visiting http://IPADDRESS/order/directory/send-a-test-email/ and sending a test email message. Upon submission of this initial configuration form, visit http://IPADDRESS/order/directory/admin/update-system-cache-assets/ to enable the site footer to reflect the values you supplied. Make sure to change the default password for the Administrator account either on this initial configuration page or by visiting the account's profile page http://IPADDRESS/order/directory/user/2 and clicking 'Edit', then set the server's "Environment" variable's value to "live", "dev" or "test" in Admin->Site Settings->Platform Settings http://IPADDRESS/order/directory/settings/.
d) Populate the database tables with default values by logging into the Employee Directory site as the Administrator, selecting "Admin" > 'Site Settings' in the top navigation bar, and arriving at (http://IPADDRESS/order/directory/settings/). Near the bottom of the page under 'Miscellaneous' heading, in the "Main Lists" section, click each link in the order listed, and confirm the action in each resulting window, then wait for each function to finish:
- Populate Country and City Lists (http://IPADDRESS/order/directory/admin/populate-country-city-list-with-default-values)
- Populate All Lists With Default Values (Part A) (http://IPADDRESS/order/directory/admin/populate-all-lists-with-default-values)
- Populate All Lists With Default Values (Part B) (http://IPADDRESS/order/scan/admin/populate-all-lists-with-default-values)
- c) Import Antibodies for the Postgres database (http://IPADDRESS/order/translational-research/generate-antibody-list/ihc_antibody_postgresql.sql)
- Pre-generate form node tree fields for Call Log Book (http://IPADDRESS/order/directory/admin/list/generate-form-node-tree/)
- Pre-generate form node tree fields for Dermatopathology Critical Result Notification (https://IPADDRESS/directory/admin/list/generate-dermatopathology-form-node-tree/)
- Pre-generate a new Fellowship Type if it does not exist (https://IPADDRESS/fellowship-applications/create-default-fellowship-type)
- Pre-generate a new Business/Vacation group if it does not exist (https://IPADDRESS/vacation-request/generate-default-group)
- Pre-generate cron jobs (Email, Fellowship Import, Unpaid Invoices) (https://IPADDRESS/directory/admin/list/generate-cron-jobs/)
- Pre-generate status cron job (check for Maintenance) (https://IPADDRESS/directory/admin/list/generate-cron-jobs/status)
- Pre-initialize dashboard charts (assign roles, topics, types) (https://IPADDRESS/directory/admin/list/init-dashboard-charts)
e) Run the deployment script again by following step 5a above:
bash deploy_prod.sh
-
Obtain and install these optional applications to enable associated functionality on the server (then ensure the path for each is correctly set on this page http://IPADDRESS/order/directory/settings/):
- wkhtmltopdf for html to pdf conversion (default path on Windows: C:\Program Files\wkhtmltopdf\ )
- LibreOffice for Word to PDF conversion (default path on Windows: C:\Program Files (x86)\LibreOffice 5\ )
- GhostScript for PDF decryption
- PDFtk Server for PDF merging
-
To enable HTTPS (SSL/TLS), first either purchase the certificate from your preferred vendor and add it to the server, or install either the ACMESharp, Certes, or WinACME with a Let's Encrypt certificate (you can also use a symfony bundle). For certificates from Let's Encrypt, verify that the scheduled task to automatically update them is set up since they expire in 90 days. Once that is done, follow these steps:
A) Copy the obtained certificate file (named your-certificate.cer) to path yourpath/conf/ssl.crt/ B) Copy the obtained private key file (named your-key.key) to path yourpath/conf/ssl.key/ C) In the config file httpd.conf enable “virtual host” by adding the following lines LoadModule ssl_module modules/mod_ssl.so <VirtualHost *:443> DocumentRoot "yourpath/htdocs/" ServerName yourservername:443 SSLEngine on SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL SSLCertificateFile "yourpath/conf/ssl.crt/your-certificate.cer" SSLCertificateKeyFile "yourpath/conf/ssl.key/your-key.key" </VirtualHost> D) Restart the web server (Apache) E) In Site Settings change the variable named "Connection Channel" to “https” F) Run deploy_prod.sh
-
Select the sites you would like to be accessible on the homepage besides the "Employee Directory" by visiting https://IPADDRESS/order/directory/admin/list-manager/id/2 , clicking the "Action" button to the right of the desired site name, and clicking "Edit", then putting a checkmark in the "Show Link On Home Page" and "Show Link in Navbar" fields, followed by clicking the "Update" button.
-
To enable submission of applications for the Fellowship application site via Google services, use the files in the /order-lab/orderflex/src/Oleg/FellAppBundle/Util/GoogleForm folder with the Google Apps Script. Make sure to add your Google Apps Script API key on the Site Settings page http://IPADDRESS/order/directory/settings/.
-
If bulk import of the initial set of users is desired, download the ImportUsersTemplate.xlsx file from the /importLists folder, fill it out with the user details, and upload it back via the the Navigation bar's "Admin > Import Users" (http://IPADDRESS/order/directory/import-users/spreadsheet) function on the Employee Directory site.
-
In order to later update to the latest version, connect to your server via:
ssh root@YOUR-IP-OR-DOMAIN-NAME
(you may be asked to change your password if connecting for the first time), then:
cd C:\ORDER_LOCATION\order-lab-master\ git pull cd orderflex bash deploy_prod.sh (via details in step 5 (a) above)
-
Install git (here use syntaxis Alma9 as an example):
sudo dnf update -y sudo dnf install git
-
Clone remote repository:
git clone https://github.com/victorbrodsky/order-lab.git /usr/local/bin/order-lab
-
Run installation script order_install.sh with 3 parameters: DB username, DB password, OS name (alma8, alma9, centos7, ubuntu22):
cd /usr/local/bin/order-lab/packer
bash order_install.sh symfony symfony alma9
-
Initializing ORDER by opening web browser: http://serverip/order/directory/admin/first-time-login-generation-init/
php bin/console assets:install
Note: For production mode, execute the following command to clean cache and fix assetic links to js and css:
(read: Dumping Asset Files in the dev environment http://symfony.com/doc/current/cookbook/assetic/asset_management.html):
php bin/console cache:clear --env=prod --no-debug or (php bin/console cache:clear --env=prod --no-debug --no-warmup)
php bin/console assetic:dump --env=prod --no-debug
After modification of html, js or css files, run this single console script to clear cache and dump assets in /orderflex folder:
deploy_prod.sh
Update composer:
composer.phar self-update
On dev server:
composer.phar update
On live server:
composer.phar install
-
Generate only getters/setters:
php bin/console doctrine:generate:entities Oleg/OrderformBundle/Entity/Slide
-
Generate CRUD:
php bin/console generate:doctrine:crud --entity=OlegOrderformBundle:Accession --format=annotation --with-write
-
Create database according to Entity
php bin/console doctrine:database:create
-
Create tables:
php bin/console doctrine:schema:update --force
-
Recreate DB:
php bin/console doctrine:database:drop --force php bin/console doctrine:database:create
-
create git repository from remote server (on Bitbucket for example):
git clone https://yourusername@bitbucket.org/weillcornellpathology/scanorder.git
-
create symfony2 project:
php "C:\Users\oli2002\Desktop\php\Composer\composer.phar" create-project symfony/framework-standard-edition orderflex
-
create bundle:
php bin/console generate:bundle --namespace=Acme/HelloBundle --format=yml
-
Run command:
git add .
-
Run command:
git commit -m "adding initial"
-
Run command:
git push -u origin master
-
repeat 3-5 for development
php ./bin/symfony_requirements
-
cd to folder created by clone
-
Run command:
git remote update
-
Run command:
git pull
If there are some local modified files, git will not allow a merge with local modifications. There are 3 options (option (b): git stash is enough):
a) Run command:
git commit -m "My message"
b) Run command:
git stash
c) Run command:
git reset --hard
To force Git to overwrite local files on pull; This will remove all the local files (http://stackoverflow.com/questions/1125968/force-git-to-overwrite-local-files-on-pull)
git fetch --all
git reset --hard origin/master
git push -u origin iss51
git fetch origin
git checkout --track origin/iss51
git remote update (note: this is the same as git fetch --all)
git pull
git add -u .
git commit -m "message"
git push -u origin master
To remove already cached files after changing .gitignore (First commit any outstanding code changes and then run this command):
git rm -r --cached .
git add .
git commit -m ".gitignore is now working"
http://stackoverflow.com/questions/2466735/how-to-checkout-only-one-file-from-git-repository
To download all the recent changes (without putting it in your current checked out code (working area)):
git fetch
git checkout origin/master -- path/to/file
git checkout abcde file/to/restore
git push --tags <remote>
git filter-branch --tree-filter 'rm -rf path/to/your/file' HEAD
git push
Run all tests (>70 tests, >210 assertions in ~9 minutes): ./bin/simple-phpunit
Run Employee directory test only: ./bin/simple-phpunit tests/Oleg/TestBundle/UserTest.php
Run Business/Vacation test only: ./bin/simple-phpunit tests/Oleg/TestBundle/VacationTest.php
Run Call Log test only: ./bin/simple-phpunit tests/Oleg/TestBundle/CalllogTest.php
Run TRP test only: ./bin/simple-phpunit tests/Oleg/TestBundle/TrpTest.php
Run Fellowship test only: ./bin/simple-phpunit tests/Oleg/TestBundle/FellappTest.php
To run test on the server without existing data use TESTENV=nodata in front of ./bin/simple-phpunit: TESTENV=nodata ./bin/simple-phpunit
-
The resulting log and screen shots are in order/test folder)
To redirect visiting users to a new server while keeping the same url path, on the old redirecting server add one of the following snippets to the "<VirtualHost *:80>" section of the Apache's httpd.conf file:
-
Example: c.med.cornell.edu/order/vacation-request to view.med.cornell.edu/vacation-request
RewriteEngine On RewriteCond %{REQUEST_URI} /order/ RewriteRule "^/order(.+)" "https://view.med.cornell.edu$1" [R,L] RewriteRule "^/order" "https://view.med.cornell.edu$1" [R,L] -
Example: c.med.cornell.edu/order/vacation-request to view.med.cornell.edu/order/vacation-request
RewriteEngine On RewriteCond %{REQUEST_URI} /order/ RewriteRule (.*) https://view.med.cornell.edu$1 [R=301,L]