Dear OTree devs,
I'm trying to follow the installation instructions provided [here](https://otree.readthedocs.io/en/latest/server/ubuntu.html#) to set up my own instance of OTree. 

I followed the instructions there up to [here](https://otree.readthedocs.io/en/latest/server/ubuntu.html#reset-the-database-on-the-server) excluded, then I jumped [here](https://www.otree.org/) (section "Getting started") as I figured out I didn't have any requirements.txt to install...(maybe consider adding this specification to the installation instructions)

From there I run the commands to create a new project (I choose to include example games), and then, before starting the devserver, I went back [here](https://otree.readthedocs.io/en/latest/server/ubuntu.html#reset-the-database-on-the-server) to install the dependencies and reset the db.

Then I got stuck: as I give command `otree resetdb` I get an exception dump (I'm on the command line on Ubuntu) that terminates with the following

`` 
sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) connection to server at "localhost" (127.0.0.1), port 5432 failed: fe_sendauth: no password supplied
``

can you help me understand what is the problem? I guess I need a way to give the password to the Postgres DB as an argument to the `resetdb` script?

I assume that you have installed PostgreSQL, and it seems that you have installed psycopg2 (psycopg2-binary). As the error message indicates, you are missing a password in at least one place.

(And I agree that the installation instructions on https://otree.readthedocs.io/en/latest/server/ubuntu.html could be improved.)

Have you done the following?

(1) Change user to the postgres user, so that you can execute some commands:

sudo su - postgres

(2) Then start the PostgreSQL shell:

psql

(3) Once you’re in the PostgreSQL shell, create a database and user:

CREATE DATABASE django_db;
alter user postgres password 'password';

(Instead of 'password', you can choose something else, say 'StefanoM'.)

(4) Exit the SQL prompt:

\q

(5) Return from the postgres user to your regular command prompt:

exit

(6) Then add the following lines to your .bashrc/.profile (preferably at the end, so it is easy to locate them):

#export PATH=~/.local/bin:$PATH
export DATABASE_URL=postgres://postgres:password@localhost/django_db
# If you chose your password to be 'StefanoM' in Step 3:
# export DATABASE_URL=postgres://postgres:StefanoM@localhost/django_db
export OTREE_ADMIN_PASSWORD=Choose-a-password-of-your-liking
export OTREE_PRODUCTION=1
export OTREE_AUTH_LEVEL=STUDY
export REDIS_URL="redis://"

You can do so, for instance, via

nano ~/.bashrc

(If you use nano, hit [ctrl] + [o] for saving the changes and [ctrl] + [x] for quitting nano.)

Alternatively, you can also set some variables in your settings.py file:

AUTH_LEVEL = "STUDY"
ADMIN_PASSWORD = "Choose-a-password-of-your-liking"
DEBUG = 0

This, however, will make it more difficult to run the code without changes locally for debugging and on the server.

(7) To start oTree, cd to your project folder and enter

otree runprodserver

(Use `screen -S oTree -d -m otree prodserver` to keep oTree running in the background. Access the detached screen via `screen -r`.)

(8) You should then be able to access your oTree instance by opening http://ip-address.of.your.server:8000 in a browser.

Dear BonnEconLab, 
many thanks for your prompt reply. 

I think I got, after many tries, as somehow I "broke" the devserver.

Without bothering you with the technical details, it is correct that the only difference I see between devserver and prodserver, is that under the tab "Server check" the devserver uses SQLite instead of Postgre?

All other things are the same (e.g. same username and password)

I guess so (as it depends on my won configuration), but I want to check to be sure.

If you need additional details just ask.

`otree prodserver` does not use PostgreSQL automatically but only if you set it up as described above. Otherwise, `otree prodserver` will also use SQLite.

The difference between `otree devserver` and `otree prodserver`, at least on my Mac, is that with `otree devserver`, I can only access oTree via http://localhost:8000. If I want to access oTree from other computers, I have to use `otree prodserver`. Additional differences are better explained by Chris_oTree.

Dear @BonnEconLab many thanks for the clarification. 

Could you elaborate more on the sentence "Additional differences are better explained by Chris_oTree": where?

I'm also wondering whether I can bind the dev server and/or the prod server to a different IP address, but I'm not finding instructions about how to do it...is this the right place to ask?

Or is it better to ask in the Github repo issues sections?

@Stefano_Mariani asked:

> Could you elaborate more on the sentence "Additional differences are better explained by Chris_oTree": where?

Ah, I meant, “I can’t really explain what the additional differences are; they would be better explained by Chris_oTree.”

@Stefano_Mariani asked:

> I'm also wondering whether I can bind the dev server and/or the prod server to a different IP address, but I'm not finding instructions about how to do it...is this the right place to ask?

I don’t really understand what you mean by binding to “a different IP address.” Different from what — from the IP address of your server? Do you mean that your server can be reached via two different IP addresses?

You can set up nginx as a reverse proxy to forward any traffic that arrives at a certain port (80 for HTTP, even better 443 for HTTPS) or at a certain IP address to oTree. Let me know if this is what you intend to do, and I can share the nginx configuration of our oTree servers. (https://github.com/trr266/otree_docker/blob/main/otree5_nginx_site.conf may also help.)

I would like to deploy also the devserver instance not in localhost, but on the public IP address of my server, that I can access via ssh in VPN...is that possible?

Yes, sure, that is possible. If you use `otree prodserver` rather than `otree devserver`, you can access your oTree experiment via http://your.ip.address:8000.

(This, of course, requires your computer’s and/or your department’s firewall to allow the respective connection between your computers. For instance, in my office, running `otree prodserver` is all I need to do, no matter whether I run oTree on a Windows, Mac or Linux machine, as long as the computers are connected to the university’s LAN. This does not work in the WiFi.)

Again, if you want to do without including the port in the URL (:8000), then you have to configure nginx so that it forwards ports 80 and 443 to 8000 (assuming you are running oTree on port 8000, which is the default).

Many thanks for your replies, I partially got OTree working by using nginx, but I still have some malfunctioning...

In the attempt to fix this myself, is this reference still valid? https://otree-server-setup.readthedocs.io/en/latest/index.html 

It seems kind obsolete, but maybe it is still valid?

I haven’t gone through https://otree-server-setup.readthedocs.io/en/latest/index.html in detail, but at first glance, it looks still up to date to me (except, of course, the Python versions).

It is a bit unclear what you mean by having gotten oTree *partially* working using nginx.

Let us, for the time being, restrict ourselves to the simplest possible case. That is, we will *not* use PostgreSQL, and we will not use SSL/HTTPS yet. That is, the objective is, as a first step, nothing more than being able to access oTree without reference to port 8000. In other words, we want to access it via http://localhost and http://your.IP.address instead of http://localohost:8000 and http://your.IP.address:8000.

I just set up a completely blank Ubuntu 24.04 (virtual) machine and then executed the following steps:


Step 1
------

a) Apply all available updates:

`sudo apt update`
`sudo apt upgrade`
`sudo apt dist-upgrade`

b) Install pip:

`sudo apt install -y python3-pip`


Step 2
------

Install nginx:

`sudo apt install nginx -y`


Step 3 (optional)
-----------------

Enable the nginx web server to start automatically at boot time:

`sudo systemctl enable nginx`


Step 4
------

Start the nginx service:

`sudo systemctl start nginx`


Step 5
------

Check that nginx is running by opening http://localhost in a browser on the same machine or http://your.IP.address on another computer. (The latter requires that your firewall permits access to the machine that runs nginx via the HTTP port 80.)


Step 6 (optional)
-----------------

It is not required but helpful to keep oTree installations separate for different projects by installing oTree in a separate virtual environment for each project. To be able to do so, install python3.12-venv:

`sudo apt install python3-venv`

Then create a virtual environment via

`mkdir ~/venv`
`python3 -m venv ~/venv/oTree-test`

Activate that virtual environment via

`source ~/venv/oTree-test/bin/activate`

(You leave the virtual environment via `deactivate`.)


Step 7
------

Install oTree via

`pip install --upgrade otree`


Step 8
------

Create a test project via

`otree startproject sample-games`


Step 9
------

Run oTree via

`cd sample-games`

and

`otree devserver`

or

`otree prodserver` (if you would like to test access from a different computer)

Check that oTree is running by opening http://localhost:8000 in a browser on the same machine or http://your.IP.address:8000 on another computer (the latter requires running `otree prodserver`).


Step 10
-------

Change the file /etc/nginx/sites-available/default as follows:

Add the following lines:

map $http_upgrade $connection_upgrade { # Some variables for configuring the protocol switch
    default upgrade;
    ''      close;
}

before the section

server {
        listen 80 default_server;
        listen [::]:80 default_server;

In the subsection

        location / {

remove/disable the line

                try_files $uri $uri/ =404;

and add the lines

                proxy_pass http://127.0.0.1:8000;
                proxy_http_version 1.1;  # protocol switch needed
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                proxy_set_header HOST $host;


Step 11
-------

Restart nginx via `sudo service nginx restart`.


Step 12
-------

The running oTree instance should then be accessible via http://localhost and http://your.IP.address, that is, via the standard HTML port 80 instead of port 8000, which is used by oTree.

This is because we have instructed nginx to redirect the traffic from port 80 to 8000.


If this setup works, we can build on it and enable SSL/HTTPS in the next step, if desired.

Dear **BonnEconLab**, 
first of all many thanks for taking your time in giving a detailed response, even after confirming that the tutorial I posted was more or less fine :)

With "partially" I meant that I had some issues with some specific pages, that were redirected to server.ip.address:8000 instead of simply server.ip.address, given by (I guess) my misconfiguration of nginx, both in redirection and in web socket upgrade.

Now it is working fine (no https, no VPN) apparently (I can click on all the pages and create new sessions), the only thing that seems odd to me is that the server is in debug mode but no debug info is printed at the bottom of pages (as the text on server check" page seems to suggest...)

My next step would be to activate HTTPS (I never worked with certificates before), and put the service behind VPN (dunno where to start, but I think I will need cooperation from my University ICT office)

You wrote,

> With "partially" I meant that I had some issues with some specific pages, that were redirected to server.ip.address:8000 instead of simply server.ip.address, given by (I guess) my misconfiguration of nginx, both in redirection and in web socket upgrade.

Yes, I observe the same thing if I only include

                proxy_pass http://127.0.0.1:8000;

in the nginx configuration: as soon as a link on the oTree “demo” creates a new session, the :8000 is appended. You definitely want to avoid this because many firewalls block that port.

This is why you need the additional lines

                proxy_http_version 1.1;  # protocol switch needed
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;
                proxy_set_header HOST $host;

@Stefano_Mariani wrote:

> My next step would be to activate HTTPS (I never worked with certificates before)


Then let’s do that:


Step 13
-------

To enable SSL/HTTPS, install Certbot from Let’s Encrypt:

`sudo apt install certbot python3-certbot-nginx`



Step 14
-------

Request an SSL certificate from Let’s Encrypt:

`sudo certbot certonly --nginx`

You will have to enter your domain name. An IP address won’t do. This requires that your machine has an entry in a domain name server (DNS). If that is not the case, ask your IT department to generate a DNS entry for your machine’s IP address.

Let’s assume that you enter your-hostname.subdomain.example.org.

If successful, Let’s Encrypt will respond with

Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/your-hostname.subdomain.example.org/fullchain.pem
Key is saved at:         /etc/letsencrypt/live/your-hostname.subdomain.example.org/privkey.pem

These two locations will have to be added to the nginx configuration.


Step 15
-------

In /etc/nginx/sites-available/default, change

server {
        listen 80 default_server;
        listen [::]:80 default_server;

to

server {
        listen 80;
        listen [::]:80;
        return 301 https://$host$request_uri;
}

server {
        listen 443 ssl default_server;
        listen [::]:443 ssl default_server;

That is, you have two `server` sections now.

The first one tells nginx to redirect any HTTP traffic to HTTPS so that no experimenter and no participant can (accidentally) use an unencrypted connection. The second entry tells nginx to forward all HTTPS traffic to port 8000, that is, the port used by oTree (by default).


Step 16
-------

To the second section

server {
        listen 443 ssl default_server;

add

        ssl_certificate /etc/letsencrypt/live/econ-055.iaas.uni-bonn.de/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/econ-055.iaas.uni-bonn.de/privkey.pem;


Step 17
-------

Restart nginx via

`sudo service nginx restart`


Step 18
-------

You should now be able to access a running oTree instance via https://your-hostname.subdomain.example.org (with http://your-hostname.subdomain.example.org automatically being upgraded to https://your-hostname.subdomain.example.org).


For completeness
----------------

The entire /etc/nginx/sites-available/default file:


map $http_upgrade $connection_upgrade { # Some variables for configuring the protocol switch
        default upgrade;
        ''      close;
}

server {
        listen 80;
        listen [::]:80;
        return 301 https://$host$request_uri;
}

server {
        listen 80 default_server;
        listen [::]:80 default_server;
        listen 443 ssl default_server;
        listen [::]:443 ssl default_server;

        ssl_certificate /etc/letsencrypt/live/your-hostname.subdomain.example.org/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/your-hostname.subdomain.example.org/privkey.pem;

        server_name _;

        location / {
                proxy_pass http://127.0.0.1:8000;
                proxy_http_version 1.1;  # protocol switch needed
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection $connection_upgrade;  # end of the configuration for oTree
                proxy_set_header Host $host;
        }
}

This works in the VM that I’m using as my testbed, even without the five additional lines

                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header X-Forwarded-Port $server_port;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Host $server_name;

that you find on https://otree-server-setup.readthedocs.io/en/latest/step5.html.

I do not have enough knowledge of nginx to be able to tell whether these lines are necessary and what which types of communication they handle.


One caveat:

As it happens, I just realized that (no matter whether I included these additional lines or not), I cannot use the “split screen mode” after enabling HTTPS. The reason is that the HTML code generated by oTree for the split screen mode includes

<iframe src="http://...">

instead of

<iframe src="https://...">

That is only a minor inconvenience, though, I think. Opening participants’ URLs in separate browser tabs/windows works flawlessly.

To turn off the debug mode, you can add

DEBUG = 0

to your settings.py file. (A better idea is including the line `export OTREE_PRODUCTION=1` in ~/.bashrc, since this allows you to work on your code locally without having to change settings.py so that it states DEBUG = 1.)

To enable password protection of the admin interface, set

AUTH_LEVEL = "STUDY"

in settings.py (or include `export OTREE_AUTH_LEVEL="STUDY"` in ~/.bashrc).