Azure Subpath Forwarding with Flint

Estimated setup time: 30-90 minutes, depending on your Azure hosting setup

When someone visits yoursite.com/pages/pricing, the request is intercepted and routed to Flint's servers behind the scenes. The visitor's browser still shows your domain in the address bar - they never see a different URL. Everything else on your site (yoursite.com/about, yoursite.com/blog, etc.) continues to work normally.

Azure offers several ways to host websites. The right method for connecting Flint depends on how your site is currently hosted. Find your setup below:

Not sure which Azure service you're using? Log into the Azure Portal, click All resources, and look for your website. The resource type will tell you:

• •App Service - you're on Azure App Service (check the "Operating system" field in its Overview for Windows vs. Linux)
• •Static Web App - you're on Azure Static Web Apps (use Method 1 or 5)
• •Virtual machine - you're on an Azure VM (use Method 4)
• •Storage account (with static website enabled) - use Method 1 or 5

You'll need:

• •Your Flint subdomain (e.g., yoursite.tryflint.com) - ask the Flint team if you're unsure
• •Access to the Azure Portal (https://portal.azure.com)
• •The subpath you want to use (we'll use /pages in all examples below)

Azure Front Door is a global traffic routing service. It sits in front of your site and can route different URL paths to different servers. This method works regardless of how your site is hosted on Azure (App Service, Static Web App, VM, Storage, etc.).

Cost: ~$35/month for the Standard tier, plus small per-request and data transfer charges. For a typical marketing site, expect $35-45/month total.

Important: Azure Front Door is not available on Free Trial subscriptions. If you're on a Free Trial, you'll need to upgrade to a Pay-As-You-Go subscription first. In the Azure Portal, go to Subscriptions > your subscription > look for an Upgrade option, or search "subscriptions" in the portal search bar. Your existing free credits will carry over after upgrading.

1. 1.Log into the Azure Portal
2. 2.Click Create a resource (the "+" icon in the top left)
3. 3.Search for "Front Door and CDN profiles" and select it
4. 4.Click Create
5. 5.Choose Azure Front Door (not Classic)
6. 6.Select Custom create
7. 7.Fill in the basics:
   • -Subscription: Select your Azure subscription
   • -Resource group: Use the same one as your website, or create a new one
   • -Name: Something descriptive (e.g., yoursite-frontdoor)
   • -Tier: Select Standard
8. 8.Click Next to move to the Endpoint tab

1. 1.Click Add an endpoint
2. 2.Give it a name (e.g., yoursite-endpoint)
3. 3.Click Add

This tells Front Door where your main website lives.

1. 1.Click + Add a route
2. 2.Give the route a name (e.g., main-site)
3. 3.Under Domains, select the endpoint you just created
4. 4.Set Patterns to match to /*
5. 5.Under Origin group, click Add a new origin group:
   • -Name it main-site-origin
   • -Click + Add an origin:
   • -Name: main-site
   • -Origin type: Select Custom (or the appropriate Azure service type if your site is on App Service, etc.)
   • -Host name: Enter your current site's hostname (e.g., yoursite.azurewebsites.net for App Service, or your VM's IP/domain)
   • -Click Add to save the origin, then Add again to save the origin group
6. 6.Click Add to save the route

1. 1.In your Front Door profile, go to Origin groups in the left sidebar
2. 2.Click + Add
3. 3.Name it flint-origin
4. 4.Click + Add an origin:
   • -Name: flint
   • -Origin type: Select Custom
   • -Host name: Enter your Flint subdomain (e.g., yoursite.tryflint.com)
   • -Origin host header: Enter your Flint subdomain (e.g., yoursite.tryflint.com)
5. 5.Click Add to save the origin, then Add to save the origin group

1. 1.Go to Front Door manager in the left sidebar
2. 2.Click on your endpoint
3. 3.Click + Add a route
4. 4.Configure the route:
   • -Name: flint-pages
   • -Domains: Select your endpoint's domain
   • -Patterns to match: Enter /pages/*
   • -Origin group: Select flint-origin (the one you created in Step 4)
   • -Origin path: Leave empty
   • -Forwarding protocol: HTTPS only
5. 5.Click Add

This strips the /pages prefix before sending the request to Flint, so Flint receives the correct path.

1. 1.In your Front Door profile, go to Rule sets in the left sidebar
2. 2.Click + Add
3. 3.Name it flint-rewrite
4. 4.Click + Add a rule:
   • -Name: strip-subpath
   • -Under Conditions, click + Add condition:
   • -Select Request URL
   • -Operator: Begins with
   • -Value: /pages/
   • -Under Actions, click + Add action:
   • -Select URL rewrite
   • -Source pattern: /pages/
   • -Destination: /
   • -Preserve unmatched path: Yes
5. 5.Click Save
6. 6.Important - don't skip this: Go back to your flint-pages route, click to edit it, and associate this rule set with it. The rewrite rule won't take effect until it's linked to the route.

If your site uses a custom domain (e.g., yoursite.com rather than yoursite-endpoint.azurefd.net):

1. 1.Go to Domains in the left sidebar of your Front Door profile
2. 2.Click + Add
3. 3.Enter your domain name and follow the DNS validation steps Azure provides
4. 4.Once validated, associate the domain with your endpoint

Note: After completing the steps above, Front Door may take 5-10 minutes to propagate your route and rule changes globally. If you see 404 errors immediately after setup, wait a few minutes and try again. You can also purge the Front Door cache from Front Door manager > Purge if pages seem stuck showing old content.

1. 1.Visit yoursite.com/pages - you should see your Flint content
2. 2.Visit yoursite.com - you should see your regular site
3. 3.Check that the browser address bar still shows your domain

If your site runs on a Windows Azure App Service, you can use IIS's built-in URL Rewrite module to proxy subpath requests to Flint. No additional Azure services are needed.

Cost: No additional cost beyond your existing App Service plan.

ARR is the IIS feature that allows your App Service to forward requests to external servers. It's pre-installed but disabled by default.

1. 1.In the Azure Portal, go to your App Service
2. 2.In the left sidebar, go to Development Tools > Advanced Tools (Kudu)
3. 3.Click Go to open the Kudu console
4. 4.In Kudu, click Debug console > CMD
5. 5.Navigate to the site folder (click "site" in the folder listing)
6. 6.Click the + icon and select New file
7. 7.Name the file applicationHost.xdt
8. 8.Click the edit (pencil) icon and paste the following content:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.webServer>
    <proxy xdt:Transform="InsertIfMissing" enabled="true"
           preserveHostHeader="false"
           reverseRewriteHostInResponseHeaders="false" />
  </system.webServer>
</configuration>

9. 9.Click Save
10. 10.Restart your App Service (go back to the Azure Portal, open your App Service, and click Restart at the top)

1. 1.Back in Kudu, navigate to site/wwwroot
2. 2.Open (or create) the web.config file
3. 3.Add the following rewrite rules inside the <system.webServer> section. If you already have a <rewrite> section, merge these rules into it:

<rewrite>
  <rules>
    <rule name="FlintProxy" stopProcessing="true">
      <match url="^pages/?(.*)"/>
      <conditions>
        <add input="{HTTP_HOST}" pattern="yoursite\.com"/>
      </conditions>
      <action type="Rewrite"
              url="https://yoursite.tryflint.com/{R:1}"/>
      <serverVariables>
        <set name="HTTP_X_FORWARDED_HOST" value="{HTTP_HOST}"/>
        <set name="HTTP_X_FORWARDED_PROTO" value="https"/>
      </serverVariables>
    </rule>
  </rules>
</rewrite>

4. 4.Replace the placeholder values:
   • -yoursite\.com - your domain (note the backslash before the dot - this is required)
   • -yoursite.tryflint.com - your Flint subdomain
   • -pages - your chosen subpath (without the leading slash)
5. 5.Click Save
6. 6.Restart your App Service again

For the X-Forwarded-Host and X-Forwarded-Proto headers to work, you need to allow them:

1. 1.In the Azure Portal, go to your App Service
2. 2.Go to Configuration > General settings
3. 3.Ensure ARR Affinity is enabled
4. 4.If you see errors about server variables, you may need to add them to the allowed list via the Kudu console or an applicationHost.xdt transform

Follow the same verification steps as Method 1, Step 8.

Linux App Services don't use IIS, so the approach is different. You'll need to configure a startup script that sets up Nginx as a reverse proxy.

Cost: No additional cost beyond your existing App Service plan.

Note: This method works best for Node.js, Python, and other Linux-based App Services. If your App Service runs a Docker container, you can modify the Nginx config inside your container instead.

1. 1.In the Azure Portal, go to your App Service
2. 2.Go to Development Tools > Advanced Tools (Kudu)
3. 3.Click Go, then open SSH from the top menu
4. 4.Create a custom Nginx config file:

cat > /home/site/nginx-custom.conf << 'NGINX_CONF'
location /pages/ {
    proxy_pass https://yoursite.tryflint.com/;
    proxy_set_header Host yoursite.tryflint.com;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_ssl_server_name on;
}

location = /pages {
    return 301 /pages/;
}
NGINX_CONF

5. 5.Replace the placeholder values:
   • -yoursite.tryflint.com - your Flint subdomain (appears twice)
   • -pages - your chosen subpath

1. 1.In the Azure Portal, go to your App Service
2. 2.Go to Configuration > General settings
3. 3.In the Startup Command field, enter a command that copies your custom config into the Nginx includes directory and starts your app. The exact command depends on your runtime, but the idea is:

cp /home/site/nginx-custom.conf /etc/nginx/conf.d/flint-proxy.conf && service nginx reload && <your-normal-startup-command>

Important: The exact file paths for Nginx configuration vary by App Service Linux runtime. You may need to check the default Nginx config location for your specific runtime (Node.js, Python, etc.). Reach out to the Flint team if you need help.

1. 1.Restart your App Service
2. 2.Follow the same verification steps as Method 1, Step 8

If your site runs on an Azure VM with Nginx, you can add a reverse proxy configuration directly. This is the same approach as any standard Linux server.

Cost: No additional cost beyond your existing VM.

1. 1.In the Azure Portal, go to your Virtual Machine
2. 2.Note the Public IP address from the Overview page
3. 3.Open a terminal on your computer and connect:

ssh your-username@YOUR_VM_IP

1. 1.Open your site's Nginx configuration file:

sudo nano /etc/nginx/sites-available/yoursite.com

(The file location may vary - check /etc/nginx/conf.d/ if the above doesn't exist.)

2. 2.Inside the server block for your domain, add the following above any existing location / block:

# Route /pages requests to Flint
location /pages/ {
    proxy_pass https://yoursite.tryflint.com/;
    proxy_set_header Host yoursite.tryflint.com;
    proxy_set_header X-Forwarded-Host yoursite.com;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_ssl_server_name on;
}

location = /pages {
    return 301 /pages/;
}

3. 3.Replace the placeholder values:
   • -yoursite.tryflint.com - your Flint subdomain (appears twice)
   • -yoursite.com - your domain
   • -pages - your chosen subpath

1. 1.Test the configuration:

sudo nginx -t

You should see: syntax is ok and test is successful.

2. 2.Reload Nginx:

sudo systemctl reload nginx

Make sure your VM's NSG allows inbound traffic on ports 80 and 443:

1. 1.In the Azure Portal, go to your VM
2. 2.Click Networking in the left sidebar
3. 3.Verify there are inbound rules allowing HTTP (port 80) and HTTPS (port 443) traffic

Follow the same verification steps as Method 1, Step 8.

If you'd rather not modify your Azure configuration, you can put Cloudflare in front of your domain and use a Worker to route subpath traffic. This works with any Azure hosting setup and is free for most sites.

Cost: Free (Cloudflare's free tier includes 100,000 requests per day).

1. 1.Go to cloudflare.com and sign up for a free account
2. 2.Click "Add a site", enter your domain, and select the Free plan
3. 3.Cloudflare will scan and import your existing DNS records - verify they look correct
4. 4.Cloudflare will provide two nameservers. Copy them down.

Go to your domain registrar (wherever you purchased your domain - GoDaddy, Namecheap, Azure DNS, etc.) and change the nameservers to the ones Cloudflare provided. This can take up to 24 hours to propagate.

In Cloudflare, go to SSL/TLS and set the mode to Full.

1. 1.In Cloudflare, go to Workers & Pages > Create
2. 2.Name the Worker (e.g., flint-router) and click Deploy
3. 3.Click Edit code, delete everything, and paste:

const YOUR_DOMAIN = "yoursite.com";
const FLINT_SUBDOMAIN = "yoursite.tryflint.com";
const SUBPATH = "pages";

export default {
  async fetch(request) {
    const url = new URL(request.url);

    if (
      url.pathname.startsWith("/" + SUBPATH + "/") ||
      url.pathname === "/" + SUBPATH
    ) {
      const flintUrl = url
        .toString()
        .replace(
          "https:" + "//" + YOUR_DOMAIN + "/" + SUBPATH,
          "https:" + "//" + FLINT_SUBDOMAIN
        );

      const proxyRequest = new Request(flintUrl, request);
      proxyRequest.headers.set("Host", FLINT_SUBDOMAIN);
      proxyRequest.headers.set("X-Forwarded-Host", YOUR_DOMAIN);
      proxyRequest.headers.set("X-Forwarded-Proto", "https");

      return fetch(proxyRequest);
    }

    return fetch(request);
  },
};

4. 4.Update the three values at the top, then click Save and deploy

1. 1.In your Worker's Settings > Triggers, click Add route
2. 2.Enter: yoursite.com/pages/*
3. 3.Select your domain's zone and click Add route

Follow the same verification steps as Method 1, Step 8.

My Flint pages show a blank page or error

• •Double-check your Flint subdomain with the Flint team. It must exactly match what Flint has configured for your site.
• •Make sure the Host header is set to your Flint subdomain, not your own domain.

Azure Front Door returns 404 for my subpath

• •Wait 5-10 minutes - Front Door route changes take time to propagate globally. This is the most common cause of 404s right after setup.
• •Verify the route pattern matches /pages/* (with the wildcard).
• •Check that the URL rewrite rule set is actually associated with the `flint-pages` route - creating the rule set alone isn't enough.
• •Make sure the Flint origin group has the correct hostname and that the Origin host header is set to your Flint subdomain (e.g., yoursite.tryflint.com).
• •Try purging the Front Door cache: go to Front Door manager > Purge and enter /pages/*.

App Service returns 500 or "ARR is not enabled"

• •Make sure you created the applicationHost.xdt file in the correct site directory (not site/wwwroot).
• •Restart your App Service after adding the file - a restart is required for the transform to apply.

The URL shows `tryflint.com` instead of my domain

• •Make sure the X-Forwarded-Host header is set to your domain in all configurations.

Azure VM: Nginx returns 502 Bad Gateway

• •Ensure proxy_ssl_server_name on; is included in your Nginx config. Without this, Nginx can't establish TLS connections to external hosts.
• •Check that your VM's Network Security Group allows outbound HTTPS traffic.

Cloudflare shows "Error 522" or "Error 524"

• •These mean Cloudflare can't reach your Azure server. Verify your DNS records in Cloudflare point to the correct Azure IP address.

If you're unsure which Azure service your site runs on, or if you run into issues during setup, reach out to the Flint team and we'll help you get set up.