Skip to main content

Reverse Proxy

It is recommended to serve FMD Server using a reverse proxy, such as Apache, Caddy, or nginx. This gives you more fine-grained control over the web server.

Therefore, please install a reverse proxy and configure it to terminate TLS and to forward traffic to FMD Server. There are various tutorials online for how to do that. This page explains the FMD Server specific configuration.

warning

FMD Server MUST be published using HTTPS. A reverse proxy with Let's Encrypt integration is the easiest way to set this up.

Examples​

The following config file samples show how to configure a reverse proxy to forward traffic to FMD Server.

Caddy​

fmd.example.com {
    reverse_proxy localhost:8080
}

Nginx​

See the nginx sample config.

The section below describes how to set up nginx as a reverse proxy for FMD Server on Debian-based systems. It is intended as a basic quickstart. Amend it to your needs.

  1. Install the required packages: sudo apt install nginx certbot python3-certbot-nginx
  2. Obtain a certificate for your domain: sudo certbot certonly --nginx -d fmd.example.com
  3. Download the nginx sample config.
    • This file references the certificates. That is why we needed to obtain the certificates first.
  4. Place the config file at /etc/nginx/sites-available/fmd.example.com and edit it to match your setup.
  5. Create a symbolic link: sudo ln -s /etc/nginx/sites-available/fmd.example.com /etc/nginx/sites-enabled/
    • Nginx only serves sites that are "enabled". It is best practice to keep configs in the list of "available" sites, and use symlinks to easily enable/disable sites.
  6. Test the configuration: sudo nginx -t
    • If this fails, analyse the issue and fix your config.
  7. Reload nginx for the new config to take effect: sudo systemctl reload nginx
    • To view the status: sudo systemctl status nginx
    • To view the nginx logs: sudo journalctl -u nginx
  8. Test that certificate renewal works: sudo certbot renew --dry-run
  9. Note: If you used the packages from apt as above, this should have created a systemd timer that takes care of renewing certificates for you.
    • sudo systemctl list-timers should show a certbot.timer
    • sudo systemctl status certbot.service should show the renewal service that is triggered by the timer.
    • If not, or on systems without systemd, you need to set up a cronjob to renew your certificates. Renewing certificates is done by invoking certbot renew.

Configure TLS​

FMD Server must be served over TLS. In particular, the web interface will only work over HTTP on localhost. On all other origins the web interface only works over HTTPS.

This is a requirement of the WebCrypto API. FMD Server's API (and hence the app) always works over HTTP - but this is highly discouraged in production.

Therefore, configure your reverse proxy to use TLS.

We recommend that you use Certbot to get a certificate from Let's Encrypt. Don't forget to create a cron job or systemd timer to regularly run Certbot to renew your certificates.

Hosting in a subdirectory​

The FMD Server binary assumes that request paths start at the root ("/"). That is, it assumes that you host FMD Server on a (sub-)domain, e.g., https://fmd.example.com.

If you host FMD Server in a subdirectory, e.g., https://example.com/fmd/, you need to configure your proxy to strip the subdirectory before forwarding the request to the backend. FMD Server does not know how to handle /fmd/api/, it only knows about /api/. Below are some examples how to do this with common reverse proxies.

Apache example:

<Location /fmd/ >
    ProxyPreserveHost On
    ProxyPass http://127.0.0.1:8080/ retry=0 timeout=30
    ProxyPassReverse http://127.0.0.1:8080/
</Location>

Nginx example:

location /fmd/ {
    proxy_pass http://127.0.0.1:8080/;
}
warning

Note the trailing slashes in the examples!

Common issues​

When uploading pictures you might see HTTP 413 errors in your proxy logs ("Content Too Large"). To fix this, increase the maximum body size, e.g to 20 MB. With nginx:

client_max_body_size 20m;

Without Reverse Proxy​

warning

This setup is not recommended and provided for your convenience only.

If you don't want to use a reverse proxy, FMD Server can terminate TLS for you. However, you need to manage (and regularly renew!) the certificates.

  1. Get a TLS certificate for your domain.

  2. Set the ServerCrt and ServerKey in the config file.

  3. In Docker: Mount the certificate and the private key into the container.

    # other lines omitted
    volumes:
        - ./server.crt:/etc/fmd-server/server.crt:ro
        - ./server.key:/etc/fmd-server/server.key:ro