How to use Virtual Directory

What is Virtual Directory

A virtual directory is a mapping in a web server (like IIS) that points to an alternative site on your system but appears as part of the website’s URL structure. To use it, you create the virtual directory on a particular HTTP proxy rule, assign it a upstream, and click save. This lets you serve files from different locations without moving them into the main site directory. It is not Nginx Location.

When to use Virtual Directory?

You should use a virtual directory when you want to serve content stored outside your main web root, such as shared resources or site on another server, without duplicating them. They’re also useful for organizing large sites into logical sections.

Usually when using virtual directory, the upstream should be a plain resources serving site like a cdn or a system that support setting something like "site URL" or "base URL" (setting name varies in different open source projects)

Note that not all open source server application support Virtual Directory and no, it doesn't work like Nginx Location.

Example Usage

This is a common confusion from people who switch from Nginx to Zoraxy. Zoraxy Virtual Directory is not Nginx Locations, it works more closely to Apache Alias or IIS Virtual Directory (which this design was referenced from).

For clarification:

# Virtual Directory Settings
/api -> 192.168.1.183/api

# Will resolves to
/api/v1/sessions -> /v1/sessions

# After remove /api from Virtual Directory Settings
/api/v1/sessions -> /api/v1/sessions

Here are a few more examples

Host: example.com -> 192.168.0.1
VDir: /foo/bar -> 192.168.0.100/resources

# For Virtual Directory, link in brackets are rewritten path prefix so it resolves correctly on your upstream if use properly
/foo/bar/image.png -> (192.168.0.100/resources)/image.png
/foo/bar/js/myscript.js -> (192.168.0.100/resources)/js/myscript.js
/foo -> (192.168.0.1)/foo

# For Location type logics, this will become
/foo/bar/image.png -> (192.168.0.100/resources)/foo/bar/image.png
/foo/bar/js/myscript.js -> (192.168.0.100/resources)/foo/bar/js/myscript.js
/foo -> (192.168.0.1)/foo

# this is why you need proxy_pass in Nginx, which is another story and I am not covering it here.

What could I try if it is not working on (open source project name)?

Here are a few things you can try

1. Try to remove all Virtual Directory rules and see if Zoraxy can automatically handle all the routing without issue
2. Try to understand what those Nginx (or what reverse proxy you are coming from) means and adjust them accordingly to Zoraxy configs
3. Take a break, have a cup of coffee (or Tea, if you are from UK) and come back later to see if someone asked the same question as you do but eventually get it working and shared his / her solution
4. Open a help issue (as a last resort)

Why you need to repeat so many time ZORAXY VIRTUAL DIRECTORY IS NOT NGINX LOCATION?

Because this is the number one help issue on Zoraxy Github that ask why a path not working in Zoraxy. This wiki page is here to help solve the problem and most of the time, people just assume they are identical and configure the wrong settings.