DriversRecommendedOutdated drivers can make a good PC feel brokenScan driver issues before chasing fixes manually.Scan NowHalloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix Now×
FREEDOM251

Freedom251 › Blog › Alias

How to Serve a Subdirectory in an Apache VirtualHost Config

By Freedom251 Team · · 13 min read

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use DocumentRoot when the subdirectory is physically inside the site’s document tree. Use an Alias when the URL should look like /app/ but the files live somewhere else. An alias also needs a matching <Directory> block that grants only the access the target requires.

Choose the mapping that matches your filesystem

Apache maps a URL to a filesystem path in two common ways. If no directive overrides the normal mapping, Apache appends the path from the request to the virtual host’s DocumentRoot. A request for /app/index.html therefore maps to <DocumentRoot>/app/index.html.

As an Amazon Associate I earn from qualifying purchases.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

If the files are outside that tree, use Alias. Apache’s mod_alias documentation describes it this way: “The Alias directive allows documents to be stored in the local filesystem other than under the DocumentRoot.” The alias changes the URL-to-path mapping; it does not, by itself, authorize Apache to read the destination.

Question DocumentRoot approach Alias approach
Where are the files? Inside the virtual host’s document tree Anywhere else on the local filesystem
Example URL /app/index.html /app/index.html
Example physical path /srv/www/example/app/index.html /srv/apps/myapp/index.html
Configuration complexity Usually simplest Requires an Alias and matching <Directory>
When it is preferable A conventional site tree that can be moved as one unit A stable public URL must point to a separate deployment, shared directory, or application tree
Access-control scope Usually inherited from the document-root policy Can be restricted to the exact external target
Portability Simple when the whole site is deployed together Useful when deployments, mounts, or shared content use a different filesystem layout

Changing DocumentRoot is not a substitute for an alias. It changes the base path for the entire virtual host, which can make the main site and every relative URL resolve somewhere else. Use it only when the whole site should be rooted at the new directory.

#1 Best Overall
Sale
TOZO A1 Wireless Earbuds Bluetooth 5.3 Light Weight in Ear Headphones | IPX5 Waterproof,2 Mics for AI Calls,Immersive Premium Sound Bass Headset with Charging Case,32 EQ via App Black
  • [Ultra-Lightweight Ear Buds Designed for Small Ears] Each earbud weighs only 3.7g and features a compact, ergonomic in-ear design made especially for small ears. Secure, low-profile, and comfortable for workouts, all-day wear or overnight sleeping.The ultra-slim profile sits flush in your ear with no hard edges poking or rubbing, so you can even sleep on your side without discomfort.
  • [Immersive Stereo Sound with TOZO OrigX Technology] TOZO OrigX tuning delivers clear vocals, balanced mids, and natural stereo sound for music, podcasts, and videos.
  • [Long Battery Life for Daily Use] Get up to 7 hours of playtime on a single charge, with up to 32 hours total using the charging case—ideal for workdays, commuting, and extended listening sessions.
  • [Bluetooth 5.3 & Stable Connection] Bluetooth 5.3 provides fast pairing, stable wireless performance, and reduced dropouts as you move around home or office.
  • [Deep Bass with Clear Vocals] High-performance drivers produce punchy bass while keeping vocals clean and detailed for everyday listening.

How Apache builds the path

For an ordinary request, Apache separates the URL path from the hostname and uses the remaining path as a suffix of the document root. Thus, with DocumentRoot "/srv/www/example", / maps to /srv/www/example/, /app/ maps to /srv/www/example/app/, and /app/css/site.css maps to /srv/www/example/app/css/site.css. An Alias substitutes its target when the URL prefix matches, so only the matching portion is replaced; the remainder of the request path is appended to the alias target.

This distinction matters when a release is moved. A site whose files are all beneath one document root can usually be copied or switched as one tree. An aliased application can be deployed independently, but the alias target and its authorization policy must remain valid on every server that receives the request.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Pattern A: serve a subdirectory under DocumentRoot

For a normal site layout, put the subdirectory below the document root and leave Apache’s default URL-to-path behavior in place.

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/srv/www/example"

    <Directory "/srv/www/example">
        Require all granted
        AllowOverride All
    </Directory>
</VirtualHost>

With this filesystem:

/srv/www/example/
└── app/
    └── index.html

http://example.com/app/ resolves to /srv/www/example/app/, and http://example.com/app/index.html resolves to /srv/www/example/app/index.html.

