<div align="center">
# PsyServer
## A server to host your online studies on.
</div>
<p align="center">
<a href="https://github.com/psf/black/blob/main/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
<a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://img.shields.io/pypi/v/black"></a>
<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
</p>
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.
## Features
PsyServer uses [Filebrowser](https://filebrowser.org/) to enable easy and safe access to the study code, and study data:
Every study placed into the `studies` folder becomes accessible from the internet.
Data from the study is saved in the `studydata` folder, 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 for `putty or ssh`.
Filebrowser allows for user management, making collaboration with others easy and convenient.
## Setup
To setup a fully functional server to host studies on, you will require following things:
1. A host machine to run the server on
2. Installing PsyServer
3. Get a domain (optional)
4. Setup HTTPS (optional)
5. Run the Server
### Host machine
A 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 an [aws ec2 instance](https://aws.amazon.com/ec2/) for little cost.
### PsyServer Setup
PsyServer itself comes as a python package and is installed as such.
At least python 3.11 is required; it is recommended to use a [virtual environment](https://docs.python.org/3/library/venv.html). Here, we use [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) ([miniconda installation guide](https://docs.conda.io/projects/miniconda/en/latest/)).
For easy access of files, you need to install [filebrowser] in addition.
```sh
# 1. create psyserver folder
mkdir psyserver
cd psyserver
# 2. set up conda environment (optional)
conda create -n psyserver python=3.11
conda activate psyserver
# 3. install package
pip install psyserver
# 4. install filebrowser
curl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash
# 5. create example config/structure.
psyserver init
# 6. configure server (optional)
# open psyserver.toml with your editor of choice, e.g. vim
vim psyserver.toml
# 7. run server
psyserver run
```
### Running setup
Although 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 as [systemd service](https://github.com/torfsen/python-systemd-tutorial).
The `psyserver init` will create the unitfile `psyserver.service` in your directory.
You need to place that unitfile into a systemd subdirectory:
```sh
$ sudo mv psyserver.service /etc/systemd/system/
$ sudo chown root:root /etc/systemd/system/psyserver.service
$ sudo chmod 644 /etc/systemd/system/psyserver.service
```
Now reload systemctl.
```sh
$ sudo systemctl daemon-reload
```
Start the service.
```sh
$ sudo systemctl start psyserver
```
Check on the service (leave with `Q`).
```sh
$ sudo systemctl status psyserver
● psyserver.service - PsyServer Service.
Loaded: loaded (/home/ubuntu/.config/systemd/user/psyserver.service; disabled; vendor preset: enabled)
Active: active (running)
```
Enable the server for autostart.
```sh
$ sudo systemctl enable psyserver
```
For stopping and disabling use:
```sh
$ sudo systemctl stop psyserver
$ sudo systemctl disable psyserver
```
### Domain Name
Using a domain name is recommended, but operation is possible without. Domains can be acquired at websites such as [namecheap](https://www.namecheap.com/).
You will require a domain if you want to use https.
### https
https 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.
1. [Install Caddy](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)
2. [Setup up the Caddy Service](https://caddyserver.com/docs/running#using-the-service)
3. [Setup Caddy as reverse Proxy](https://caddyserver.com/docs/quick-starts/reverse-proxy)
Use this Caddyfile with the default configuration of PsyServer.
```Caddyfile
example.com
{
reverse_proxy :5000
}
admin.example.com
{
reverse_proxy :5050
}
```
Replace `example.com` with your `domain`.
Reload Caddy `sudo systemctl reload caddy`.
That's it!
You can also setup uvicorn directly to handle https ([uvicorn https documentation](https://www.uvicorn.org/deployment/#running-with-https)). Settings are set in `psyserver.toml` under `[uvicorn]` with exactly the same keys as the documentation, without the `--`.
## Configuration
`psyserver.toml` configures the server.
This file has to be in the directory from which `psyserver run` is called.
The configuration has two groups:
1. psyserver: all PsyServer configuratons
2. uvicorn: Uvicorn configurations
### psyserver config
```toml
[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.html` will 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/save` will be saved in `<data_dir>/exp_cute/`. Has to be different from `studies_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
```toml
[uvicorn]
host = "127.0.0.1"
port = 5000
```
Here configures the uvicorn instance runnning the server. For example, uou can specify the `host`, `port` and https configurations.
For all possible options, use the commands in the [uvicorn settings documentation](https://www.uvicorn.org/settings/) without `--`.
## How to save data to psyserver
To 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>/save` which saves data as a json file.
Upon succesful saving, a json object `{success: true}` is returned.
Provide the `participantID` key such that the saved data will be named with the participantID.
```js
// example data
participant_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 call `JSON.stringify` on your data**. Without this, you will get an `unprocessable entity` error.
## Development
### Setup
```sh
# 1. set up conda environment
$ conda create -n psyserver python=3.11
$ conda activate psyserver
# 2. clone
$ git clone git@github.com:GabrielKP/psyserver.git
$ cd psyserver
# 3. install in editor mode
$ pip install -e .
```
### Testing
```sh
# normal test
$ pytest . -v
# coverage
$ coverage run -m pytest
# html report
$ coverage html
```
### Publishing
```sh
$ flit publish
```
Raw data
{
"_id": null,
"home_page": null,
"name": "psyserver",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.11",
"maintainer_email": null,
"keywords": "experiments, studies, behavioral, online, server",
"author": null,
"author_email": "Gabriel Kressin Palacios <gabriel.kressin@homtail.de>",
"download_url": "https://files.pythonhosted.org/packages/bd/19/2540699ed3f7404706190ea6b9fec142a91eb2b765a20604a9dd2586594f/psyserver-0.5.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# PsyServer\n\n## A server to host your online studies on.\n\n</div>\n\n<p align=\"center\">\n<a href=\"https://github.com/psf/black/blob/main/LICENSE\"><img alt=\"License: MIT\" src=\"https://black.readthedocs.io/en/stable/_static/license.svg\"></a>\n<a href=\"https://pypi.org/project/black/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/black\"></a>\n<a href=\"https://github.com/psf/black\"><img alt=\"Code style: black\" src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n</p>\n\nPsyServer is a simple, easy to setup server on which to host online studies safely and conveniently.\nIt does not require you to commit to a certain framework, and eliminate the need to put excessive time into setting up backends and servers.\n\n## Features\n\nPsyServer uses [Filebrowser](https://filebrowser.org/) to enable easy and safe access to the study code, and study data:\n\n\n\nEvery study placed into the `studies` folder becomes accessible from the internet.\n\n\n\n\nData from the study is saved in the `studydata` folder, which is only accessible via the filebrowser and an account.\n\nBoth the studies and studydata folder can easily modified and downloaded from the online interface, eliminating the need for `putty or ssh`.\n\nFilebrowser allows for user management, making collaboration with others easy and convenient.\n\n## Setup\n\nTo setup a fully functional server to host studies on, you will require following things:\n\n1. A host machine to run the server on\n2. Installing PsyServer\n3. Get a domain (optional)\n4. Setup HTTPS (optional)\n5. Run the Server\n\n### Host machine\n\nA host machine to run the server on will be required. It is highly recommended it is a linux machine.\nFor example, you can set up an [aws ec2 instance](https://aws.amazon.com/ec2/) for little cost.\n\n### PsyServer Setup\n\nPsyServer itself comes as a python package and is installed as such.\nAt least python 3.11 is required; it is recommended to use a [virtual environment](https://docs.python.org/3/library/venv.html). Here, we use [conda](https://conda.io/projects/conda/en/latest/user-guide/getting-started.html) ([miniconda installation guide](https://docs.conda.io/projects/miniconda/en/latest/)).\nFor easy access of files, you need to install [filebrowser] in addition.\n\n```sh\n# 1. create psyserver folder\nmkdir psyserver\ncd psyserver\n\n# 2. set up conda environment (optional)\nconda create -n psyserver python=3.11\nconda activate psyserver\n\n# 3. install package\npip install psyserver\n\n# 4. install filebrowser\ncurl -fsSL https://raw.githubusercontent.com/filebrowser/get/master/get.sh | bash\n\n# 5. create example config/structure.\npsyserver init\n\n# 6. configure server (optional)\n# open psyserver.toml with your editor of choice, e.g. vim\nvim psyserver.toml\n\n# 7. run server\npsyserver run\n```\n\n### Running setup\n\nAlthough 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.\nThus it is recommended to setup PsyServer as [systemd service](https://github.com/torfsen/python-systemd-tutorial).\n\nThe `psyserver init` will create the unitfile `psyserver.service` in your directory.\nYou need to place that unitfile into a systemd subdirectory:\n\n```sh\n$ sudo mv psyserver.service /etc/systemd/system/\n$ sudo chown root:root /etc/systemd/system/psyserver.service\n$ sudo chmod 644 /etc/systemd/system/psyserver.service\n```\n\nNow reload systemctl.\n\n```sh\n$ sudo systemctl daemon-reload\n```\n\nStart the service.\n\n```sh\n$ sudo systemctl start psyserver\n```\n\nCheck on the service (leave with `Q`).\n\n```sh\n$ sudo systemctl status psyserver\n\u25cf psyserver.service - PsyServer Service.\n Loaded: loaded (/home/ubuntu/.config/systemd/user/psyserver.service; disabled; vendor preset: enabled)\n Active: active (running)\n```\n\nEnable the server for autostart.\n\n```sh\n$ sudo systemctl enable psyserver\n```\n\nFor stopping and disabling use:\n\n```sh\n$ sudo systemctl stop psyserver\n$ sudo systemctl disable psyserver\n```\n\n### Domain Name\n\nUsing a domain name is recommended, but operation is possible without. Domains can be acquired at websites such as [namecheap](https://www.namecheap.com/).\nYou will require a domain if you want to use https.\n\n### https\n\nhttps ensure safe communication between participants and your server. It is highly recommend to set up https.\nSetting up https yourself can be quite tricky, it is thus recommended to use Caddy as Reverse Proxy.\nA reverse proxy is another application running on your machine which handles the connections from the internet to a server, in this case PsyServer.\n\n1. [Install Caddy](https://caddyserver.com/docs/install#debian-ubuntu-raspbian)\n2. [Setup up the Caddy Service](https://caddyserver.com/docs/running#using-the-service)\n3. [Setup Caddy as reverse Proxy](https://caddyserver.com/docs/quick-starts/reverse-proxy)\n\nUse this Caddyfile with the default configuration of PsyServer.\n\n```Caddyfile\nexample.com\n{\n reverse_proxy :5000\n}\n\nadmin.example.com\n{\n reverse_proxy :5050\n}\n```\n\nReplace `example.com` with your `domain`.\n\nReload Caddy `sudo systemctl reload caddy`.\n\nThat's it!\n\nYou can also setup uvicorn directly to handle https ([uvicorn https documentation](https://www.uvicorn.org/deployment/#running-with-https)). Settings are set in `psyserver.toml` under `[uvicorn]` with exactly the same keys as the documentation, without the `--`.\n\n## Configuration\n\n`psyserver.toml` configures the server.\nThis file has to be in the directory from which `psyserver run` is called.\n\nThe configuration has two groups:\n\n1. psyserver: all PsyServer configuratons\n2. uvicorn: Uvicorn configurations\n\n### psyserver config\n\n```toml\n[psyserver]\nstudies_dir = \"studies\"\ndata_dir = \"data\"\nredirect_url = \"https://www.example.com\"\n```\n\n- `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.html` will have the url `<host>:<port>/exp_cute/index.html`.\n- `data_dir`: directory in which study data is saved. E.g. data submissions to the url `<host>:<port>/exp_cute/save` will be saved in `<data_dir>/exp_cute/`. Has to be different from `studies_dir`.\n- `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.\n\n### uvicorn config\n\n```toml\n[uvicorn]\nhost = \"127.0.0.1\"\nport = 5000\n```\n\nHere configures the uvicorn instance runnning the server. For example, uou can specify the `host`, `port` and https configurations.\nFor all possible options, use the commands in the [uvicorn settings documentation](https://www.uvicorn.org/settings/) without `--`.\n\n## How to save data to psyserver\n\nTo save participant data to the server it has to be sent in the json format of a POST request.\nThe POST request can be made to `/<study>/save` which saves data as a json file.\nUpon succesful saving, a json object `{success: true}` is returned.\nProvide the `participantID` key such that the saved data will be named with the participantID.\n\n```js\n// example data\nparticipant_data = {\n participantID: \"debug_1\",\n condition: \"1\",\n experiment1: [2, 59, 121, 256],\n // ...\n};\n// post data to server\n$.ajax({\n url: \"/exp_cute/save\",\n type: \"POST\",\n data: JSON.stringify(participant_data),\n contentType: \"application/json\",\n success: () => {\n console.log(\"Saving successful\");\n // success function\n },\n}).fail(() => {\n console.log(\"ERROR with $.post()\");\n});\n```\n\n**Note that you need to call `JSON.stringify` on your data**. Without this, you will get an `unprocessable entity` error.\n\n## Development\n\n### Setup\n\n```sh\n# 1. set up conda environment\n$ conda create -n psyserver python=3.11\n$ conda activate psyserver\n\n# 2. clone\n$ git clone git@github.com:GabrielKP/psyserver.git\n$ cd psyserver\n\n# 3. install in editor mode\n$ pip install -e .\n```\n\n### Testing\n\n```sh\n# normal test\n$ pytest . -v\n\n# coverage\n$ coverage run -m pytest\n# html report\n$ coverage html\n```\n\n### Publishing\n\n```sh\n$ flit publish\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A server to host your online studies on.",
"version": "0.5.1",
"project_urls": {
"Home": "https://github.com/GabrielKP/psyserver"
},
"split_keywords": [
"experiments",
" studies",
" behavioral",
" online",
" server"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "73c4dc30c20178640079cbc51de34ef7a30056b8ee0567ecef90e319822c7c7d",
"md5": "6cf0e650928bf8959184bc9630661d22",
"sha256": "1748b76325a0a6130c6bdc80c37fa7e6acb3645f7fd70b1a7aacf3fbc4bf9cb6"
},
"downloads": -1,
"filename": "psyserver-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6cf0e650928bf8959184bc9630661d22",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.11",
"size": 12918737,
"upload_time": "2024-03-31T19:23:54",
"upload_time_iso_8601": "2024-03-31T19:23:54.461337Z",
"url": "https://files.pythonhosted.org/packages/73/c4/dc30c20178640079cbc51de34ef7a30056b8ee0567ecef90e319822c7c7d/psyserver-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bd192540699ed3f7404706190ea6b9fec142a91eb2b765a20604a9dd2586594f",
"md5": "a60f88f1c04a870e34ff2258062c7d28",
"sha256": "154a0f002941308d0ce6940be967d97b15438123e5da826f3e672bef35ab3a11"
},
"downloads": -1,
"filename": "psyserver-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "a60f88f1c04a870e34ff2258062c7d28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.11",
"size": 13109454,
"upload_time": "2024-03-31T19:24:03",
"upload_time_iso_8601": "2024-03-31T19:24:03.208601Z",
"url": "https://files.pythonhosted.org/packages/bd/19/2540699ed3f7404706190ea6b9fec142a91eb2b765a20604a9dd2586594f/psyserver-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-31 19:24:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GabrielKP",
"github_project": "psyserver",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "psyserver"
}
JSON
