Vagrant and Shared Folders

To those who’ve built Orthanc with Vagrant,

I’ve encountered problems when using the synced_folder option in Vagrant for the Orthanc Database and Webviewer cache directories.

Previously, I built Orthanc 0.9.3 within Vagrant and shared the orthanc DICOM storage directory out to the Vagrant host machine by way of the synced_folder option. The sqlite DB and web cache directories were kept inside the virtual client machine. Everything ran smoothly (web browser, receiving incoming DICOM, REST commands, etc.)

I recently built an Orthanc 1.0.0 version within Vagrant and that too works with the Orthanc DICOM storage directory set to a synced vagrant folder.

Unfortunately, I don’t seem to be able to move either the Orthanc sqlite DB or Webviewer cache folders to a synced vagrant folder. When I do so, Orthanc will run once and then not again. Launching Orthanc a second time (after shutting down the first) produces errors from sqlite.

With both the sqlite db and web cache directories set to a shared folder, relaunching Orthanc is unsuccessful. The process seems to crash somewhere around preparing the web viewer cache:

0204 23:00:05.550603 PluginsManager.cpp:167] Storing the cache of the Web viewer in folder: /media/external/WebViewerCache
0204 23:00:05.556290 PluginsManager.cpp:163] SQLite: Cannot prepare a cached statement
0204 23:00:05.556855 PluginsManager.cpp:101] Error while initializing plugin /usr/local/share/orthanc/plugins/ (code -1)

Moving the Web Viewer cache folder back inside the Vagrant machine, while keeping the sqlite DB and DICOM folders on vagrant synced folders generates an error when relaunching Orthanc:

W0204 23:03:07.620976 OrthancInitialization.cpp:910] SQLite index directory: “/media/external/OrthancDB”
W0204 23:03:07.622403 OrthancInitialization.cpp:980] Storage directory: “/media/external/OrthancStorage”
E0204 23:03:07.626404 StatementReference.cpp:85] SQLite: disk I/O error

As long as I keep the Web viewer cache and sqlite DB folders within the vagrant box, things appear to work fine. Orthanc can be shutdown and relaunched and operated without problem.

My theory is that there’s a permission (perhaps umask) problem between the vagrant client and the host machine. I’m running VirtualBox as my vagrant provider. Somewhere, Vagrant or virtualbox must negotiate the file ownership UID between the client and the host machine for the shared folder. What I don’t understand is why this would particularly affect the sqlite database (or web viewer cache) and not the DICOM files.

The process running vagrant has more restrictive permissions (umask 0007) than the internal vagrant client process (umask 0002). There might be a conflict there, but I’ve tried lowering the external permissions without effect.

Do either the sqlite or web viewer cache functions need world/other file permissions for any reason?

It occurs to me that there might be an issue with file locking across a shared folder. Does sqlite perform some sort of file lock on its files or folders? I’m not sure why this would not cause a problem the first time Orthanc was run but always cause a problem when relaunching.

I’d appreciate suggestions. We’d like to share the database out to the hose machine for purposes of backup.


I strongly suspect file locking is the source of my problem. If the VirtualBox file sharing mechanism can’t handle file locking, there’s not much I can do. For future reference:


I have seen similar issues: I’m running unit tests with Vagrant on a Linux box. Running the tests directly in the /vagrant folder (which is a VirtualBox shared folder) gives my “unable to open database file” errors. My workaround is to copy the tests to /tmp and run them there. So it is definitely an issue of the combination VirtualBox shared folder implementation + SQLite locking mechanism. – schlamar Oct 14 '13 at 7:19

As a followup, I found one configuration that seems to work for our setup and backup needs. Our original goal was to have Orthanc store its database and cache data to folders shared out by VirtualBox to the host machine, both for ease of backup and to avoid filling the client virtual machine’s disk.

In our current setup, I locate Veracrypt container files in folders shared by the host and vagrant/Virtualbox machine - similar to my failed attempt to write the Orthanc data to these shared folders. In this case, however, the container is decrypted and mounted internally by the client virtual machine.

Once mounted internally, the veracrypt container looks like any other internal directory to Orthanc. Apparently, the veracrypt file system manages file locking and caching better than the Virtualbox shared folder file system. We do not encounter any of the sqlite locking corruption problems or file caching issues we ran into when writing directly to the Virtualbox shared folders. Data is properly recorded to the veracrypt container and is consistent across veracrypt dismounts, Orthanc start/stop, and vagrant machine reboots.

I should note that in trying to debug the previous setup, I did turn off Host I/O caching on the vagrant virtualboxes. That did not help when writing directly to the shared folders, but may help in the new setup using veracrypt containers.