What happens when the request names a directory

When the URL ends at a directory, Apache uses its configured DirectoryIndex files, such as index.html, when one exists. If no index file is available, the result depends on directory-listing settings: Apache may return an error or show a generated listing if indexing has been enabled. Set the index policy deliberately rather than relying on an accidental default.

A request for /app and one for /app/ are not identical URL forms. The slash identifies the resource as a directory and can affect how relative links in an HTML document are resolved. Test the form your navigation uses and provide a redirect when the site’s canonical URL requires one.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

When this pattern is the right choice

  • The application can live beneath the same release tree as the rest of the site.
  • You want the simplest path calculation and the fewest independent permissions to troubleshoot.
  • Moving or backing up the site as one directory is useful operationally.
  • Every environment can use the same document-root layout without a separate mount or deployment path.

Do not point DocumentRoot directly at the app directory merely to make /app/ work. That would make the application available at the virtual host root instead, changing the meaning of URLs such as /, stylesheets, scripts, and links elsewhere on the site. If the desired public prefix is specifically /app/, keep the parent directory as the document root and create app beneath it.

Rank #2
Sale
Smart Watch for Men Women Compatible with iPhone Samsung Android Phone 1.69 inch Full Touch Screen IP68 Waterproof Bluetooh Fitness Tracker Heart Rate/Sleep Monitor (Black)
  • 【IP68 Waterproof Multifunctinal Smart Watch】Torjalph fitness activity tracker smart watch is IP68 waterproof technology ,you can wear it when swimming,handwashing,it's rain-proof which means that you perform multiple exercise modes outside without worrying about sweat or rain corroding your fitness smart watch,and this watch equipped with a 230 mAh large capacity battery magnetic charging ,and this sports activity tracker watch can be used 5-7 days If fully charged.
  • 【Larger 1.83'' Full Screen Watch & Multi-dial Selection】1.83 inch full HD color touch screen smart watch for men / women provides excellent 240*284 resolution image quality ,This Bluetooth smart watch offers a better touch experience and remarkable immersion and ,more than 200 watch faces for you to choose from App"Da Fit ", you can change the dial style according to your mood to wear keeping the world on your wrist
  • 【Accurate Activity Tracker Smart Watch 】sports watch activity tracker uses sweat and dust resistant breathable silicone strap, our Fitness Tracker Smart Watch for Android iOS Phones supports 12 sports modes,walking,running,bicycle,swimming,badminton,basketball,football,rope skipping. This bluetooth calls smart watch for men women is lightweight and stylish, bringing more convenient and relaxing sports experience while also providing more protection.
  • 【Your 24 Hour Personal Daily Health Monitor】Fitness watch for women men full touch screen IP67 waterproof bluetooth smartwatch for Android iOS Phones with heart rate blood pressure monitor multifunction Andriod smart watch with steps counter sleep monitor sports fitness watch, monitoring blood oxygen saturation allows you to understand your physical condition in real time to track fitness progress ,to know your health status in time.
  • 【More Functions Bluetooth Call Smart Watch】This fitness activity smart watch full screen for iPhone and Android phones includes a bunch of new features including:The bluetooth smart watch can hang up the phone, receive and display WhatsAPP /Text /Facebook /Twitter /Messenger reminder.Support sedentary reminder, alarm clock, stopwatch, timer,weather information,music control, remote camera control compatible with Android 5.0 and above or iOS 9.0 and above smartphones.

Pattern B: map a URL subdirectory with Alias

Use an alias when the public path and physical path are intentionally different.

<VirtualHost *:80>
    ServerName example.com

    DocumentRoot "/srv/www/example"

    Alias "/app/" "/srv/apps/myapp/"
    <Directory "/srv/apps/myapp/">
        Require all granted
        AllowOverride None
        Options FollowSymLinks
    </Directory>
</VirtualHost>

Here, /app/index.html maps to /srv/apps/myapp/index.html. The rest of the virtual host continues to use /srv/www/example. A request for /app/images/logo.svg maps to /srv/apps/myapp/images/logo.svg; the alias does not flatten or rename the files below the target.

Keep the trailing-slash convention consistent

The example uses a slash at the end of both the URL path and target path. With a slash-terminated alias, the requested URL must include the trailing slash for that alias to match as documented. Test both /app and /app/; if the first does not redirect or resolve as expected, add an explicit redirect or adjust the URL convention rather than assuming the alias is broken.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Keep the slash style consistent in configuration. A target ending in / makes it clear that the URL prefix denotes a directory and avoids ambiguous concatenation when Apache appends the rest of the path. When changing the alias, retest a directory URL and a known file below it.

