Fossil SCM

fossil-scm / www / server / windows / iis.md
Source Blame History 134 lines
f146e21… drh 1 # Serving via IIS
f146e21… drh 2
f146e21… drh 3 ## Why Bother?
f146e21… drh 4
f146e21… drh 5 The first part of the scheme below sets Fossil up as an HTTP server, so
f146e21… drh 6 you might be wondering why you wouldn’t just modify that to make it
f146e21… drh 7 listen on all network interfaces on TCP port 80, so you can avoid the
f146e21… drh 8 need for IIS entirely. For simple use cases, you can indeed do without
f146e21… drh 9 IIS, but there are several use cases where adding it is helpful:
f146e21… drh 10
f146e21… drh 11 1. Proxying Fossil with IIS lets you [add TLS encryption][tls], which
f146e21… drh 12 [Fossil does not currently speak](../../ssl.wiki) in its server role.
f146e21… drh 13
f146e21… drh 14 2. The URL rewriting we do below allows Fossil to be part of a larger
f146e21… drh 15 site already being served with IIS.
f146e21… drh 16
f146e21… drh 17 3. You can have a mixed-mode site, with Fossil acting as a powerful
f146e21… drh 18 dynamic content management service and IIS as a fast static content
f146e21… drh 19 server. The pure-Fossil alternative requires that you check all of
f146e21… drh 20 your static content into Fossil as versioned or unversioned
f146e21… drh 21 artifacts.
f146e21… drh 22
f146e21… drh 23 This article shows how you can get any combination of those benefits by
f146e21… drh 24 using IIS as a reverse proxy for `fossil server`.
f146e21… drh 25
f146e21… drh 26 There are other ways to use IIS to serve Fossil, such as [via
f146e21… drh 27 CGI](./cgi.md).
f146e21… drh 28
f146e21… drh 29
f146e21… drh 30 ## Background Fossil Service Setup
f146e21… drh 31
f146e21… drh 32 You will need to have the Fossil HTTP server running in the background,
f146e21… drh 33 serving some local repository, bound to localhost on a fixed
f146e21… drh 34 high-numbered TCP port. For the purposes of testing, simply start it by
f146e21… drh 35 hand in your command shell of choice:
f146e21… drh 36
8a1ba49… wyoung 37 fossil serve --port 9000 --localhost repo.fossil
f146e21… drh 38
f146e21… drh 39 That command assumes you’ve got `fossil.exe` in your `%PATH%` and you’re
f146e21… drh 40 in a directory holding `repo.fossil`. See [the platform-independent
f146e21… drh 41 instructions](../any/none.md) for further details.
f146e21… drh 42
f146e21… drh 43 For a more robust setup, we recommend that you [install Fossil as a
f146e21… drh 44 Windows service](./service.md), which will allow Fossil to start at
f146e21… drh 45 system boot, before anyone has logged in interactively.
f146e21… drh 46
f146e21… drh 47
93cee1f… wyoung 48 ## <a id="install"></a>Install IIS
f146e21… drh 49
f146e21… drh 50 IIS might not be installed in your system yet, so follow the path
f146e21… drh 51 appropriate to your host OS. We’ve tested only the latest Microsoft
f146e21… drh 52 OSes as of the time of this writing, but the basic process should be
f146e21… drh 53 similar on older OSes.
f146e21… drh 54
f146e21… drh 55
f146e21… drh 56 ### Windows Server 2019
f146e21… drh 57
f146e21… drh 58 1. Start “Server Manager”
f146e21… drh 59 2. Tell it you want to “Add roles and features”
f146e21… drh 60 3. Select “Role-based or feature-based installation”
f146e21… drh 61 4. Select your local server
f146e21… drh 62 5. In the Server Roles section, enable “Web Server (IIS)”
f146e21… drh 63
fd1282e… drh 64 ### Windows
f146e21… drh 65
f146e21… drh 66 1. Open Control Panel
f146e21… drh 67 2. Go to “Programs”
f146e21… drh 68 3. Select “Turn Windows features on or off” in the left-side pane
f146e21… drh 69 4. In the “Windows Features” dialog, enable “Internet Information
f146e21… drh 70 Services”
f146e21… drh 71
f146e21… drh 72 The default set of IIS features there will suffice for this tutorial,
f146e21… drh 73 but you might want to enable additional features.
f146e21… drh 74
f146e21… drh 75
f146e21… drh 76 ## Setting up the Proxy
f146e21… drh 77
f146e21… drh 78 The stock IIS setup doesn’t have reverse proxying features, but they’re
f146e21… drh 79 easily added through extensions. You will need to install the
f146e21… drh 80 [Application Request Routing][arr] and [URL Rewrite][ure] extensions. In
f146e21… drh 81 my testing here, URL Rewrite showed up immediately after installing it,
f146e21… drh 82 but I had to reboot the server to get ARR to show up. (Yay Windows.)
f146e21… drh 83
f146e21… drh 84 You can install these things through the direct links above, or you can
f146e21… drh 85 do it via the Web Platform Installer feature of IIS Manager (a.k.a.
f146e21… drh 86 `INETMGR`).
f146e21… drh 87
f146e21… drh 88 Set these extensions up in IIS Manager like so:
f146e21… drh 89
f146e21… drh 90 1. Double-click the “Application Request Routing Cache” icon.
f146e21… drh 91
f146e21… drh 92 2. Right-click in the window that results, and select “Server Proxy
f146e21… drh 93 Settings...”
f146e21… drh 94
f146e21… drh 95 3. Check the “Enable Proxy” box in the dialog. Click the “Apply” text
f146e21… drh 96 in the right-side pane.
f146e21… drh 97
f146e21… drh 98 4. Return to the top server-level configuration area of IIS Manager and
f146e21… drh 99 double-click the “URL Rewrite” icon. Alternately, you might find
f146e21… drh 100 “URL Rewrite” in the right-side pane from within the ARR settings.
f146e21… drh 101
f146e21… drh 102 5. Right click in the window that results, and click “Add Rule(s)...”
f146e21… drh 103 Tell it you want a “Blank rule” under “Inbound rules”.
f146e21… drh 104
f146e21… drh 105 6. In the dialog that results, create a new rule called “Fossil repo
f146e21… drh 106 proxy.” Set the “Pattern” to “`^(.*)$`” and “Rewrite URL” set to
f146e21… drh 107 “`http://localhost:9000/{R:1}`”. That tells it to take everything in
f146e21… drh 108 the path part of the URL and send it down to localhost:9000, where
f146e21… drh 109 `fossil server` is listening.
f146e21… drh 110
f146e21… drh 111 7. Click “Apply” in the right-side pane, then get back to the top level
f146e21… drh 112 configuration for the server, and click “Restart” in that same pane.
f146e21… drh 113
f146e21… drh 114 At this point, if you go to `http://localhost/` in your browser, you
f146e21… drh 115 should see your Fossil repository’s web interface instead of the default
f146e21… drh 116 IIS web site, as before you did all of the above.
f146e21… drh 117
f146e21… drh 118 This is a very simple configuration. You can do more complicated and
f146e21… drh 119 interesting things with this, such as redirecting only `/code` URLs to
f146e21… drh 120 Fossil by setting the Pattern in step 6 to “`^/code(.*)$`”. (You would
f146e21… drh 121 also need to pass `--baseurl http://example.com/code` in the `fossil
f146e21… drh 122 server` command to make this work properly.) IIS would then directly
f146e21… drh 123 serve all other URLs. You could also intermix ASP.NET applications in
f146e21… drh 124 the URL scheme in this way.
f146e21… drh 125
f146e21… drh 126 See the documentation on [URL Rewrite rules][urr] for more ideas.
f146e21… drh 127
f146e21… drh 128 *[Return to the top-level Fossil server article.](../)*
f146e21… drh 129
f146e21… drh 130
f146e21… drh 131 [arr]: https://www.iis.net/downloads/microsoft/application-request-routing
f146e21… drh 132 [tls]: https://docs.microsoft.com/en-us/iis/manage/configuring-security/understanding-iis-url-authorization
f146e21… drh 133 [ure]: https://www.iis.net/downloads/microsoft/url-rewrite
f146e21… drh 134 [urr]: https://docs.microsoft.com/en-us/iis/extensions/url-rewrite-module/creating-rewrite-rules-for-the-url-rewrite-module

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button