Run Pyramid under a web path instead of the root

Background

Running Pyramid from a path is sometimes required (e.g., https://mysite.com/pyramid) instead of the root (e.g. https://mysite.com). In embedding scenarios, this allows Pyramid to run under the same web domain instead of a subdomain - facilitating easier integrations and simplified authentication/security operations.

Prerequisites

• This applies only to Pyramid 2023.16.083 / 2024.01.013 and later.
• Earlier versions do not support this feature.

1. Configuring Pyramid to Use a Virtual Directory

1. Log in to Pyramid Admin.
2. Navigate to:
   Services → Web Services → Web Settings.
3. Enable "Deploy via Virtual Directory".
4. Set your desired virtual directory/path name, e.g., /pyramid.
5. Click Apply and restart all Pyramid web servers.

   

    Now, users can access Pyramid at:

http://localhost:8181/pyramid

Important Notes:

Pyramid may still be accessible at the root (/) by default. This is because Pyramid assumes that a load balancer or reverse proxy will manage access to /pyramid. If you only want users to access Pyramid at /pyramid, configure your load balancer accordingly and block access.

---

The next sections explain how to facilitate the virtual path for Pyramid using various load balancing / reverse proxy technologies.

---

2. Configuring AWS Load Balancer to Serve Pyramid Under /pyramid

(Assumes you already have an AWS Load Balancer set up. If not, see this guide for setup instructions.)

Steps:

1. Go to AWS Console → EC2 → Load Balancers.
2. Select the Load Balancer that will serve Pyramid.
3. Click "Add Rule".

Rule Configuration:

• Name: pyramid
• Condition Type: Path
• Path: /pyramid* ( use the path you setup for the virtual directory in the Pyramid admin)
• Action: Forward to target group
• Target Group: Choose the group that points to your Pyramid web servers (port 8181).

Setting Rule Priority

• The rule must have a lower number (higher priority) than any rule that routes traffic to /.
• Example: If there is a rule for / that sends traffic to another website, your /pyramid rule should have a lower number than that rule.
• This ensures /pyramid traffic is forwarded correctly and doesn't get overridden.

Example Rule Evaluation Order:

Now, users browsing to /pyramid will be forwarded to Pyramid before the root rule is applied.

---

3. Configuring IIS to Serve Pyramid Under to Serve Pyramid Under /pyramid

Step 1: Open IIS Manager

1. Open IIS Manager (inetmgr from the Run dialog).
2. In the Connections panel, click on your site (e.g., Default Web Site).

Step 2: Configure URL Rewrite Rules

1. Double-click "URL Rewrite" in the middle panel.
2. Click "Add Rules…" in the right panel.
3. Select "Blank Rule" under Inbound Rules and click OK.

Step 2.1: Create Rewrite Rule for /pyramid

1. Enter "Rewrite Pyramid Path" as the rule name.
2. Under Conditions, click "Match URL":
   • Set Requested URL to Matches the Pattern
   • Use the Regular Expressions option.
   • In the Pattern field, enter:

     ^pyramid(/.*)?$

3. Scroll to Action and set:
   • Action Type: Rewrite
   • Rewrite URL:

     http://localhost:8181/pyramid{R:1}

   • Append Query String: Yes
   • Stop Processing of Subsequent Rules: Yes
4. Click Apply in the right panel.

Step 3: Restart IIS and Test

1. Click Restart on the right panel under Manage Server.
2. Open a browser and visit:

   http://yourserver/pyramid

   It should correctly forward to http://localhost:8181/pyramid.
   
   Access the main site at:

   http://yourserver/

   Any request that is not for /pyramid will automatically be handled by the main site, so no additional rules are needed

Now, Pyramid should be accessible at /pyramid via IIS. 

When browsing to the main site i.e mysite.com you will get the site

3. Configuring Nginx to Serve Pyramid Under /pyramid

This process is identical to the one described here; however, in step 3, use the below configuration instead

 

server {
  listen 443 ssl;
    ssl_certificate /etc/nginx/certs/chain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    server_name yourServername.mycompany.com;
    access_log /var/log/nginx/nginx.vhost.access.log;
    error_log /var/log/nginx/nginx.vhost.error.log;
    client_max_body_size 300M;
    location / {
proxy_pass http://localhost:8181/pyramid;
    }
location /events {
proxy_pass http://localhost:8181/pyramid/events;
                proxy_http_version 1.1;
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "upgrade";
        }
}