Authorize the destination separately

An alias only tells Apache where to look. The corresponding <Directory> section controls whether Apache may serve that location. Keep the section as narrow as possible: authorize the exact target directory, not an entire parent such as /srv. On Apache 2.4, Require all granted permits access to everyone who can reach that virtual host; replace it with the authentication or network restrictions your site needs when the content is not public.

AllowOverride None prevents files in the aliased tree from changing configuration through .htaccess. If the application genuinely needs per-directory overrides, use an appropriate AllowOverride policy and understand which directives it enables. Options FollowSymLinks permits symbolic-link traversal under this directory; enable it only when that behavior is intentional. Configuration choices in the external directory are independent of the URL prefix, so document them alongside the alias for future operators.

Common alias design mistakes

  • Defining the alias outside the virtual host that receives the request, so another host or global context handles it.
  • Granting a parent directory such as /srv/apps when only one application directory needs to be public.
  • Forgetting that a file must exist at the target plus the remaining URL path; an alias does not create missing directories or index files.
  • Assuming an alias on port 80 also applies to HTTPS. The request must reach a virtual host containing the alias on its own address and port.

Make sure Apache selects the intended virtual host

A correct alias in the wrong virtual host behaves like a missing alias. For name-based virtual hosts, Apache first matches the connection’s address and port, then compares the request hostname with ServerName and ServerAlias. If no hostname matches, the first virtual host for that address and port becomes the default.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #3
New Bee Guitar Cable 10ft Electric Instrument Bass AMP Cord
  • [Low Noise High Fidelity] New bee guitar cord with 22AWG oxygen-free-copper center conductors provides enhanced signal transfer, the PVC insulation material and the high-density stranded copper double shield provide noise rejection for quiet operation
  • [Ideal for Choice] New bee 1/4 straight and right angle metal connectors, ensures a secure connection in any instrument, pedal, or amp jack. L shape great fro on stage guitar stands
  • [Wide Compatible] Suitable for mixer, power amplifier, microphone, effector, decoder, equalizer, electoronic organ, electric guitar, electric bass and other electronic equipments. Widely used in the installation of smart home, karaoke speaker, professional stage audio, etc
  • [Easy Disassemble] Making incidental repairs quick and easy! Very nice, flexible cable
  • [Dont Hesite to Order] 24 hours customer services and professional technology team are standing by

Set an explicit hostname

Include a ServerName in every name-based virtual host:

<VirtualHost *:80>
    ServerName example.com
    ServerAlias www.example.com
    ...
</VirtualHost>

A <VirtualHost> block does not create DNS. The hostname must resolve to the server’s address before a browser can reach this configuration. If DNS still points elsewhere, Apache will never receive the request and cannot apply the alias. During testing, verify the hostname resolves to the intended address and that any proxy or load balancer forwards the original host as expected.

Check the address and port

Make the <VirtualHost> address and port match the listener handling the request, such as *:80 for HTTP or *:443 for HTTPS. Configure the alias in the HTTPS virtual host as well if the failing request is encrypted; a working port-80 block does not automatically affect port 443. If HTTP redirects to HTTPS, test the final HTTPS request rather than stopping after observing the redirect.

Validate the configuration before debugging the browser

  1. Run apachectl configtest on Unix-like systems, or httpd -t. Fix every syntax error before reloading Apache.
  2. Inspect parsed virtual hosts with apachectl -S. On Windows, use httpd.exe -S. This shows which address, port, and configuration file Apache associated with each virtual host.
  3. Request both /app and /app/ when the alias ends in a slash. Record whether the response is a redirect, 404, 403, or successful content.
  4. Request a file whose existence you know, such as /app/index.html. A known file distinguishes mapping problems from missing-index behavior.
  5. Read the access and error logs for the same request. The status code, selected host, and filesystem-related error usually identify the failing layer.
  6. Check the complete filesystem path, including every parent directory. Apache’s account needs permission to read the file and execute (traverse) each directory leading to it.

Reload or restart Apache only after the configuration test succeeds, using the service procedure appropriate to the operating system and distribution. A successful reload confirms that Apache accepted the syntax, not that DNS, permissions, or the selected virtual host are correct; those still require a request test.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Validate one layer at a time. First prove that Apache loaded the file and selected the expected virtual host. Next prove that the URL prefix maps to the expected directory with a static, known file. Only then investigate application routing, rewrites, or generated responses. This order prevents a rewrite rule or missing index from hiding a basic path error.

