<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/content/features/virtual-hosting.md - fork/static-web-server @ allow-symlink</title>
<meta name="description" content="docs/content/features/virtual-hosting.md in fork/static-web-server at allow-symlink.">
<meta property="og:title" content="docs/content/features/virtual-hosting.md - fork/static-web-server @ allow-symlink">
<meta property="og:description" content="docs/content/features/virtual-hosting.md in fork/static-web-server at allow-symlink.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="allow-symlink" data-tip="4414610fe1b0370ff0ac415e9367548840584710">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/static-web-server</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/static-web-server</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Matthias Schoettle</span><span class="commit-message" data-commit="dd43d06551fcf853e0012381c76af5b832d23b57">refactor: format check support Markdown files via mdformat (#597)</span><span class="snapshot-sha sha" data-commit="dd43d06551fcf853e0012381c76af5b832d23b57">dd43d06</span><time datetime="2025-12-07T04:40:21-05:00" title="2025-12-07 04:40:21 -0500">2025-12-07</time></p>
<header class="topbar"><details class="switcher"><summary>allow-symlink</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/static-web-server/ref/allow-symlink/">allow-symlink</a><a class="all" href="/fork/static-web-server/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/static-web-server/">static-web-server</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/">docs</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/content/">content</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/content/features/">features</a> / <span class="cur">virtual-hosting.md</span></nav>
<span class="view-stats"><span>1.7 KiB</span><span>30 lines</span></span><span class="actions"><a class="raw" href="/fork/static-web-server/raw/4fea14b1f9b7342caff53eb42a72cb2e0252dfec/docs/content/features/virtual-hosting.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>Virtual Hosting</h1>
<p><strong>SWS</strong> provides rudimentary support for name-based <a href="https://en.wikipedia.org/wiki/Virtual_hosting#Name-based">virtual hosting</a>. This allows you to serve files from different root directories depending on the <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/host">"Host" header</a> of the request, with all other settings staying the same.</p>
<p>!!! warning "All other settings are the same!"</p>
<pre><code>Each virtual host has to have all the same settings (aside from `root`). If using TLS, your certificates will have to cover all virtual host names as Subject Alternative Names (SANs). Also, beware of other conflicting settings like redirects and rewrites. If you find yourself needing different settings for different virtual hosts, it is recommended to run multiple instances of SWS.
</code></pre>
<p>Virtual hosting can be useful for serving more than one static website from the same SWS instance, if it's not otherwise feasible to run multiple instances of SWS. Browsers will automatically send a <code>Host</code> header which matches the hostname in the URL bar, which is how HTTP servers are able to tell which "virtual" host that the client is accessing.</p>
<p>By default, SWS will always serve files from the main <code>root</code> directory. If you configure virtual hosting and the "Host" header matches, SWS will instead look for files in an alternate root directory you specify.</p>
<h2>Examples</h2>
<pre class="language-toml"><a-c># By default, all requests are served from here</a-c>
<a-pr>root</a-pr> <a-o>=</a-o> <a-s>&quot;/var/www/html&quot;</a-s>

<a-p>[</a-p><a-pr>advanced</a-pr><a-p>]</a-p>

<a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>virtual-hosts</a-pr><a-p>]]</a-p>
<a-c># But if the &quot;Host&quot; header matches this...</a-c>
<a-pr>host</a-pr> <a-o>=</a-o> <a-s>&quot;sales.example.com&quot;</a-s>
<a-c># ...then files will be served from here instead</a-c>
<a-pr>root</a-pr> <a-o>=</a-o> <a-s>&quot;/var/sales/html&quot;</a-s>

<a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>virtual-hosts</a-pr><a-p>]]</a-p>
<a-pr>host</a-pr> <a-o>=</a-o> <a-s>&quot;blog.example.com&quot;</a-s>
<a-pr>root</a-pr> <a-o>=</a-o> <a-s>&quot;/var/blog/html&quot;</a-s></pre>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>Virtual Hosting</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">**SWS** provides rudimentary support for name-based [virtual hosting](https://en.wikipedia.org/wiki/Virtual_hosting#Name-based). This allows you to serve files from different root directories depending on the [&quot;Host&quot; header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/host) of the request, with all other settings staying the same.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">!!! warning &quot;All other settings are the same!&quot;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-tl>    Each virtual host has to have all the same settings (aside from `root`). If using TLS, your certificates will have to cover all virtual host names as Subject Alternative Names (SANs). Also, beware of other conflicting settings like redirects and rewrites. If you find yourself needing different settings for different virtual hosts, it is recommended to run multiple instances of SWS.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">Virtual hosting can be useful for serving more than one static website from the same SWS instance, if it&#39;s not otherwise feasible to run multiple instances of SWS. Browsers will automatically send a `Host` header which matches the hostname in the URL bar, which is how HTTP servers are able to tell which &quot;virtual&quot; host that the client is accessing.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">By default, SWS will always serve files from the main `root` directory. If you configure virtual hosting and the &quot;Host&quot; header matches, SWS will instead look for files in an alternate root directory you specify.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"><a-p>##</a-p> <a-tt>Examples</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>```</a-p><a-tl>toml</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p># By default, all requests are served from here</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>root </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/var/www/html&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-p>[</a-p><a-pr>advanced</a-pr><a-p>]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"><a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>virtual-hosts</a-pr><a-p>]]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p># But if the &quot;Host&quot; header matches this...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>host </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;sales.example.com&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"><a-p># ...then files will be served from here instead</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>root </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/var/sales/html&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>virtual-hosts</a-pr><a-p>]]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>host </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;blog.example.com&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>root </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/var/blog/html&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"><a-p>```</a-p></span></span></pre></div></div>
</main>
</body>
</html>
