Package: psyserver
PsyServerA server to host your online studies on.PsyServer is a simple, easy to setup server on which to host online studies safely and conveniently.
It does not require you to commit to a certain framework, and eliminate the need to put excessive time into setting up backends and servers.FeaturesPsyServer usesFilebrowserto enable easy and safe access to the study code, and study data:Every study placed into thestudiesfolder becomes accessible from the internet.Data from the study is saved in thestudydatafolder, which is only accessible via the filebrowser and an account.Both the studies and studydata folder can easily modified and downloaded from the online interface, eliminating the need forputty or ssh.Filebrowser allows for user management, making collaboration with others easy and convenient.SetupTo setup a fully functional server to host studies on, you will require following things:A host machine to run the server onInstalling PsyServerGet a domain (optional)Setup HTTPS (optional)Run the ServerHost machineA host machine to run the server on will be required. It is highly recommended it is a linux machine.
For example, you can set up anaws ec2 instancefor little cost.PsyServer SetupPsyServer itself comes as a python package and is installed as such.
At least python 3.11 is required; it is recommended to use avirtual environment. Here, we useconda(miniconda installation guide).
For easy access of files, you need to install [filebrowser] in addition.# 1. create psyserver foldermkdirpsyservercdpsyserver# 2. set up conda environment (optional)condacreate-npsyserverpython=3.11
condaactivatepsyserver# 3. install packagepipinstallpsyserver# 4. install filebrowsercurl-fsSLhttps://raw.githubusercontent.com/filebrowser/get/master/get.sh|bash# 5. create example config/structure.psyserverinit# 6. configure server (optional)# open psyserver.toml with your editor of choice, e.g. vimvimpsyserver.toml# 7. run serverpsyserverrunRunning setupAlthough you could just run psyserver as background job in your console, that would come at the disadvantage that when the server crashes or restarts, psyserver will not brestart automatically.
Thus it is recommended to setup PsyServer assystemd service.Thepsyserver initwill create the unitfilepsyserver.servicein your directory.
You need to place that unitfile into a systemd subdirectory:$sudomvpsyserver.service/etc/systemd/system/
$sudochownroot:root/etc/systemd/system/psyserver.service
$sudochmod644/etc/systemd/system/psyserver.serviceNow reload systemctl.$sudosystemctldaemon-reloadStart the service.$sudosystemctlstartpsyserverCheck on the service (leave withQ).$sudosystemctlstatuspsyserver
●psyserver.service-PsyServerService.Loaded:loaded(/home/ubuntu/.config/systemd/user/psyserver.service;disabled;vendorpreset:enabled)Active:active(running)Enable the server for autostart.$sudosystemctlenablepsyserverFor stopping and disabling use:$sudosystemctlstoppsyserver
$sudosystemctldisablepsyserverDomain NameUsing a domain name is recommended, but operation is possible without. Domains can be acquired at websites such asnamecheap.
You will require a domain if you want to use https.httpshttps ensure safe communication between participants and your server. It is highly recommend to set up https.
Setting up https yourself can be quite tricky, it is thus recommended to use Caddy as Reverse Proxy.
A reverse proxy is another application running on your machine which handles the connections from the internet to a server, in this case PsyServer.Install CaddySetup up the Caddy ServiceSetup Caddy as reverse ProxyUse this Caddyfile with the default configuration of PsyServer.example.com
{
  reverse_proxy :5000
}

admin.example.com
{
  reverse_proxy :5050
}Replaceexample.comwith yourdomain.Reload Caddysudo systemctl reload caddy.That's it!You can also setup uvicorn directly to handle https (uvicorn https documentation). Settings are set inpsyserver.tomlunder[uvicorn]with exactly the same keys as the documentation, without the--.Configurationpsyserver.tomlconfigures the server.
This file has to be in the directory from whichpsyserver runis called.The configuration has two groups:psyserver: all PsyServer configuratonsuvicorn: Uvicorn configurationspsyserver config[psyserver]studies_dir="studies"data_dir="data"redirect_url="https://www.example.com"studies_dir: path to directory which contains studies. Any directory inside will be reachable via the url. E.g. a study in<studies_dir>/exp_cute/index.htmlwill have the url<host>:<port>/exp_cute/index.html.data_dir: directory in which study data is saved. E.g. data submissions to the url<host>:<port>/exp_cute/savewill be saved in<data_dir>/exp_cute/. Has to be different fromstudies_dir.redirect_url: Visitors will be redirected to this url when accessing routes that are not found. Without this key, a 404 - Not found html will be displayed.uvicorn config[uvicorn]host="127.0.0.1"port=5000Here configures the uvicorn instance runnning the server. For example, uou can specify thehost,portand https configurations.
For all possible options, use the commands in theuvicorn settings documentationwithout--.How to save data to psyserverTo save participant data to the server it has to be sent in the json format of a POST request.
The POST request can be made to/<study>/savewhich saves data as a json file.
Upon succesful saving, a json object{success: true}is returned.
Provide theparticipantIDkey such that the saved data will be named with the participantID.// example dataparticipant_data={participantID:"debug_1",condition:"1",experiment1:[2,59,121,256],// ...};// post data to server$.ajax({url:"/exp_cute/save",type:"POST",data:JSON.stringify(participant_data),contentType:"application/json",success:()=>{console.log("Saving successful");// success function},}).fail(()=>{console.log("ERROR with $.post()");});Note that you need to callJSON.stringifyon your data. Without this, you will get anunprocessable entityerror.DevelopmentSetup# 1. set up conda environment$condacreate-npsyserverpython=3.11
$condaactivatepsyserver# 2. clone$gitclonegit@github.com:GabrielKP/psyserver.git
$cdpsyserver# 3. install in editor mode$pipinstall-e.Testing# normal test$pytest.-v# coverage$coveragerun-mpytest# html report$coveragehtmlPublishing$flitpublish