Installation through docker - KL-Psychological-Methodology/ESMira GitHub Wiki

Installation through Docker

[!NOTE] Internally, the docker container is an Apache server that runs PHP and has already downloaded the according ESMira files.

In case Docker is not already installed on your system, follow these instructions: https://docs.docker.com/engine/install/

This tutorial assumes that you want to install ESMira to ./esmira/. Replace ./esmira/ with the path to your desired directory.

Step 1: Install ESMira

Create a new directory and move there:

mkdir ./esmira
cd ./esmira

Download the docker compose file into ./esmira/:

wget https://raw.githubusercontent.com/KL-Psychological-Methodology/ESMira-web/refs/heads/main/docker-compose.yml

If you want to use ESMira on an ARM based machine (e.g., a Raspberry Pi or other single board computer), you need to edit the docker-compose.yml file accordingly and change platform: linux/amd64 to platform: linux/arm64.

Step 2: Set up a TLS certificate (if needed)

Your server will need a TLS certificate to be reachable through https:// (in contrast to http://), which requires a domain name. Otherwise, the smartphone apps will not be able to connect to your server.

[!NOTE] If a domain (including TLS) is already set up for your server, then you can skip Step 2 altogether and continue with Step 3.

[!NOTE] The DNS entries for your domain must be set up and lead to your server's IP address. You also need to make sure that your server is reachable over the internet and port 443 is open.

Depending on your setup, if the Docker container can be accessed directly from the internet, and you want to install the certificate inside the Docker container, continue with Alternative A. Or, if Docker is configured to be accessed via a reverse proxy, you should continue with Alternative B.

Alternative A: Install the certificate for a reverse proxy

[!CAUTION] The default docker-compose.yml is using port 80 by default. Port 80 will most likely already be used by your reverse proxy. So you need to change the external (/left) port number in docker-compose-yml to something else. Also, since your reverse proxy instead of the ESMira container is handling TLS, you can remove the port 443 in docker-compose.yml.

[!NOTE] This tutorial is assuming that you are using LetsEncrypt with Certbot and Nginx as a reverse proxy. For any other server configuration please open an issue, and we will try to figure it out together.

Acquire a certificate from LetsEncrypt

(Replace [DOMAIN-NAME] with your domain name):

certbot certonly --nginx -d [DOMAIN-NAME]

Create a new configuration file in /etc/nginx/sites-enabled/esmira.conf

(Replace [DOMAIN-NAME] with your domain name and [PORT] with the external port number set in docker-compose.yml):

server {
    server_name [DOMAIN-NAME];
    listen 443;
    listen [::]:443;

    location / {
        proxy_set_header HOST $host;
        proxy_set_header X-Forwarded-Proto https;
        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;
        proxy_pass http://127.0.0.1:[PORT];
    }
    
    ssl_certificate /etc/letsencrypt/live/[DOMAIN-NAME]/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/[DOMAIN-NAME]/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}
server {
    server_name [DOMAIN-NAME];
    listen 80;
    listen [::]:80;

    return 301 https://$host$request_uri;
}

Restart nginx:

service nginx restart

Alternative B: Install the certificate inside the container

Create a new file in ./esmira/sites-enabled/apache-ssl.conf

(Replace [DOMAIN-NAME] with your domain name and [YOUR-EMAIL] with your email address):

# Used to send notifications if the renewal automation breaks
ServerAdmin [YOUR-EMAIL]

# The primary domain name of the certificate.
MDomain [DOMAIN-NAME] auto

# This is your consent to Let's Encrypt's terms and conditions which is required.
MDCertificateAgreement accepted

# Always redirect to HTTPS
MDRequireHttps permanent

# Enable HTTP/2 in addition to regular HTTP and the TLS-based ACME server identity verification protocol.
Protocols h2 http/1.1 acme-tls/1

<VirtualHost *:443>
    ServerName [DOMAIN-NAME]
    DocumentRoot /var/www/html
    SSLEngine on
</VirtualHost>

Step 3: Run the container

When everything else is set up, run the following command in ./esmira/:

docker compose up -d

Almost done!

Your server has been installed. Now, you need to set up your admin account. Continue at Complete the setup.