Behind a reverse proxy

If you want multiple web services, including one or more Apleno Server instances, on the same server, you will need a reverse proxy.

Info

This guide covers two common setups: Traefik with Docker, and NGINX.

Using Traefik with Docker

If your server already runs Traefik, its Docker provider can automatically discover the Apleno Server container and route a domain to it. This method handles the generation and renewal of the HTTPS certificate with Let's Encrypt for you.

This assumes a running Traefik instance with a websecure entrypoint, a certificate resolver named letsencrypt, and a shared external network:

# docker network create traefik

Add the following to the Apleno Server service described on the Docker installation page:

services:
  apleno:
    image: pgmsolutions/apleno:latest
    environment:
      ROOT: https://apleno.example.com
      TRUSTED_PROXIES: "1"
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.apleno.rule=Host(`apleno.example.com`)"
      - "traefik.http.routers.apleno.entrypoints=websecure"
      - "traefik.http.routers.apleno.tls.certresolver=letsencrypt"
      - "traefik.http.services.apleno.loadbalancer.server.port=8080"
    networks:
      - traefik

networks:
  traefik:
    external: true

Note that the service has no ports: section: Traefik reaches the container over the shared network. Publishing port 8080 on the host would leave Apleno Server directly reachable over plain HTTP, bypassing Traefik and its TLS.

Note

TRUSTED_PROXIES must be set for Apleno Server to see the real visitor's IP address. The default (loopback) only trusts a proxy running on the same host, which is not the case here since Traefik runs in its own container. Setting it to 1 trusts one proxy hop; you can also give the Docker network in CIDR notation. See the configuration file page.

Since Traefik terminates TLS, Apleno Server itself stays in plain HTTP: leave HTTPS to false (the default). WebSocket connections, used by running apps, are forwarded by Traefik without any extra configuration.

Using NGINX

The instructions below assume a Debian or Ubuntu distribution, under a root session.

Installation

The first step is to install NGINX:

# apt-get install nginx

Then create a new site configuration by copying the default site, and enable it by creating a symbolic link in site-enabled:

# cp /etc/nginx/sites-available/default /etc/nginx/sites-available/apleno
# ln -s /etc/nginx/sites-available/apleno /etc/nginx/sites-enabled

Disable the default site and restart NGINX:

# rm /etc/nginx/sites-enabled/default
# systemctl restart nginx

Configuration

Here is an example site file, like /etc/nginx/sites-available/apleno. We will set the Apleno Server to listen on the port 8080.

server {
    listen 80 default_server;
    client_max_body_size 10G;
    server_name apleno.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Connection "upgrade";
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 20d;
        proxy_send_timeout 20d;
    }
}

default_server is the default site used when no server_name matches a configuration. Only one server block should have it per port.

Note

The X-Forwarded-For and X-Forwarded-Proto headers let Apleno Server see the real visitor's IP address instead of NGINX's. By default Apleno Server only trusts this header from a proxy running on the same host (the trustedProxies setting, loopback by default), exactly this setup. If NGINX runs on a different host, adjust trustedProxies accordingly, see the configuration file page.

Configuring Apleno

Don't forget to make Apleno Server listen on port 8080, or whatever port you choose in the NGINX file. To do this, edit your .env file and set the port and root settings:

PORT=8080
ROOT=http://apleno.example.com

You can find more information about configuration in the specific section.

HTTPS

The trick to use HTTPS behind a proxy with NGINX is to handle the SSL connection in NGINX, then forward it to Apleno Server over normal HTTP. The first server block will redirect any non-HTTPS request to its secure URL. The other server block is for the HTTPS website itself.

server {
    listen 80;
    if ($host = apleno.example.com) {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    client_max_body_size 10G;
    server_name apleno.example.com;
    ssl_certificate /etc/letsencrypt/live/apleno.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/apleno.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Connection "upgrade";
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 20d;
        proxy_send_timeout 20d;
    }
}

Since NGINX is the one terminating TLS here, Apleno Server itself should stay in plain HTTP: set HTTPS to false (this is also the default, so the line can simply be omitted):

# Web Server port
PORT=8080
ROOT=https://apleno.example.com

# HTTPS
HTTPS=false