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 does not 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

To add nginx yum repository, 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 configuration below 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-Scheme    $scheme;
      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 TLSv1.1 TLSv1.2;
    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;
      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

If SELinux is enabled and NGINX does not work you might need to change SELinux to be more permissive by entering:

$ setenforce permissive

 To make this permanent edit: /etc/sysconfig/selinux and change line:

SELINUX=enforcing

to

SELINUX=permissive

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;