Setting up a server
ESMira is meant to be set up very easily and without much technical knowledge required. Additionally, there are very little requirements and ESMira should work on most servers out of the box.
We offer two methods for installation. Pick the one you are most familiar with. If you already have a PHP server running, we advise you to follow the native installation. Choose Docker if it is already set-up on your server. Otherwise, it does not really matter. Both should only take a few minutes to set up. And both can be updated very easily using the web interface.
Its minimal requirements are:
- PHP 7.4 or greater.
- PHP needs write access in the file system (which it usually has).
- For an easy setup: Support for .htaccess files (See below for a setup without .htaccess).
Note
These instructions assume that you want to install ESMira in the root folder of your domain (e.g. https://example.com/). ESMira can also be installed in a sub folder (e.g. https://example.com/thisIsAFolder/subSubFolder) without any additional steps required. Just copy the files to the desired location.
Download the zipped release of ESMira: Direct link
Unzip the ESMira-web.zip you just downloaded, and copy all its contents to the web folder of your server. (On most apache web servers this folder would be /var/www/).
If you copied the correct files, the web folder should have at least four folders (named api, backend, frontend and locales) and a bunch of other files.
Note
Setting the permissions is needed, so ESMira is able to create its config files and is also required so updates can be installed automatically.
Make sure that PHP has write access to all files you just copied.
On most UNIX systems (e.g. Linux or macOS) it is sufficient to just change the file owner of all the folders and files that you just copied to www-data. On Windows, this step is probably not needed.
Your server has been installed. Now, you need to set up your admin account. Continue at Complete the setup.
You should also check Optional steps for specific server setups before you finish.
Note
This will set up a docker container with an Apache server that runs PHP and has the according ESMira files already downloaded automatically.
Create a new directory and move there:
mkdir ./esmira
cd ./esmiraDownload the docker compose file:
wget -O https://raw.githubusercontent.com/KL-Psychological-Methodology/ESMira-web/refs/heads/master/docker-compose.ymlRun the container:
docker compose up -dYour server has been installed. Now, you need to set up your admin account. Continue at Complete the setup.
Then, start your web browser and open the admin interface (e.g. https://example.com?admin).
The page should look like this:
Note
In order to use the admin interface, make sure that your browser is up-to-date and has JavaScript enabled. You should also have Cookies enabled or auto log in will not work.
Follow the instructions and provide a data path, username and password. Make sure that the password is secure because this account will be able to view, change and delete all studies and data on your ESMira server!
Caution
Make sure to remember your admin password. There is no (easy) way to retrieve it afterwards!
Your own ESMira server should now be set up successfully!
If you run into any problems, have a look at Common problems. If that does not help, the discussion forum can help you. Next, you should read Conditions for using ESMira and The admin interface.
Note
If you are using Docker, this will not be necessary.
The following instructions are only necessary if you get warned on the initialization page that your server does not support URL rewrite (notably .htaccess files and / or the mod_replace feature of apache server).
Most features of ESMira will work without URL rewrite except for two things:
- Making sure that the data folder is not accessible from the internet.
Caution
Without .htaccess support (or alternatives) you need to make sure that the "esmira_data" directory is at a location that can not be accessed from the internet or all your study data will be easily accessible to everybody!
- Short study urls as listed in Urls to web version.
Enabling URL rewrite is different on different server architectures. Please follow the instructions according to your server:
In order to enable .htaccess support, you need to change /etc/apache2/sites-available/default (depending on your setup, you might have to change the vhost file that is responsible for ESMira).
Locate the section labeled <Directory /var/www> (/var/www might be different depending on your server setup). Add a new line somewhere between the <Directory> tags with the content:
AllowOverride All
Then restart apache2 by running in the console (you need to run this command with root privileges):
service apache2 restart
(needed to make short links to studies work)
Run the following command in your console (you need to run this command with root privileges):
a2enmod rewrite
Then restart apache2 by running (with root privileges):
service apache2 restart
(this section has only partly been tested and probably can be improved - we would be happy to receive feedback :) ).
In your vhost configuration in /etc/nginx/sites-available/000-default (depending on your setup, you might have to change the vhost file that is responsible for ESMira) add the following lines in the server { section:
# to a study
location / {
# www.example.com/1234
if ($request_uri ~ "\d$"){
rewrite ^/(\d+)$ /index.php?id=$1 last;
}
# www.example.com/KEY
rewrite ^/([a-zA-Z][a-zA-Z0-9]+)$ /index.php?key=$1 last;
# www.example.com/1234-KEY
rewrite ^/(\d+)-([a-zA-Z][a-zA-Z0-9]+)$ /index.php?id=$1&key=$2 last;
}
#to app instructions
location /app {
# www.example.com/app-1234
rewrite ^/app-(\d+)$ /index.php?id=$1&app_install last;
# www.example.com/app-KEY
rewrite ^/app-([a-zA-Z][a-zA-Z0-9]+)$ /index.php?key=$1&app_install last;
# www.example.com/app-1234-KEY
rewrite ^/app-(\d+)-([a-zA-Z][a-zA-Z0-9]+)$ /index.php?id=$1&key=$2&app_install last;
}
# to questionnaire
location /survey {
# www.example.com/survey-12345
rewrite ^/survey-(\d+)$ /index.php?qid=$1 last;
# www.example.com/survey-12345-KEY
rewrite ^/survey-(\d+)-([a-zA-Z][a-zA-Z0-9]+)$ /index.php?qid=$1&key=$2 last;
}
location /api {
# Needed for uploading big files (i.e. photo or voice_input item):
client_max_body_size 0;
# Fallback in case we ever want to replace the php backend:
rewrite ^/api/([^.]+)$ /api/$1.php last;
}
# Deny access to backend files and esmira_data
location ~ /(backend|esmira_data) {
deny all;
return 404;
}
Please open an issue, and we will try to figure it out together. If you were able to set up ESMira without or help please provide us with your settings, so we can add them to the wiki! :)
Note
We advise you to update the server on a regular basis. But while we thoroughly test all our changes, there can always be unforeseen side effects. Before you update, read the change logs of all version changes. Usually we add warnings, when an update has a chance of causing issues.
Note
If you are using Docker, you can either use the web interface or update the whole container through Docker (docker compose pull && docker compose up -d --remove-orphans and docker image prune). Both methods will just replace the server files of ESMira. But be aware that the Apache and PHP server inside the container will only be updated if you update the whole container via Docker.
ESMira can update itself automatically through the web interface. All you need to do is login via the web interface (your account needs to have admin permissions on ESMira), go to "Server Settings" (https://example.com/?admin#admin/serverSettings) and click the update button (if an update is available)
Unfortunately Android apps are not able to connect to servers using a self-signed certificate. If you want participants using Android smartphones be able to participate in your study, we recommend using https://letsencrypt.org/ instead.
Most likely this is caused because ESMira does not have sufficient permissions. Are you sure you have done Step 3: Set the correct file permissions properly?
Have a look in your error.log (usually found in /usr/var/log/apache/error.log or /usr/var/log/nginx/error.log). It will tell you what exactly went wrong.
If that does not help, the discussion forum can help you (when posting, consider adding the contents of your error.log).