Setting Up a New Open Clinical History Server
This guide describes thehow basicto server setup required fordeploy a new Open Clinical History installation.
Open Clinical History includes a temporary first-run setup assistant:
setup_delete_after_setup.php
The setup assistant is deliberately self-contained so that it can run before config.php exists and before the application database has been configured.
It guides the administrator through:
Server preflight
|
v
Private config.php
|
v
Database
|
v
Application settings
|
v
SNOMED CT
|
v
Image/SNOMED database
|
v
Queue workers
|
v
First patient
|
v
Delete setup installer
Important:
setup_delete_after_setup.phpmust be deleted from the web server after installation is complete.
Requirements
A new installation requires:
-
PHP 8.3 or later
-
MariaDB/PHP CLI
MariaDB or MySQL
aApache, Nginx or another suitable web server
cURL orsupport
PDO / PDO MySQL
mbstring
JSON support
proc_open()
a private configuration directory
a writable runtime directory
a private SNOMED CT storage directory
a writable runtime directory
access to the private Open Clinical History source repository
SSL/The existing installation design separates the private configuration, runtime and SNOMED files from the public application files.
HTTPS is strongly recommended and should be considered mandatory for anyan environmentinstallation containingthat will contain real clinicalpatient information.
Recommended Directory Structure
Keep sensitive configuration, runtimeSensitive files andshould SNOMEDremain CT source files outside the web-accessible application directory.directory.
AFor typical installation might use:example:
/var/www/
├── private/
│ └── demo/
│ ├── config.php
│ ├── config_template.php
│ ├── health_history.sql
│ ├── run/
│ └── snomed/
│
└── openclinicalhistory/
└── webapplication applicationfiles
For example:
root@server:/var/www/private/demo# ls
config.php
config_template.php
health_history.sql
run
snomed
The application web directory is public.
The following are not public:
config.php
database schema/backups
runtime state
SNOMED CT RF2 files
The /var/www/private directory shouldmust notnever be configured as anthe Apache or Nginx document root.
1. CreateObtain the PrivateOpen ApplicationClinical DirectoryHistory Source
CreateThe Open Clinical History source repository is currently private.
Repository:
https://github.com/bengoudieparkoch/openclinicalhistory
To request access, visit:
https://www.openclinicalhistory.org/access.php
and complete the access request form.
The existing deployment documentation also identifies repository access as an approved-user process rather than a privatepublic directorysource for:download.
After
accessdatabasehas configurationbeen granted, clone the repository into the web application directory.
SQL schema
runtime files
SNOMED CT RF2 releases
For example:
mkdircd /var/www
git clone https://github.com/bengoudieparkoch/openclinicalhistory.git
For later application updates:
cd /var/www/openclinicalhistory
git pull
Do not store GitHub credentials in the Open Clinical History source code.
2. Configure the Web Server
Create an Apache VirtualHost or equivalent Nginx configuration for the application.
For example:
https://clinical.example.org/
The web server's document root should point directly to the Open Clinical History application directory.
For example:
DocumentRoot /var/www/openclinicalhistory
Do not use:
DocumentRoot /var/www
because that could make /var/www/private reachable through the web server.
The original installation guide explicitly separates the application directory from /var/www/private for this reason.
3. Configure HTTPS
Configure SSL/TLS before using Open Clinical History with real clinical information.
Open Clinical History may contain:
patient identifiers
dates of birth
clinical records
complete medical histories
API bearer tokens
These should not be transmitted over plain HTTP.
For example:
https://clinical.example.org/
The Patient Record API also defaults to requiring HTTPS.
For Apache deployments, Let's Encrypt and Certbot can be used where appropriate.
4. Open the First-Run Setup Assistant
Once the application files are available through the web server, open:
/setup_delete_after_setup.php
For example:
https://clinical.example.org/setup_delete_after_setup.php
If Open Clinical History is installed under a subdirectory such as /demo, use:
https://clinical.example.org/demo/setup_delete_after_setup.php
The setup assistant contains the installation sequence:
0 · Preflight
1 · config.php
2 · Database
3 · App settings
4 · SNOMED
5 · Image DB
6 · Workers
7 · Patient import
8 · Finish
It is safe for this page to run before the database is working because it deliberately does not depend on the normal application bootstrap.
5. Run the Server Preflight
Select:
0 · Preflight
The installer checks the web-server PHP environment.
Checks currently include:
proc_open()
Required
CLI PHP
Required
Config template
Should be available
The setup assistant searches for a CLI PHP executable in this order:
/usr/bin/php8.5
/usr/bin/php8.4
/usr/bin/php8.3
/usr/bin/php
A working CLI PHP installation is important because long-running Open Clinical History operations execute outside the browser request.
These include background processing such as:
history_job.php
queue_worker.php
SNOMED import workers
Additional Preflight Checks
Also verify manually that:
MariaDB/MySQL is installed and reachable
HTTPS is working
the web-server/worker user can read the application
the web-server/worker user can read the SNOMED directory
the runtime directory is writable
the supplied anatomical PNG catalogue exists under img/
Do not proceed until the PHP preflight is clean.
6. Create the Private Directory
Create the private installation directory.
For example:
sudo install -pd -o root -g www-data -m 0750 /var/www/private/demo
Create the writable runtime directory:
sudo install -d -o www-data -g www-data -m 0770 /var/www/private/demo/run
Create the SNOMED storage directory if it does not already exist:
mkdir -p /var/www/private/demo/snomed
The resultresulting structure should look similar to:resemble:
/var/www/private/demo/
├── config.php
├── config_template.php
├── health_history.sql
├── run/
└── snomed/
The existing setup design uses run directory is used by Open Clinical Historyfor background processes for runtimeprocess state and job information.
The snomed directory storesfor the extractedRF2 SNOMED CT RF2terminology release.
2.7. ProtectGenerate theconfig.php
Select:
1 · config.php
The setup assistant provides an interactive config.php generator.
The form is processed entirely in the browser.
Database credentials entered into this setup form are not posted back to setup_delete_after_setup.php.
Enter:
PHP CLI binary
private runtime directory
database host
database port
database name
database username
database password
database character set
debug mode
The default runtime directory must not be publicly accessible.
For example, the following should not work:is:
https:/var/www/private/demo/run
The recommended configuration location is:
/your-domain.example/var/www/private/demo/config.php
The application needs filesystem access to these files, but they must remain outside the web server's public document root.
Pay particular attention to:
config.php
because it contains database credentials.
SNOMED CT source files may also be subject to licensing restrictions and should not be publicly downloadable.
3. CreateExample config.php
Open Clinical History includes a:
config_template.php
Use this as the starting point for the server-specific configuration.
For example:
cd /var/www/private/demo
cp config_template.php config.php
Edit:
config.php
with the appropriate settings for the server.
A typical configuration is:
<?php
return [
'php_binary' => '/usr/bin/php8.3',
'run_dir' => '/var/www/private/demo/run',
'db' => [
'host' => '127.0.0.1',
'port' => 3306,
'database' => 'health_history',
'username' => 'root'openclinicalhistory',
'password' => 'your_password',
'charset' => 'utf8mb4',
],
'debug' => false,
];
The existing guide uses the same private configuration structure and keeps config.php outside version control.
ConfigurationPHP SettingsCLI Binary
php_binary
For
Example:example:
'php_binary' => '/usr/bin/php8.3',
TheCheck CLIit PHP executable used for background processing.
Open Clinical History launches background workers such as:
history_job.php
queue_worker.php
using this PHP binary.
Confirm the configured executable exists:with:
/usr/bin/php8.3 -v
TheAnd CLI PHP installation must includeverify the extensionsimportant required by the application.
At minimum, verify:extensions:
/usr/bin/php8.3 -m | grep -E 'pdo_mysql|curl'curl|mbstring'
The CLI PHP installation can differ from the PHP installation used by Apache or PHP-FPM.
Both must be correctly configured.
run_dir
Runtime Directory
Example:For example:
'run_dir' => '/var/www/private/demo/run',
DefinesThis thedirectory privatestores runtime directoryinformation usedsuch foras:
-
job
state.status
Thelocks
worker backgroundstate
processing state
It must be ablewritable to write to this directory.
For example:
mkdir -p /var/www/private/demo/run
Set ownership and permissions appropriate toby the serverweb/worker environment.
For an Apache installation using www-data, this may look similar to:
chown -R www-data:www-data /var/www/private/demo/run
Do not blindly apply ownership commands without considering the security model of your server.account.
Database ConfigurationConnection
TheFor db section defines the MariaDB/MySQL connection.
Example:example:
'db' => [
'host' => '127.0.0.1',
'port' => 3306,
'database' => 'health_history',
'username' => 'root'openclinicalhistory',
'password' => 'your_password',
'charset' => 'utf8mb4',
],
host
Usually:
127.0.0.1
when the database runs on the same server.
port
Default MySQL/MariaDB port:
3306
database
Recommended database name:
health_history
username
Database account used by Open Clinical History.
A dedicated application database user is recommended for production rather than using the MariaDB root account.
password
Database password.
This is sensitive and must not be committed to Git.
charset
Use:
utf8mb4
This supportsfor the completedatabase character set.
Clinical records can contain the full Unicode character setset.
Database clinicalUser
Although a root database login may be convenient during development, a dedicated application account is recommended.
For example:
CREATE USER 'openclinicalhistory'@'localhost'
IDENTIFIED BY 'use-a-strong-password';
GRANT ALL PRIVILEGES
ON health_history.*
TO 'openclinicalhistory'@'localhost';
FLUSH PRIVILEGES;
Then use that account in config.php.
Debug Mode
Production installations should normally use:
'debug' => false,
Debug modeinformation maycan expose application andor database information thatand should only be enabled temporarily when troubleshooting.
Save and Protect config.php
The setup page allows the generated configuration to be:
copied
downloaded as config.php
Save it as:
/var/www/private/demo/config.php
Then protect it.
For example:
sudo chown root:www-data /var/www/private/demo/config.php
sudo chmod 640 /var/www/private/demo/config.php
The web server needs to read the file.
It should not be visiblewritable by the web process.
Do not commit config.php to endGit. users.
Onlyexisting enableinstallation debuggingguide temporarilyspecifically inkeeps aserver controlledcredentials developmentand environment.paths outside the repository.
4.8. Create the Database
Select:
2 · Database
Create the Open Clinical Historyapplication database.
For example:
CREATE DATABASE health_history
CHARACTER SET utf8mb4
COLLATE utf8mb4_unicode_ci;
AThe dedicatedbase database userschema is preferable.
For example:
CREATE USER 'och'@'localhost'
IDENTIFIED BY 'use-a-strong-password';
GRANT ALL PRIVILEGES
ON health_history.*
TO 'och'@'localhost';
FLUSH PRIVILEGES;
Then update config.php accordingly:
'username' => 'och',
'password' => 'use-a-strong-password',
5. Importwith the Database Schema
The Open Clinical History source includes the database SQL required for a new installation.
PlaceFor or copy:example:
health_history.sql
into the private installation directory if required.
For example:
/var/www/private/demo/health_history.sql
Import it into the database:it:
mysql -u ochopenclinicalhistory -p health_history \
< /var/www/private/demo/health_history.sql
Or,The ifexisting usinginstallation anotherarticle already requires loading this base schema before the application can operate.
Run All Database Migrations
The base schema is not necessarily the end of database account:setup.
Run all migrations supplied with the installed Open Clinical History release, in release order.
The current setup assistant specifically identifies migrations responsible for features including:
app_config
api_token
ingest_queue
Known migrations referenced by the current application include:
migrations/2026-08-21_config_and_api_tokens.sql
migrations/2026-08-21b_ingest_queue.sql
The release package itself should be treated as authoritative.
If additional migrations are supplied, apply those as well.
Do not skip migrations simply because the base application page loads.
Verify the Database
Connect to the database:
mysql -u root -p health_history < /var/www/private/demo/health_history.sql
Verify that the schema was imported:
mysql -u ochopenclinicalhistory -p health_history
Then:Then check:
SHOW TABLES;
YouIn shouldparticular, seebefore moving to application configuration, confirm that the required configuration and queue tables exist.
9. Configure Open Clinical History application tables.
6. Create the Web Directory
Create a directory for the web application.Select:
For3 example:· App settings
or open:
mkdir -p /var/www/openclinicalhistoryadmin_config.php
Thisconfig.php iscontains separatethe from:infrastructure settings needed to connect to the server and database.
Operational application settings are instead stored in:
/var/www/private/app_config
A typical structure is:
/var/www/
├── private/
│ └── demo/
│ ├── config.php
│ ├── run/
│ └── snomed/
│
└── openclinicalhistory/
├── index.php
├── history_import.php
├── admin_config.php
├── lib/
├── img/
└── ...
Only the application directory should be exposed through the web server.
7. Configure theat Domain
Create an Apache VirtualHost or equivalent Nginx configuration for the application.
For example:
https://clinical.example.org/
The web server's document root should point to the Open Clinical History application directory.
It should not point to:
/var/www
because this could expose the private directory.
For example:
DocumentRoot /var/www/openclinicalhistory
rather than:
DocumentRoot /var/www
8. Enable HTTPS
SSL/TLS is strongly recommended.
For a production or externally accessible installation, HTTPS should be considered required.
Open Clinical History can receive:least:
-
patientdateidentifiersformat -
datesSNOMEDofRF2birthrelease path -
clinicalLLMrecordsenabled -
medicalGeminihistoriesAPI key
Gemini model
provider limits
extraction limits
grounded SNOMED settings
API credentials
These must not be transmitted over unencrypted HTTP.
For an Apache server using Let's Encrypt, Certbot can typically be used to provision and renew the certificate.
After configuration, the application should be accessed through:
https://clinical.example.org/
rather than:
http://clinical.example.org/
The Patient Record API also defaults to requiring HTTPS.
9. Obtain Access to the Source Repository
The Open Clinical History source repository is currently private.
Repository:
https://github.com/bengoudieparkoch/openclinicalhistory
Access is provided to approved users rather than making the repository publicly available.
To request access, visit:
https://www.openclinicalhistory.org/access.php
and complete the access request form.
Once access has been approved, the repository can be cloned onto the server.
10. Clone the Repository
After GitHub access has been granted:
cd /var/www
Clone the repository:
git clone https://github.com/bengoudieparkoch/openclinicalhistory.git
This will normally create:
/var/www/openclinicalhistory
For subsequent deployments:
cd /var/www/openclinicalhistory
git pull
The exact authentication method depends on the GitHub account and server configuration.
GitHub may use:
SSH keysconfiguration
aingest personal access token
another approved Git credential mechanism
Do not store GitHub credentials directly in application source files.
11. Ensure config.php Is Not in the Web Repository
The server-specific:
config.php
should remain in:
/var/www/private/demo/
rather than being committed into the repository.
Conceptually:
Git repository
|
| application code
v
/var/www/openclinicalhistory
Private server configuration
|
v
/var/www/private/demo/config.php
This keeps:
database passwords
filesystem paths
server-specificqueue configuration
outThe ofexisting versionserver control.article already places these settings after database setup and before SNOMED processing.
12.Gemini ConfigureAPI WebKey Servervs Permissions
The web-server process must be able to:
read the application source
read the private configuration
write to the configured run_dir
read the SNOMED CT directory when running imports
It generally should not need write access to the entire application source tree.
A more secure model is:
Application code
read-only to web process
Private config
read-only to web process
Run directory
read/write to web and workers
SNOMED files
read-only to web/workers
13. Check PHP Requirements
Confirm the web and CLI PHP environments contain the required modules.
For CLI PHP:
/usr/bin/php8.3 -m
Important modules include:
PDO
pdo_mysql
curl
json
mbstring
The exact installed module set will depend on the application version.
Also check:
/usr/bin/php8.3 -v
to confirm the version configured in:
'php_binary'
matches the installed binary.
14. Create the SNOMED Directory
Create a protected directory for SNOMED CT RF2 source releases:
mkdir -p /var/www/private/demo/snomed
A release may contain directories similar to:
Full/
Snapshot/
Delta/
with subdirectories such as:
Terminology/
Refset/
Open Clinical History usesAPI Token
These are two different credentials.
Gemini API key
Used for:
Open Clinical History
|
v
Gemini
It authenticates outbound LLM requests.
Open Clinical History API token
Used for:
External clinical system
|
v
Open Clinical History Patient Record API
It authenticates inbound patient-document submissions.
Do not confuse the Snapshot data for its normal SNOMED import.
The raw SNOMED source files can be very large.
Allow sufficient:
disk space
database space
processing time
for the import.two.
15.API Open the ApplicationToken
After:
databasewill configuration
schema import
Git deployment
web-server configuration
permissions
have been completed, open:through:
https://your-domain.example/history_api_import.php
Confirmcreate thatan theAPI applicationtoken loads without a database or configuration error.
16. Complete Application Configuration
Open:under:
Admin → Configuration
ConfigureFor a normal importing integration, the runtimelikely applicationscopes settings.
At minimum, review:are:
Dateimport
formatstatus
SNOMED CT RF2 release path
LLM enabled
Gemini API key
Gemini model
LLM usage limits
API configuration
Ingest queue configurationcommit
SetStore the token immediately.
The plaintext token is displayed only once.
Only its hash is stored afterwards.
Enable the import API only after HTTPS has been configured.
10. Install SNOMED pathCT
Select:
4 · SNOMED
Open Clinical History does not redistribute SNOMED CT.
The installing organisation must obtain the authorised terminology release under the appropriate SNOMED licensing arrangements.
For an Australian installation, obtain the appropriate SNOMED CT-AU RF2 Snapshot release.
Store the extracted files in the protected RF2server location.directory.
For example:
/var/www/private/demo/snomed
A release may contain:
Full/
Snapshot/
Delta/
with directories such as:
Terminology/
Refset/
The previous server guide already specifies the Snapshot release as the source for normal Open Clinical History imports.
17.Configure Importthe SNOMED Path
Under:
Admin → Configuration → SNOMED CT RF2
set:
/var/www/private/demo/snomed
or the root of the specific extracted release.
Run SNOMED Import
Open:
SNOMED Import
or:
/snomed_import.php
Confirm that the RF2 inventory detects:
Concept Snapshot
Description Snapshot
Relationship Snapshot
Language Snapshot
Then run:
Start or resume pipeline
The initialoriginal SNOMEDinstallation importguide canalso takerequires aall significantfour amount of time.
The source data contains millions of rows.
Allow the pipeline to completedatasets before proceeding.
18.SNOMED Import Can Take a Long Time
SNOMED CT is large.
The import involves millions of terminology rows and multiple derived-index stages.
Do not proceed simply because the first RF2 tables have been populated.
Wait until the entire SNOMED pipeline reports completion.
The setup assistant deliberately requires the administrator to confirm:
SNOMED import completed and verified
before enabling the Image DB step.
11. Build the Image / SNOMED Database
AfterSelect:
5 SNOMED· pipelineImage hasDB
or open:
/build_image_db.php
Do this Image/only after SNOMED import has completely finished.
The image build combines:
Completed SNOMED terminology
+
Installed anatomical PNG catalogue
|
v
Image / SNOMED Summary Build
|
v
Clinical concept ↔ anatomy ↔ image mappings
Run:
Clean rebuild image summary database
ThisThe connectsexisting theinstallation installedsequence anatomicalalso imageplaces cataloguethis tooperation theimmediately localafter SNOMED database and builds the compact runtime mapping tables.
This operation can also take some time.import.
19.Verify the Image Build
Review the resulting coverage, including:
active PNG layers
SNOMED seed rows
anatomy hierarchy rows
concept/image rows
mapped clinical concepts
anatomical layers without verified SNOMED seeds
Do not proceed to production patient ingestion until the result looks sensible.
12. Configure the IngestPersistent Queue WorkerWorkers
If:Select:
queue_enabled6
· WorkersisQueued enabled,API atingestion least one:requires:
queue_worker.php
process shouldto be running.
ForWithout testing,a itqueue worker, records can beenter:
ingest_queue
manually:but will remain there waiting for processing.
For testing:
cd /var/www/openclinicalhistory
/usr/bin/php8.3 queue_worker.php
The existing server documentation also recommends running the queue worker under a persistent service manager rather than relying on a terminal session.
Use a Service Manager
For production, configure it usinguse a host-level process supervisormanager such as:
-
systemd
-
Supervisor
-
another
suitableappropriate service manager
TheWorkers should restart automatically following:
process crashes
application failures
server reboots
Do not rely on a browser connection to keep a queue worker should be configured to restart if it exits unexpectedly.alive.
20.Worker TestCount
The setup assistant recommends starting conservatively and tuning worker concurrency according to:
CPU capacity
Gemini concurrency
configured LLM budgets
database load
available memory
More workers are not automatically better.
The LLM provider, database and token budget can become the limiting resources before CPU does.
Monitor Workers
Open:
/import_monitor.php
Confirm that the expected worker processes are visible before proceeding.
13. Import the First Patient
Select:
7 · Patient Importimport
Do not begin with bulk production data.
The recommended first validation is a single known:
synthetic
or:
de-identified
patient history.
Open:
/history_import.php
Upload a smallone plain-text clinicalhistory history.and allow it to complete.
Confirm
Validate the workflowEntire canPipeline
For the first patient:
Upload
|
v
Extract
|
v
Audit & Import
|
v
Complete
This provides an end-to-end check of:
-
databaseUploadconnectivitythe source history. -
CLIStartworker configurationextraction. -
GeminiWatchconfigurationprocessing through the available monitoring screens. -
SNOMEDReviewlookupthetablesextracted clinical events. -
anatomicalReviewlookupSNOMEDtablesCT classifications. -
runtimeReviewdirectoryanatomicalpermissionsmappings. -
Check the original source evidence.
Review date precision and chronology.
Review the audit output.
Confirm unresolved terminology appears in the Learning Queue instead of being silently guessed.
Complete the import.
Open the resulting patient history.
The existing guide already uses manual import as the end-to-end validation of database, worker, Gemini, SNOMED and anatomy configuration.
21.14. Test the Patient Record API
IfOnly after the APImanual willtest has succeeded should an external integration be used:
Open Admin → Configuration.
Confirm the API is enabled.
Create an API token.Use:
Give it only the required scopes.
Test:
/history_api_import.php?action=ping
usingwith aan Open Clinical History Bearer token.
Then test one non-production record through the API.
Verify:
submission
|
v
queued
|
v
extracting
|
v
audit / commit
|
v
patient history
Do not expose the API credentialstoken inin:
browser-side JavaScript
public source repositories.code
Git repositories
documentation
The original article similarly places API testing after manual patient validation.
Suggested15. Finish the Installation
Select:
8 · Finish
Before removing the setup assistant, confirm:
private config.php is outside the web root
config.php permissions are restricted
base database schema is installed
all database migrations are installed
Gemini/application settings are configured
SNOMED CT has completed and verified
Image/SNOMED database has completed and verified
queue workers are supervised and running
a test patient completed successfully end-to-end
the API has been tested if it will be used
backups have been configured
16. Delete setup_delete_after_setup.php
This step is mandatory.
The first-run installer exposes information useful during server configuration and is intentionally not part of the normal running application.
Once installation has been proven:
cd /var/www/openclinicalhistory
rm setup_delete_after_setup.php
If your application is installed somewhere else, adjust the path accordingly.
For example:
cd /var/www/openclinicalhistory/demo
rm setup_delete_after_setup.php
Confirm that:
https://your-domain.example/setup_delete_after_setup.php
now returns:
404 Not Found
or is otherwise inaccessible.
Open Clinical History does not depend on this file after installation.
Do not leave it available on a production server.
Updating Open Clinical History Later
After the initial installation:
cd /var/www/openclinicalhistory
git pull
Review the release for:
database migrations
changed configuration requirements
SNOMED rebuild requirements
Image/SNOMED rebuild requirements
worker changes
Do not assume that every application update requires a SNOMED or image rebuild.
Follow the release-specific instructions.
If setup_delete_after_setup.php is restored by a later Git update, do not leave it publicly accessible simply because the server is already configured.
Remove it again unless it is deliberately required for a controlled upgrade procedure.
Recommended File Permissions
Conceptually:
Application source
read by web server
config.php
root owned
readable by web-server group
not writable by web server
run/
readable/writable by workers
snomed/
readable by application/workers
not web accessible
For example:
sudo chown root:www-data /var/www/private/demo/config.php
sudo chmod 640 /var/www/private/demo/config.php
The existing deployment guide also recommends giving the web process write access only where required rather than across the whole application.
Backups
Before using Open Clinical History for important patient information, configure regular backups.
At minimum, protect:
Open Clinical History database
private config.php
application-specific customisations
anatomical image catalogue
The original deployment guidance also recommends retaining the exact SNOMED release where practical because it simplifies recovery and auditing.
Do not rely on Git as a patient-data or database backup.
Security Checklist
A production installation should include:
HTTPS only
dedicated database credentials
restrictive filesystem permissions
/var/www/private inaccessible through HTTP
no secrets committed to Git
protected administration pages
secure API bearer tokens
current operating-system security updates
database backups
appropriate firewall restrictions
supervised background workers
deletion of setup_delete_after_setup.php
These controls build on the security requirements already identified in the server guide.
New Server Checklist
Obtain repository access
Clone Open Clinical History
Configure Apache/Nginx
Configure HTTPS
Open setup_delete_after_setup.php
Pass server preflight
Create /var/www/private/<environment>
Create private runrun/ directory
Create private snomedsnomed/ directory
Copy config_template.php toGenerate config.php
ConfigureProtect PHP CLI path
Configure runtime directory
Configure database connectionconfig.php
Create MariaDB/MySQL database
Create dedicated application database user
Import health_history.sql
RequestApply accessall torelease the private GitHub repository
Clone Open Clinical History
Create Apache/Nginx virtual hostmigrations
Confirm privateapp_config
theConfirm webapi_token
Confirm ingest_queue
Configure HTTPS
Verify web PHP extensions
Verify CLI PHP extensions
Configure applicationAdmin settings
Configure Gemini
Install SNOMED CT RF2 releaseSnapshot
Run SNOMED Import
Verify SNOMED pipeline completion
Run Image/SNOMED Summary Build
Verify image/SNOMED coverage
Configure persistent queue_worker.php
Confirm workers in Import Monitor
Test manualone synthetic/de-identified patient
Review SNOMED, anatomy, evidence and audit
Test Patient Record API if required
Confirm backups are configured
Recommended Production Structure
A production deployment should ultimately look conceptually like:
Internet
|
v
HTTPS / TLS
|
v
Apache / Nginx
|
v
/var/www/openclinicalhistory
|
+--------------+--------------+
| |
v v
PHP application CLI workers
| |
+--------------+--------------+
|
v
/var/www/private/demo
| | |
| | |
v v v
config.php run/ snomed/
|
v
MariaDB/MySQL
The public web server exposes the application.
It does not expose:
config.php
SNOMED RF2 files
runtime job state
database SQL backups
Backups
Before using Open Clinical History with important patient information, configure regular backups.
At minimum, back up:
Open Clinical History database
private configuration
application-specific customisations
anatomical image catalogue
The SNOMED RF2 source files can usually be downloaded again from the authorised distributor, but retaining the exact release used by the installation can simplify recovery and auditing.
Do not rely on Git as a database or patient-data backup.
Security Notes
A new server may hold sensitive clinical information.
Recommended minimum controls include:
HTTPS only
private database credentials
dedicated database user
restrictive filesystem permissions
no public access to /var/www/private
no credentials committed to Git
protected administrative access
secure API bearer tokens
regular operating-system updates
regular databaseConfigure backups
firewall restrictionsDelete appropriatesetup_delete_after_setup.php
Confirm the installationsetup page is no longer web accessible
The sample configuration uses root as the database user for simplicity.
A dedicated database user should be used for a production deployment.
Installation Order Summary
AThe complete newfirst-run installationsequence follows this sequence:is:
1. PrepareObtain serversource access
|
v
2. Deploy application
|
v
3. Configure domain + HTTPS
|
v
4. Open setup_delete_after_setup.php
|
v
5. Pass server preflight
|
v
6. Create private directories
|
v
3.7. ConfigureGenerate config.php
|
v
4.8. Create database
|
v
5.9. ImportLoad health_history.sqlbase schema + migrations
|
v
6. Request GitHub repository access
|
v
7. Clone application
|
v
8. Configure domain and HTTPS
|
v
9.10. Configure Admin settings + Gemini
|
v
10.11. Install SNOMED RF2
files|
v
12. Run SNOMED Import
|
v
11. Import SNOMED
|
v
12.13. Build Image/SNOMED database
|
v
13.14. Start supervised queue worker
|
v
14. Test patient importworkers
|
v
15. TestImport APIone test patient
|
v
System16. readyReview complete patient history
|
v
17. Test API if required
|
v
18. Configure backups
|
v
19. DELETE setup_delete_after_setup.php
|
v
SYSTEM READY
RepositoryWhy Accessthe Setup Assistant Must Be Deleted
Opensetup_delete_after_setup.php Clinicalexists Historyonly to help bootstrap a new installation.
It performs checks and displays server information that is useful to an administrator during deployment but should not currentlyremain distributedexposed throughafterwards.
It can display information such as:
installed PHP version
PHP extensions
detected CLI PHP path
expected private filesystem paths
installation sequence
application administration locations
It also contains a publicbrowser-side sourceconfig.php repository.generator.
ApprovedAlthough usersthe cangenerator requestdoes accessnot at:submit the entered credentials to the server, there is no operational reason for the installer to remain publicly available once the server has been configured.
The filename is deliberately explicit:
https://www.openclinicalhistory.org/access.setup_delete_after_setup.php
OnceWhen approved,setup repositoryis accesscomplete, candelete be provided for:it.
https://github.com/bengoudieparkoch/openclinicalhistory
This allows controlled access to the source while the project remains under active development.