Configuring a proxy (NGINX)

When configuring PageSeeder on Linux, if a website port less than 1024 (e.g. 80 or 443 for SSL) is chosen, then a reverse proxy from this port to the API port (e.g. 8282) needs to be configured. This is because the PageSeeder service is not running as the root user so doesn’t have permission to use these lower port numbers.

We recommend using NGINX as a reverse proxy as it is open source and straightforward to configure. Following are instructions on how to do this.

Install NGINX

Try entering:

$ yum install nginx

If this doesn't work add the nginx yum repository as follows: create a file named /etc/yum.repos.d/nginx.repo and paste the following configuration for CentOS or something similar for the operating system.

CentOS:

[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=0
enabled=1

Then enter:

$ yum install nginx

Configure NGINX

Backup the original nginx.config:

$ mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.orig

Create a new file /etc/nginx/nginx.conf and paste the following configuration for non-SSL or SSL into it. Substitute your domain name for myserver.mycompany.com, your website port for 80 and your API port for 8282. If using SSL, see Configuring SSL. To bind PageSeeder to a single IP address, substitute 80 or 443 with [your ip]:80 or [your ip]:443.
Non-SSL:

user nginx;

events {
    worker_connections  1024;
}

http {
  include       /etc/nginx/mime.types;
  server {
    listen               80;
    server_name          myserver.mycompany.com;    
    client_max_body_size 1000m;
    location / {
      proxy_pass                         http://localhost:8282;
      proxy_set_header Host              $host;
      proxy_set_header X-Real-IP         $remote_addr;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host  $host:$server_port;
      proxy_set_header Upgrade           $http_upgrade;
      proxy_set_header Connection        $http_connection;
      proxy_http_version 1.1;
      proxy_read_timeout                 300s;
    }
    error_page 502 =503  /ps/maintenance/maintenance.html;
    location /ps/maintenance/ {
      root               /var/www;
    }
  }
}

SSL:

user nginx;

events {
  worker_connections  1024;
}

http {
  include       /etc/nginx/mime.types;
  server {
    listen               443 ssl;
    server_name          myserver.mycompany.com;
    client_max_body_size 1000m;
    ssl_certificate      /etc/nginx/ssl/pageseeder/mydomain.crt;
    ssl_certificate_key  /etc/nginx/ssl/pageseeder/mydomain.key;
    ssl_session_cache    shared:SSL:10m;
    ssl_session_timeout  10m;
    ssl_protocols        TLSv1.2 TLSv1.3;
    location / {
      proxy_pass                         http://localhost:8282;
      proxy_set_header Host              $host;
      proxy_set_header X-Real-IP         $remote_addr;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_set_header X-Forwarded-Host  $host:$server_port;
      proxy_set_header Upgrade           $http_upgrade;
      proxy_set_header Connection        $http_connection;
      proxy_http_version 1.1; 
      proxy_cookie_path /ps              "/ps; Secure";
      proxy_read_timeout                 300s;
    }
    error_page 502 =503  /ps/maintenance/maintenance.html;
    location /ps/maintenance/ {
      root               /var/www;
    }
  }
  server {
    listen                80;
    return 301            https://$host$request_uri;
  }
}

Copy the PageSeeder maintenance page to NGINX as follows:

$ mkdir -p /var/www/ps
$ cp -r /opt/pageseeder/webapp/maintenance /var/www/ps/

Start NGINX and make it start automatically at reboot.
On CentOS 6:

$ service nginx start
$ chkconfig --add nginx

On CentOS 7:

$ systemctl start nginx
$ systemctl enable nginx

Troubleshooting

SELinux

To see if SELinux is enabled, enter the following:

$ sestatus

If Current mode: enforcing is displayed and NGINX returns a 403 Forbiddenerror you might need to allow port 8282 and directory /var/www/ps in SELinux by entering:

$ setsebool -P httpd_can_network_relay on
$ semanage port -a -t http_port_t -p tcp 8282
$ semanage fcontext -a -t httpd_sys_content_t '/var/www/ps(/.*)?'
$ restorecon -Rv /var/www/ps

If the semanage command is not found it can be installed by entering:

$ yum install -y policycoreutils-python-utils

If this doesn’t fix the problem you can temporarily change SELinux to be more permissive by entering:

$ setenforce permissive

 But after finding the correct SELinux settings you should set the mode to enforce by entering:

$ setenforce enforcing

Permanent changes to the mode can be made by editing /etc/selinux/config but this is not recommended.

Timeout errors

If 504 Gateway timeout errors are received from NGINX, try increasing the time for PageSeeder responses to 5 minutes by adding the following under server {:

proxy_read_timeout  300s;