enigma-bbs/servers/contentservers/web-server.html

2473 lines
25 KiB
HTML
Raw Normal View History

<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="icon" type="image/png" sizes="16x16" href="/enigma-bbs/assets/images/favicon-16x16.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="32x32" href="/enigma-bbs/assets/images/favicon-32x32.png">
<link rel="stylesheet" href="/enigma-bbs/assets/css/style.css?v=">
<!-- Begin Jekyll SEO tag v2.7.1 -->
<title>Web Server | ENiGMA½ BBS Software</title>
<meta name="generator" content="Jekyll v4.2.1" />
<meta property="og:title" content="Web Server" />
<meta property="og:locale" content="en_US" />
<meta name="description" content="ENiGMA½ comes with a built in content server for supporting both HTTP and HTTPS. Currently the File Bases registers routes for file downloads, password reset email links are handled via the server, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!" />
<meta property="og:description" content="ENiGMA½ comes with a built in content server for supporting both HTTP and HTTPS. Currently the File Bases registers routes for file downloads, password reset email links are handled via the server, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!" />
<meta property="og:site_name" content="ENiGMA½ BBS Software" />
<meta property="og:type" content="article" />
<meta property="article:published_time" content="2022-09-09T03:31:32+00:00" />
<meta name="twitter:card" content="summary" />
<meta property="twitter:title" content="Web Server" />
<script type="application/ld+json">
{"datePublished":"2022-09-09T03:31:32+00:00","description":"ENiGMA½ comes with a built in content server for supporting both HTTP and HTTPS. Currently the File Bases registers routes for file downloads, password reset email links are handled via the server, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!","mainEntityOfPage":{"@type":"WebPage","@id":"/enigma-bbs/servers/contentservers/web-server.html"},"url":"/enigma-bbs/servers/contentservers/web-server.html","@type":"BlogPosting","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"/enigma-bbs/assets/images/enigma-logo.png"}},"headline":"Web Server","dateModified":"2022-09-09T03:31:32+00:00","@context":"https://schema.org"}</script>
<!-- End Jekyll SEO tag -->
</head>
<body>
<div id="container">
<div class="sidebar" id="sidebar">
<hr class="mobile-divide">
<div class="container">
<a href="/enigma-bbs/"><img src="/enigma-bbs/assets/images/enigma-logo.png" class="logo" alt="Enigma logo"></a>
</div>
<ul>
<li>Installation</li>
<ul>
<li><a href="/enigma-bbs/installation/installation-methods.html">Installation Methods</a></li>
<li><a href="/enigma-bbs/installation/install-script.html">Install Script</a></li>
<li><a href="/enigma-bbs/installation/docker.html">Docker</a></li>
<li><a href="/enigma-bbs/installation/manual.html">Manual Installation</a></li>
<li>OS / Hardware Specific</li>
<ul>
<li><a href="/enigma-bbs/installation/hardware/rpi.html">Raspberry Pi</a></li>
<li><a href="/enigma-bbs/installation/hardware/windows.html">Installation Under Windows</a></li>
</ul>
<li><a href="/enigma-bbs/installation/network.html">Network Setup</a></li>
<li><a href="/enigma-bbs/installation/testing.html">Testing Your Installation</a></li>
<li><a href="/enigma-bbs/installation/production.html">Production Installation</a></li>
</ul>
<li>Configuration</li>
<ul>
<li><a href="/enigma-bbs/configuration/creating-config.html">Creating Initial Config Files</a></li>
<li><a href="/enigma-bbs/configuration/sysop-setup.html">SysOp Setup</a></li>
<li><a href="/enigma-bbs/configuration/config-files.html">Configuration Files</a></li>
<li><a href="/enigma-bbs/configuration/config-hjson.html">System Configuration</a></li>
<li><a href="/enigma-bbs/configuration/hjson.html">HJSON Config Files</a></li>
<li><a href="/enigma-bbs/configuration/menu-hjson.html">Menu HSJON</a></li>
<li><a href="/enigma-bbs/configuration/directory-structure.html">Directory Structure</a></li>
<li><a href="/enigma-bbs/configuration/external-binaries.html">External Support Binaries</a></li>
<li><a href="/enigma-bbs/configuration/archivers.html">Archivers</a></li>
<li><a href="/enigma-bbs/configuration/file-transfer-protocols.html">File Transfer Protocols</a></li>
<li><a href="/enigma-bbs/configuration/email.html">Email</a></li>
<li><a href="/enigma-bbs/configuration/colour-codes.html">Colour Codes</a></li>
<li><a href="/enigma-bbs/configuration/event-scheduler.html">Event Scheduler</a></li>
<li><a href="/enigma-bbs/configuration/acs.html">Access Condition System (ACS)</a></li>
<li><a href="/enigma-bbs/configuration/security.html">Security</a></li>
</ul>
<li>Miscellaneous</li>
<ul>
<li><a href="/enigma-bbs/misc/user-interrupt.html">User Interruptions</a></li>
</ul>
<li>File Base</li>
<ul>
<li><a href="/enigma-bbs/filebase/index.html">About File Areas</a></li>
<li><a href="/enigma-bbs/filebase/first-file-area.html">Configuring a File Base</a></li>
<li><a href="/enigma-bbs/filebase/acs.html">ACS</a></li>
<li><a href="/enigma-bbs/filebase/uploads.html">Uploads</a></li>
<li><a href="/enigma-bbs/filebase/web-access.html">Web Access</a></li>
<li><a href="/enigma-bbs/filebase/tic-support.html">TIC Support</a></li>
<li><a href="/enigma-bbs/filebase/network-mounts-and-symlinks.html">Network Mounts &amp; Symlinks</a></li>
</ul>
<li>Message Areas</li>
<ul>
<li><a href="/enigma-bbs/messageareas/configuring-a-message-area.html">Message Base</a></li>
<li><a href="/enigma-bbs/messageareas/message-networks.html">Message Networks</a></li>
<li><a href="/enigma-bbs/messageareas/bso-import-export.html">BSO Import / Export</a></li>
<li><a href="/enigma-bbs/messageareas/netmail.html">Netmail</a></li>
<li><a href="/enigma-bbs/messageareas/qwk.html">QWK Support</a></li>
<li><a href="/enigma-bbs/messageareas/ftn.html">FidoNet-Style Networks (FTN)</a></li>
</ul>
<li>Art</li>
<ul>
<li><a href="/enigma-bbs/art/general.html">General Art Information</a></li>
<li><a href="/enigma-bbs/art/themes.html">Themes</a></li>
<li><a href="/enigma-bbs/art/mci.html">MCI Codes</a></li>
<li>Views</li>
<ul>
<li><a href="/enigma-bbs/art/views/button_view.html">Button View</a></li>
<li><a href="/enigma-bbs/art/views/edit_text_view.html">Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/full_menu_view.html">Full Menu View</a></li>
<li><a href="/enigma-bbs/art/views/horizontal_menu_view.html">Horizontal Menu View</a></li>
<li><a href="/enigma-bbs/art/views/mask_edit_text_view.html">Mask Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/multi_line_edit_text_view.html">Multi Line Edit Text View</a></li>
<li><a href="/enigma-bbs/art/views/predefined_label_view.html">Predefined Label View</a></li>
<li><a href="/enigma-bbs/art/views/spinner_menu_view.html">Spinner Menu View</a></li>
<li><a href="/enigma-bbs/art/views/text_view.html">Text View</a></li>
<li><a href="/enigma-bbs/art/views/toggle_menu_view.html">Toggle Menu View</a></li>
<li><a href="/enigma-bbs/art/views/vertical_menu_view.html">Vertical Menu View</a></li>
</ul>
</ul>
<li>Servers</li>
<ul>
<li>Login Servers</li>
<ul>
<li><a href="/enigma-bbs/servers/loginservers/telnet.html">Telnet Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/ssh.html">SSH Server</a></li>
<li><a href="/enigma-bbs/servers/loginservers/websocket.html">Web Socket / Web Interface Server</a></li>
</ul>
<li>Content Servers</li>
<ul>
<li class="active-nav">Web Server</li>
<li><a href="/enigma-bbs/servers/contentservers/gopher.html">Gopher Server</a></li>
<li><a href="/enigma-bbs/servers/contentservers/nntp.html">NNTP Server</a></li>
</ul>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/local-doors.html">Local Doors</a></li>
<li><a href="/enigma-bbs/modding/door-servers.html">Door Servers</a></li>
<li><a href="/enigma-bbs/modding/telnet-bridge.html">Telnet Bridge</a></li>
<li><a href="/enigma-bbs/modding/existing-mods.html">Existing Mods</a></li>
<li><a href="/enigma-bbs/modding/file-area-list.html">File Area List</a></li>
<li><a href="/enigma-bbs/modding/last-callers.html">Last Callers</a></li>
<li><a href="/enigma-bbs/modding/whos-online.html">Who's Online</a></li>
<li><a href="/enigma-bbs/modding/user-list.html">User List</a></li>
<li><a href="/enigma-bbs/modding/msg-conf-list.html">Message Conference List</a></li>
<li><a href="/enigma-bbs/modding/msg-area-list.html">Message Area List</a></li>
<li><a href="/enigma-bbs/modding/bbs-list.html">BBS List</a></li>
<li><a href="/enigma-bbs/modding/rumorz.html">Rumorz</a></li>
<li><a href="/enigma-bbs/modding/file-transfer-protocol-select.html">File Transfer Protocol Select</a></li>
<li><a href="/enigma-bbs/modding/onelinerz.html">Onelinerz</a></li>
<li><a href="/enigma-bbs/modding/show-art.html">The Show Art Module</a></li>
<li><a href="/enigma-bbs/modding/file-base-download-manager.html">File Base Download Manager</a></li>
<li><a href="/enigma-bbs/modding/file-base-web-download-manager.html">File Base Web Download Manager</a></li>
<li><a href="/enigma-bbs/modding/set-newscan-date.html">Set Newscan Date Module</a></li>
<li><a href="/enigma-bbs/modding/node-msg.html">Node to Node Messaging</a></li>
<li><a href="/enigma-bbs/modding/top-x.html">TopX</a></li>
<li><a href="/enigma-bbs/modding/user-2fa-otp-config.html">2FA/OTP Config</a></li>
<li><a href="/enigma-bbs/modding/autosig-edit.html">Auto Signature Editor</a></li>
<li><a href="/enigma-bbs/modding/menu-modules.html">Menu Modules</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/administration.html">Administration</a></li>
</ul>
<li>Modding</li>
<ul>
<li><a href="/enigma-bbs/modding/wfc.html">Waiting For Caller (WFC)</a></li>
</ul>
<li>Administration</li>
<ul>
<li><a href="/enigma-bbs/admin/oputil.html">oputil</a></li>
<li><a href="/enigma-bbs/admin/updating.html">Updating</a></li>
</ul>
<li>Troubleshooting</li>
<ul>
<li><a href="/enigma-bbs/troubleshooting/monitoring-logs.html">Monitoring Logs</a></li>
</ul>
</ul>
</div>
<div class="main_area">
<div class="container">
<section id="main_content">
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/servers/loginservers/websocket.html">« Web Socket / Web Interface Server</a>
<a href="#sidebar" class="btn menu_button">MENU</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/servers/contentservers/gopher.html">Gopher Server »</a>
<br clear="both">
</div>
<div class="page">
<h1 class="page-title">Web Server</h1>
<p>ENiGMA½ comes with a built in <em>content server</em> for supporting both HTTP and HTTPS. Currently the <a href="../modding/file-base-web-download-manager.md">File Bases</a> registers routes for file downloads, password reset email links are handled via the server, and static files can also be served for your BBS. Other features will likely come in the future or you can easily write your own!</p>
<h1 id="configuration">Configuration</h1>
<p>By default the web server is not enabled. To enable it, you will need to at a minimum configure two keys in the <code class="language-plaintext highlighter-rouge">contentServers.web</code> section of <code class="language-plaintext highlighter-rouge">config.hjson</code>:</p>
<pre><code class="language-hjson">contentServers: {
web: {
domain: bbs.yourdomain.com
http: {
enabled: true
port: 8080
}
}
}
</code></pre>
<p>The following is a table of all configuration keys available under <code class="language-plaintext highlighter-rouge">contentServers.web</code>:</p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="language-plaintext highlighter-rouge">domain</code></td>
<td><img class="emoji" title=":+1:" alt=":+1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" height="20" width="20"></td>
<td>Sets the domain, e.g. <code class="language-plaintext highlighter-rouge">bbs.yourdomain.com</code>.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">http</code></td>
<td><img class="emoji" title=":-1:" alt=":-1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" height="20" width="20"></td>
<td>Sub configuration for HTTP (non-secure) connections. See <strong>HTTP Configuration</strong> below.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">overrideUrlPrefix</code></td>
<td><img class="emoji" title=":-1:" alt=":-1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" height="20" width="20"></td>
<td>Instructs the system to be explicit when handing out URLs. Useful if your server is behind a transparent proxy.</td>
</tr>
</tbody>
</table>
<h3 id="http-configuration">HTTP Configuration</h3>
<p>Entries available under <code class="language-plaintext highlighter-rouge">contentServers.web.http</code>:</p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="language-plaintext highlighter-rouge">enable</code></td>
<td><img class="emoji" title=":+1:" alt=":+1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" height="20" width="20"></td>
<td>Set to <code class="language-plaintext highlighter-rouge">true</code> to enable this server.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">port</code></td>
<td><img class="emoji" title=":-1:" alt=":-1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" height="20" width="20"></td>
<td>Override the default port of <code class="language-plaintext highlighter-rouge">8080</code>.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">address</code></td>
<td><img class="emoji" title=":-1:" alt=":-1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" height="20" width="20"></td>
<td>Sets an explicit bind address.</td>
</tr>
</tbody>
</table>
<h3 id="https-configuration">HTTPS Configuration</h3>
<p>Entries available under <code class="language-plaintext highlighter-rouge">contentServers.web.https</code>:</p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code class="language-plaintext highlighter-rouge">enable</code></td>
<td><img class="emoji" title=":+1:" alt=":+1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" height="20" width="20"></td>
<td>Set to <code class="language-plaintext highlighter-rouge">true</code> to enable this server.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">port</code></td>
<td><img class="emoji" title=":-1:" alt=":-1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" height="20" width="20"></td>
<td>Override the default port of <code class="language-plaintext highlighter-rouge">8080</code>.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">address</code></td>
<td><img class="emoji" title=":-1:" alt=":-1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44e.png" height="20" width="20"></td>
<td>Sets an explicit bind address.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">certPem</code></td>
<td><img class="emoji" title=":+1:" alt=":+1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" height="20" width="20"></td>
<td>Overrides the default certificate path of <code class="language-plaintext highlighter-rouge">/config/https_cert.pem</code>. Certificate must be in PEM format. See <strong>Certificates</strong> below.</td>
</tr>
<tr>
<td><code class="language-plaintext highlighter-rouge">keyPem</code></td>
<td><img class="emoji" title=":+1:" alt=":+1:" src="https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png" height="20" width="20"></td>
<td>Overrides the default certificate key path of <code class="language-plaintext highlighter-rouge">/config/https_cert_key.pem</code>. Key must be in PEM format. See <strong>Certificates</strong> below.</td>
</tr>
</tbody>
</table>
<h4 id="certificates">Certificates</h4>
<p>If you dont have a TLS certificate for your domain, a good source for a certificate can be <a href="https://letsencrypt.org/">Lets Encrypt</a> who supplies free and trusted TLS certificates. A common strategy is to place another web server such as <a href="https://caddyserver.com/">Caddy</a> in front of ENiGMA½ acting as a transparent proxy and TLS termination point.</p>
<blockquote>
<p><img class="emoji" title=":information_source:" alt=":information_source:" src="https://github.githubassets.com/images/icons/emoji/unicode/2139.png" height="20" width="20"> Keep in mind that the SSL certificate provided by Lets Encrypts Certbot is by default stored in a privileged location; if your ENIGMA instance is not running as root (which it should not be!), youll need to copy the SSL certificate somewhere else in order for ENIGMA to use it.</p>
</blockquote>
<h2 id="static-routes">Static Routes</h2>
<p>Static files live relative to the <code class="language-plaintext highlighter-rouge">contentServers.web.staticRoot</code> path which defaults to <code class="language-plaintext highlighter-rouge">enigma-bbs/www</code>.</p>
<p><code class="language-plaintext highlighter-rouge">index.html, favicon.ico</code>, and any error pages like <code class="language-plaintext highlighter-rouge">404.html</code> are accessible from the route path. Other static assets hosted by the web server must be referenced from <code class="language-plaintext highlighter-rouge">/static/</code>, for example:</p>
<div class="language-html highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;a</span> <span class="na">href=</span><span class="s">"/static/about.html"</span><span class="nt">&gt;</span> Example Link
</code></pre></div></div>
<h2 id="custom-error-pages">Custom Error Pages</h2>
<p>Customized error pages can be created for <a href="https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error">HTTP error codes</a> by providing a <code class="language-plaintext highlighter-rouge">&lt;error_code&gt;.html</code> file in the <em>static routes</em> area. For example: <code class="language-plaintext highlighter-rouge">404.html</code>.</p>
</div>
<div class="PageNavigation">
<a class="btn" style="float:left;margin-right: 20px;" href="/enigma-bbs/servers/loginservers/websocket.html">« Web Socket / Web Interface Server</a>
<a class="btn" style="float: right;margin-left: 20px" href="/enigma-bbs/servers/contentservers/gopher.html">Gopher Server »</a>
<br clear="both">
</div>
</section>
</div>
</div>
</div>
</body>
</html>