Troubleshoot by symptom

Symptom Likely causes Checks and fixes
404 Not Found Typo in the URL or target path; alias placed in another virtual host; an earlier alias matched first Compare the URL and filesystem spelling, verify the selected vhost with apachectl -S, and inspect aliases in configuration order. Put more specific aliases before broader ones because the first matching alias takes precedence.
403 Forbidden Missing authorization section; insufficient file permission; a parent directory cannot be traversed; a higher-level restriction blocks access Confirm a matching <Directory> block, then check read permission on the file and execute permission on every parent directory. Review authentication, IP, and other inherited restrictions.
The wrong site is served DNS points to another server; hostname does not match ServerName or ServerAlias; address/port is wrong; request fell through to the first vhost Verify DNS, the request hostname, the virtual host address and port, and the parsed order shown by apachectl -S.
A directory listing appears instead of an index No configured DirectoryIndex file exists, or directory indexing is enabled Check that the expected index filename exists in the mapped directory and review DirectoryIndex and indexing options.
The alias seems ignored after a rewrite Rewrite rules or .htaccess processing changes the request after it reaches the vhost First prove that the request reaches the intended vhost and that a direct known file works. Then inspect rewrite rules and per-directory configuration for redirects, front-controller routing, or path substitutions.

Interpreting 403 versus 404

A 404 usually means Apache did not find a matching resource or mapping. Check spelling, alias order, and the selected virtual host first. A 403 means Apache recognized the request but refused access, often because authorization or filesystem traversal failed. Do not “fix” a 403 by granting access to a much broader directory; identify the exact target and parent permission that is missing.

Alias ordering and overlapping paths

Apache evaluates aliases in configuration order, and the first match wins. An alias such as /app/ can therefore capture a request that you intended for a more specific path. Place longer, more specific URL prefixes before shorter, general ones, and avoid overlapping aliases unless their precedence is deliberate.

Rank #4
BSIMB 15.6" Digital Family Calendar & Chore Chart, No Subscription Fees
  • Digital Family Calendar: BSIMB digital calendar wall touch screen puts an end to your chaotic life. Designed for busy families, the digital calendar keeps you organised and in step with your family. Assign different colours and tasks to each family member to make family scheduling easier and more intuitive.
  • Easy Setup and Auto-Sync: Plug in, connect to WLAN and auto-syn your electric calendar in minutes. Digital wall calendar compatible with Google calendar, iCloud calendar, Outlook calendar, Cozi calendar and Yahoo calendar. Add events directly on the device or through the ecalendar app. Electronic calendar stays current whether you're at work or traveling—no manual updates needed.
  • All-In-One Home Assistant: Smart calendar builds habits and encourage independence with personalised chores. Display daily meal plan to reduce the daily ‘What's for dinner?’ stress. To-do lists keep track of everything you want. Turning chores into valuable achievements with stars and rewards, making life easier and more enjoyable.
  • Manage Anytime Anywhere: BSIMB electronic calendar for family stay connected with the powerful ecalendar app. Access and manage your digital wall calendar anytime, anywhere with free features like stars & rewards, photo screensaver, chore charts, meals plans, to-do lists etc. Electronic planner paid features like Magic Import tailor advanced tools for users with special needs.
  • Stay in Touch with Loved Ones: Share photos or videos from your phone to electronic wall calendar with app, instantly update your life moment, and keep in touch with your family, especially those who are far away; you can also surprise your smart calendar digital wall by sending him a wish card; it's also great for keeping tech-illiterate elders in touch with the youngsters.

When diagnosing an overlap, test a unique file beneath each path rather than relying only on the directory URL. The resulting log entry and returned content reveal which mapping actually handled the request. Keep related aliases together in the configuration and comment their intended scope so a later edit does not silently change precedence.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Permissions and security boundaries

Linux and Unix permissions apply to the entire path, not only the final file. For /srv/apps/myapp/index.html, Apache must be able to traverse /srv, /srv/apps, and /srv/apps/myapp, and read the file. A readable file inside an inaccessible parent still produces a 403.

  • Grant access to the smallest target directory that must be public.
  • Do not use a broad <Directory> rule to make an error disappear; it may expose unrelated files.
  • Keep application secrets, deployment metadata, and source files outside a public alias whenever possible.
  • Use authentication, IP restrictions, or other authorization directives for private content instead of relying on an obscure URL.
  • Review symbolic links and Options settings so an alias cannot unexpectedly reach another tree.

These controls are independent: filesystem permissions decide whether the operating-system account can traverse and read the path, while Apache authorization decides whether the HTTP request is allowed to use it. Both layers must permit the request. A change to one layer does not replace the other, and a successful configuration test does not verify either layer.

Portability and deployment considerations

DocumentRoot is generally easier to copy between development, staging, and production because the URL tree and filesystem tree have the same shape. An Alias is preferable when the physical location is managed separately, but every environment must define the same URL prefix, target path, and <Directory> policy. If those paths differ by environment, keep the difference in the environment-specific virtual-host configuration rather than changing application links.

For a rollout, verify that the external directory exists before reloading Apache, that its parent directories are traversable by the service account, and that the alias target contains the expected index or static files. A configuration can pass syntax validation while still pointing at an empty, moved, or unmounted directory.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Practical decision checklist

  • Inside the site tree: keep the existing DocumentRoot and create the subdirectory beneath it.
  • Outside the site tree: add an Alias inside the exact <VirtualHost> that receives the request.
  • Private or restricted content: replace unrestricted access with the site’s required authorization policy.
  • Slash-terminated alias: test and handle both /app and /app/.
  • Overlapping prefixes: put the most specific alias first.
  • Any failure: validate syntax, inspect parsed vhosts, request a known file, read logs, and then check every path permission.

The reliable pattern is therefore straightforward: use the document root for an ordinary child directory, use an alias for a different physical location, authorize that location explicitly, and verify the selected virtual host before changing unrelated settings.

Frequently Asked Questions

Should I change DocumentRoot to the subdirectory I want to serve?

Usually no. Keep the parent directory as DocumentRoot when the files are already beneath it; /app/ will map to the child directory. Changing DocumentRoot changes the base for the entire virtual host and can move the site root, stylesheets, scripts, and other links.

When should I use Alias instead of DocumentRoot?

Use Alias when the public URL prefix must point to a directory outside the virtual host’s document tree. Add a matching <Directory> block for that exact target. Use the ordinary document-root layout when the files can live under the site tree.

Why does an Alias return 403?

An alias maps the URL but does not authorize the destination. Check the matching <Directory> section, Apache’s authorization directives, read permission on the file, and execute (traverse) permission on every parent directory. Also review inherited authentication or network restrictions.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Why does /app/ work but /app not work?

A slash-terminated alias is matched with the trailing slash convention. Test both forms and configure an explicit redirect or canonical URL if /app should become /app/. Confirm the alias and target paths use consistent slashes.

Why is the wrong website responding to the request?

Check DNS, the request hostname, ServerName, ServerAlias, and the virtual host address and port. If no hostname matches, Apache uses the first virtual host for that address and port. Run apachectl -S or httpd.exe -S to inspect the parsed order.

Does an Alias configured for HTTP also work for HTTPS?

Not automatically. HTTP and HTTPS normally use different virtual-host address/port combinations. Put the alias and its matching <Directory> policy in the HTTPS virtual host that receives port-443 requests, then test the final HTTPS URL.

How do I distinguish a missing index from a broken alias?

Request a known file such as /app/index.html. If that succeeds, the mapping works and the directory behavior is the issue; check DirectoryIndex and indexing settings. If the known file fails, inspect alias placement, path spelling, vhost selection, and permissions.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Can .htaccess change behavior in an aliased directory?

Only if the target directory permits overrides. AllowOverride None prevents per-directory files from changing configuration. If overrides are required, choose a narrower policy deliberately and inspect rewrite rules after confirming that a direct known file maps correctly.

What happens when two aliases overlap?

Apache processes aliases in configuration order and the first matching alias takes precedence. Put more specific, longer URL prefixes before broader ones, avoid accidental overlap, and test a unique file under each prefix to confirm the intended mapping.

The Bottom Line

Keep a normal subdirectory under DocumentRoot when the files belong to the site tree. Use Alias for an external directory, pair it with a narrowly scoped <Directory> authorization block, handle trailing slashes, and verify the selected virtual host, permissions, and logs with a known-file request.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

AliasApacheconfigurationDocumentRootLinuxVirtualHostweb server

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Crashes, No Sound, or Screen Glitches?Free driver scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.