Fossil SCM

Merge in documentation enhancements from trunk.

drh 2019-08-27 00:29 vdiff-improvements merge

Commit c1b62c32602179d24892a454d92e4ec5a8dbcda912769d5c791473afcec2311e

Parent 2078c746a5abb9e…

2 files changed +35 -21 +63 -68

~ www/server/any/scgi.md ~ www/server/debian/nginx.md

M www/server/any/scgi.md

+35 -21

		--- www/server/any/scgi.md
		+++ www/server/any/scgi.md
		@@ -9,20 +9,30 @@
9	9	This can be used with a web server such as [nginx](http://nginx.org)
10	10	which does not support [Fossil’s CGI mode](./cgi.md).
11	11
12	12	A basic nginx configuration to support SCGI with Fossil looks like this:
13	13
14		- location /example/ {
	14	+ location /code/ {
15	15	include scgi_params;
	16	+ scgi_param SCRIPT_NAME "/code";
16	17	scgi_pass localhost:9000;
17		- scgi_param SCRIPT_NAME "/example";
18		- scgi_param HTTPS "on";
19	18	}
20	19
21		-Start Fossil so that it will respond to nginx’s SCGI calls like this:
	20	+The `scgi_params` file comes with nginx, and it simply translates nginx
	21	+internal variables to `scgi_param` directives to create SCGI environment
	22	+variables for the proxied program; in this case, Fossil. Our explicit
	23	+`scgi_param` call to define `SCRIPT_NAME` adds one more variable to this
	24	+set, which is necessary for this configuration to work properly, because
	25	+our repo isn’t at the root of the URL hierarchy. Without it, when Fossil
	26	+generates absolute URLs, they’ll be missing the `/code` part at the
	27	+start, which will typically cause [404 errors][404].
	28	+
	29	+The final directive simply tells nginx to proxy all calls to URLs under
	30	+`/code` down to an SCGI program on TCP port 9000. We can temporarily
	31	+set Fossil up as a server on that port like so:
22	32
23		- fossil server /path/to/repo.fossil --scgi --localhost --port 9000
	33	+ $ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 &
24	34
25	35	The `--scgi` option switches Fossil into SCGI mode from its default,
26	36	which is [stand-alone HTTP server mode](./none.md). All of the other
27	37	options discussed in that linked document — such as the ability to serve
28	38	a directory full of Fossil repositories rather than just a single
		@@ -34,23 +44,27 @@
34	44
35	45	Giving an explicit non-default TCP port number via `--port` is a good
36	46	idea to avoid conflicts with use of Fossil’s default TCP service port,
37	47	8080, which may conflict with local uses of `fossil ui` and such.
38	48
39		-Fossil requires the `SCRIPT_NAME` environment variable in order to
40		-function properly, but nginx does not provide this variable by default,
41		-so it is necessary to provide it in the configuration. Failure to do
42		-this will cause Fossil to return an error.
43		-
44		-The [example `fslsrv` script](/file/tools/fslsrv) shows off these same
45		-concepts in a more complicated setting. You might want to mine that
46		-script for ideas.
47		-
48		-You might want to next read one of the platform-specific versions of this
49		-document, which goes into more detail:
50		-
51		-* [Debian/Ubuntu](../debian/nginx.md)
52		-
53		-There is a [separate article](../../tls-nginx.md) showing how to add TLS
54		-encryption to this basic SCGI + nginx setup.
	49	+We characterized the SCGI service start command above as “temporary”
	50	+because running Fossil in the background like that means it won’t start
	51	+back up on a reboot of the server. A simple solution to that is to add
	52	+that command to `/etc/rc.local` on systems that have it. However, you
	53	+might want to consider setting Fossil up as an OS service instead, so
	54	+that you get the benefits of the platform’s service management
	55	+framework:
	56	+
	57	+* [Linux (systemd)](../debian/service.md)
	58	+* [Windows service](../windows/service.md)
	59	+* [macOS (launchd)](../macos/service.md)
	60	+* [xinetd](../any/xinetd.md)
	61	+* [inetd](../any/inetd.md)
	62	+
	63	+We go into more detail on nginx service setup with Fossil in our
	64	+[Debian/Ubuntu specific guide](../debian/nginx.md). Then in [a later
	65	+article](../../tls-nginx.md) that builds upon that, we show how to add
	66	+TLS encryption to this basic SCGI + nginx setup on Debian type OSes.
55	67
56	68	[Return to the top-level Fossil server article.](../)
	69	+
	70	+[404]: https://en.wikipedia.org/wiki/HTTP_404
57	71

	--- www/server/any/scgi.md
	+++ www/server/any/scgi.md
	@@ -9,20 +9,30 @@
9	This can be used with a web server such as [nginx](http://nginx.org)
10	which does not support [Fossil’s CGI mode](./cgi.md).
11
12	A basic nginx configuration to support SCGI with Fossil looks like this:
13
14	location /example/ {
15	include scgi_params;

16	scgi_pass localhost:9000;
17	scgi_param SCRIPT_NAME "/example";
18	scgi_param HTTPS "on";
19	}
20
21	Start Fossil so that it will respond to nginx’s SCGI calls like this:











22
23	fossil server /path/to/repo.fossil --scgi --localhost --port 9000
24
25	The `--scgi` option switches Fossil into SCGI mode from its default,
26	which is [stand-alone HTTP server mode](./none.md). All of the other
27	options discussed in that linked document — such as the ability to serve
28	a directory full of Fossil repositories rather than just a single
	@@ -34,23 +44,27 @@
34
35	Giving an explicit non-default TCP port number via `--port` is a good
36	idea to avoid conflicts with use of Fossil’s default TCP service port,
37	8080, which may conflict with local uses of `fossil ui` and such.
38
39	Fossil requires the `SCRIPT_NAME` environment variable in order to
40	function properly, but nginx does not provide this variable by default,
41	so it is necessary to provide it in the configuration. Failure to do
42	this will cause Fossil to return an error.
43
44	The [example `fslsrv` script](/file/tools/fslsrv) shows off these same
45	concepts in a more complicated setting. You might want to mine that
46	script for ideas.
47
48	You might want to next read one of the platform-specific versions of this
49	document, which goes into more detail:
50
51	* [Debian/Ubuntu](../debian/nginx.md)
52
53	There is a [separate article](../../tls-nginx.md) showing how to add TLS
54	encryption to this basic SCGI + nginx setup.


55
56	[Return to the top-level Fossil server article.](../)


57

	--- www/server/any/scgi.md
	+++ www/server/any/scgi.md
	@@ -9,20 +9,30 @@
9	This can be used with a web server such as [nginx](http://nginx.org)
10	which does not support [Fossil’s CGI mode](./cgi.md).
11
12	A basic nginx configuration to support SCGI with Fossil looks like this:
13
14	location /code/ {
15	include scgi_params;
16	scgi_param SCRIPT_NAME "/code";
17	scgi_pass localhost:9000;


18	}
19
20	The `scgi_params` file comes with nginx, and it simply translates nginx
21	internal variables to `scgi_param` directives to create SCGI environment
22	variables for the proxied program; in this case, Fossil. Our explicit
23	`scgi_param` call to define `SCRIPT_NAME` adds one more variable to this
24	set, which is necessary for this configuration to work properly, because
25	our repo isn’t at the root of the URL hierarchy. Without it, when Fossil
26	generates absolute URLs, they’ll be missing the `/code` part at the
27	start, which will typically cause [404 errors][404].
28
29	The final directive simply tells nginx to proxy all calls to URLs under
30	`/code` down to an SCGI program on TCP port 9000. We can temporarily
31	set Fossil up as a server on that port like so:
32
33	$ fossil server /path/to/repo.fossil --scgi --localhost --port 9000 &
34
35	The `--scgi` option switches Fossil into SCGI mode from its default,
36	which is [stand-alone HTTP server mode](./none.md). All of the other
37	options discussed in that linked document — such as the ability to serve
38	a directory full of Fossil repositories rather than just a single
	@@ -34,23 +44,27 @@
44
45	Giving an explicit non-default TCP port number via `--port` is a good
46	idea to avoid conflicts with use of Fossil’s default TCP service port,
47	8080, which may conflict with local uses of `fossil ui` and such.
48
49	We characterized the SCGI service start command above as “temporary”
50	because running Fossil in the background like that means it won’t start
51	back up on a reboot of the server. A simple solution to that is to add
52	that command to `/etc/rc.local` on systems that have it. However, you
53	might want to consider setting Fossil up as an OS service instead, so
54	that you get the benefits of the platform’s service management
55	framework:
56
57	* [Linux (systemd)](../debian/service.md)
58	* [Windows service](../windows/service.md)
59	* [macOS (launchd)](../macos/service.md)
60	* [xinetd](../any/xinetd.md)
61	* [inetd](../any/inetd.md)
62
63	We go into more detail on nginx service setup with Fossil in our
64	[Debian/Ubuntu specific guide](../debian/nginx.md). Then in [a later
65	article](../../tls-nginx.md) that builds upon that, we show how to add
66	TLS encryption to this basic SCGI + nginx setup on Debian type OSes.
67
68	[Return to the top-level Fossil server article.](../)
69
70	[404]: https://en.wikipedia.org/wiki/HTTP_404
71

M www/server/debian/nginx.md

+63 -68

		--- www/server/debian/nginx.md
		+++ www/server/debian/nginx.md
		@@ -66,15 +66,15 @@
66	66
67	67	Fossil provides four major ways to access a repository it’s serving
68	68	remotely, three of which are straightforward to use with nginx:
69	69
70	70	* HTTP — Fossil has a built-in HTTP server: [`fossil
71		- server`](/help/server). While this method is efficient and it’s
72		- possible to use nginx to proxy access to another HTTP server, this
73		- option is overkill for our purposes. nginx is itself a fully
74		- featured HTTP server, so we will choose in this guide not to make
75		- nginx reinterpret Fossil’s implementation of HTTP.
	71	+ server`](../any/none.md). While this method is efficient and it’s
	72	+ possible to use nginx to proxy access to another HTTP server, we
	73	+ don’t see any particularly good reason to make nginx reinterpret
	74	+ Fossil’s own implementation of HTTP when we have a better option.
	75	+ (But see [below](#http).)
76	76
77	77	* CGI — This method is simple but inefficient, because it launches
78	78	a separate Fossil instance on every HTTP hit.
79	79
80	80	Since Fossil is a relatively small self-contained program, and it’s
		@@ -107,103 +107,74 @@
107	107	$ sudo apt install fossil nginx
108	108
109	109
110	110	## <a name="scgi"></a>Running Fossil in SCGI Mode
111	111
112		-I run my Fossil SCGI server instances with a variant of [the `fslsrv`
113		-shell script](/file/tools/fslsrv) currently hosted in the Fossil source
114		-code repository. You’ll want to download that and make a copy of it, so
115		-you can customize it to your particular needs.
116		-
117		-This script allows running multiple Fossil SCGI servers, one per
118		-repository, each bound to a different high-numbered `localhost` port, so
119		-that only nginx can see and proxy them out to the public. The
120		-“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
121		-on localhost:12346.
122		-
123		-As written, the `fslsrv` script expects repositories to be stored in the
124		-calling user’s home directory under `~/museum`, because where else do
125		-you keep Fossils?
126		-
127		-That home directory also needs to have a directory to hold log files,
128		-`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
129		-does, it’s better to have it captured than to need to re-create the
130		-problem after the fact.
131		-
132		-The use of `--baseurl` in this script lets us have each Fossil
133		-repository mounted in a different location in the URL scheme. Here, for
134		-example, we’re saying that the “`example`” repository is hosted under
135		-the `/code` URI on its domains, but that the “`foo`” repo is hosted at
136		-the top level of its domain. You’ll want to do something like the
137		-former for a Fossil repo that’s just one piece of a larger site, but the
138		-latter for a repo that is basically the whole point of the site.
139		-
140		-You might also want another script to automate the update, build, and
141		-deployment steps for new Fossil versions:
142		-
143		- #!/bin/sh
144		- cd $HOME/src/fossil/trunk
145		- fossil up
146		- make -j11
147		- killall fossil
148		- sudo make install
149		- fslsrv
150		-
151		-The `killall fossil` step is needed only on OSes that refuse to let you
152		-replace a running binary on disk.
153		-
154		-As written, the `fslsrv` script assumes a Linux environment. It expects
155		-`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
156		-It should not be difficult to port to systems like macOS or the BSDs.
	112	+For the following nginx configuration to work, it needs to contact a
	113	+Fossil instance speaking the SCGI protocol. There are [many ways](../)
	114	+to set that up. For Debian type systems, we primarily recommend
	115	+following [our systemd user service guide](service.md).
	116	+
	117	+Another option would be to customize [the `fslsrv` shell
	118	+script](/file/tools/fslsrv) that ships with Fossil as an example of
	119	+launching multiple Fossil instances in the background to serve multiple
	120	+URLs.
	121	+
	122	+However you do it, you need to match up the TCP port numbers between it
	123	+and those in the nginx configuration below.
157	124
158	125
159	126	## <a name="config"></a>Configuration
160	127
161	128	On Debian and Ubuntu systems the primary user-level configuration file
162	129	for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this
163	130	file contain only a list of include statements, one for each site that
164	131	server hosts:
165	132
166		- include local/example
167		- include local/foo
	133	+ include local/example.com
	134	+ include local/foo.net
168	135
169	136	Those files then each define one domain’s configuration. Here,
170		-`/etc/nginx/local/example` contains the configuration for
171		-`.example.com` and `.example.net`; and `local/foo` contains the
172		-configuration for `*.foo.net`.
	137	+`/etc/nginx/local/example.com` contains the configuration for
	138	+`.example.com` and its alias `.example.net`; and `local/foo.net`
	139	+contains the configuration for `*.foo.net`.
173	140
174		-The configuration for our `foo.net` web site, stored in
175		-`/etc/nginx/sites-enabled/local/foo` is:
	141	+The configuration for our `example.com` web site, stored in
	142	+`/etc/nginx/sites-enabled/local/example.com` is:
176	143
177	144	server {
178		- server_name .foo.net;
	145	+ server_name .example.com .example.net "";
179	146	include local/generic;
180	147
181		- access_log /var/log/nginx/foo.net-https-access.log;
182		- error_log /var/log/nginx/foo.net-https-error.log;
	148	+ access_log /var/log/nginx/example.com-https-access.log;
	149	+ error_log /var/log/nginx/example.com-https-error.log;
183	150
184		- # Bypass Fossil for the static Doxygen docs
185		- location /doc/html {
186		- root /var/www/foo.net;
	151	+ # Bypass Fossil for the static documentation generated from
	152	+ # our source code by Doxygen, so it merges into the embedded
	153	+ # doc URL hierarchy at Fossil’s $ROOT/doc without requiring that
	154	+ # these generated files actually be stored in the repo. This
	155	+ # also lets us set aggressive caching on these docs, since
	156	+ # they rarely change.
	157	+ location /code/doc/html {
	158	+ root /var/www/example.com/code/doc/html;
187	159
188	160	location ~* \.(html\|ico\|css\|js\|gif\|jpg\|png)$ {
189	161	expires 7d;
190	162	add_header Vary Accept-Encoding;
191	163	access_log off;
192	164	}
193	165	}
194	166
195	167	# Redirect everything else to the Fossil instance
196		- location / {
	168	+ location /code {
197	169	include scgi_params;
	170	+ scgi_param SCRIPT_NAME "/code";
198	171	scgi_pass 127.0.0.1:12345;
199		- scgi_param HTTPS "on";
200		- scgi_param SCRIPT_NAME "";
201	172	}
202	173	}
203	174
204		-As you can see, this is a simple extension of [the basic nginx service
	175	+As you can see, this is a pure extension of [the basic nginx service
205	176	configuration for SCGI][scgii], showing off a few ideas you might want to
206	177	try on your own site, such as static asset proxying.
207	178
208	179	The `local/generic` file referenced above helps us reduce unnecessary
209	180	repetition among the multiple sites this configuration hosts:
		@@ -221,10 +192,34 @@
221	192	the `access_log` and `error_log` directives, which follow an obvious
222	193	pattern from one host to the next. Sadly, you must tolerate some
223	194	repetition across `server { }` blocks when setting up multiple domains
224	195	on a single server.
225	196
226		-The configuration for `example.com` and `example.net` is similar.
	197	+The configuration for `foo.net` is similar.
227	198
228	199	See [the nginx docs](http://nginx.org/en/docs/) for more ideas.
229	200
	201	+
	202	+## <a name="http"></a>Proxying HTTP Anyway
	203	+
	204	+[Above](#modes), we argued that proxying SCGI is a better option than
	205	+making nginx reinterpret Fossil’s own implementation of HTTP. If you
	206	+want Fossil to speak HTTP, just [set Fossil up as a standalone
	207	+server](../any/none.md). And if you want nginx to [provide TLS
	208	+encryption for Fossil][tls], proxying HTTP instead of SCGI provides no
	209	+benefit.
	210	+
	211	+However, it is still worth showing the proper method of proxying
	212	+Fossil’s HTTP server through nginx if only to make reading nginx
	213	+documentation on other sites easier:
	214	+
	215	+ location /code {
	216	+ rewrite ^/code(/.*) $1 break;
	217	+ proxy_pass http://127.0.0.1:12345;
	218	+ }
	219	+
	220	+The most common thing people get wrong when hand-rolling a configuration
	221	+like this is to get the slashes wrong. Fossil is senstitive to this. For
	222	+instance, Fossil will not collapse double slashes down to a single
	223	+slash, as some other HTTP servers will.
	224	+
230	225	[Return to the top-level Fossil server article.](../)
231	226

	--- www/server/debian/nginx.md
	+++ www/server/debian/nginx.md
	@@ -66,15 +66,15 @@
66
67	Fossil provides four major ways to access a repository it’s serving
68	remotely, three of which are straightforward to use with nginx:
69
70	* HTTP — Fossil has a built-in HTTP server: [`fossil
71	server`](/help/server). While this method is efficient and it’s
72	possible to use nginx to proxy access to another HTTP server, this
73	option is overkill for our purposes. nginx is itself a fully
74	featured HTTP server, so we will choose in this guide not to make
75	nginx reinterpret Fossil’s implementation of HTTP.
76
77	* CGI — This method is simple but inefficient, because it launches
78	a separate Fossil instance on every HTTP hit.
79
80	Since Fossil is a relatively small self-contained program, and it’s
	@@ -107,103 +107,74 @@
107	$ sudo apt install fossil nginx
108
109
110	## <a name="scgi"></a>Running Fossil in SCGI Mode
111
112	I run my Fossil SCGI server instances with a variant of [the `fslsrv`
113	shell script](/file/tools/fslsrv) currently hosted in the Fossil source
114	code repository. You’ll want to download that and make a copy of it, so
115	you can customize it to your particular needs.
116
117	This script allows running multiple Fossil SCGI servers, one per
118	repository, each bound to a different high-numbered `localhost` port, so
119	that only nginx can see and proxy them out to the public. The
120	“`example`” repo is on TCP port localhost:12345, and the “`foo`” repo is
121	on localhost:12346.
122
123	As written, the `fslsrv` script expects repositories to be stored in the
124	calling user’s home directory under `~/museum`, because where else do
125	you keep Fossils?
126
127	That home directory also needs to have a directory to hold log files,
128	`~/log/fossil/*.log`. Fossil doesn’t put out much logging, but when it
129	does, it’s better to have it captured than to need to re-create the
130	problem after the fact.
131
132	The use of `--baseurl` in this script lets us have each Fossil
133	repository mounted in a different location in the URL scheme. Here, for
134	example, we’re saying that the “`example`” repository is hosted under
135	the `/code` URI on its domains, but that the “`foo`” repo is hosted at
136	the top level of its domain. You’ll want to do something like the
137	former for a Fossil repo that’s just one piece of a larger site, but the
138	latter for a repo that is basically the whole point of the site.
139
140	You might also want another script to automate the update, build, and
141	deployment steps for new Fossil versions:
142
143	#!/bin/sh
144	cd $HOME/src/fossil/trunk
145	fossil up
146	make -j11
147	killall fossil
148	sudo make install
149	fslsrv
150
151	The `killall fossil` step is needed only on OSes that refuse to let you
152	replace a running binary on disk.
153
154	As written, the `fslsrv` script assumes a Linux environment. It expects
155	`/bin/bash` to exist, and it depends on non-POSIX tools like `pgrep`.
156	It should not be difficult to port to systems like macOS or the BSDs.
157
158
159	## <a name="config"></a>Configuration
160
161	On Debian and Ubuntu systems the primary user-level configuration file
162	for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this
163	file contain only a list of include statements, one for each site that
164	server hosts:
165
166	include local/example
167	include local/foo
168
169	Those files then each define one domain’s configuration. Here,
170	`/etc/nginx/local/example` contains the configuration for
171	`.example.com` and `.example.net`; and `local/foo` contains the
172	configuration for `*.foo.net`.
173
174	The configuration for our `foo.net` web site, stored in
175	`/etc/nginx/sites-enabled/local/foo` is:
176
177	server {
178	server_name .foo.net;
179	include local/generic;
180
181	access_log /var/log/nginx/foo.net-https-access.log;
182	error_log /var/log/nginx/foo.net-https-error.log;
183
184	# Bypass Fossil for the static Doxygen docs
185	location /doc/html {
186	root /var/www/foo.net;





187
188	location ~* \.(html\|ico\|css\|js\|gif\|jpg\|png)$ {
189	expires 7d;
190	add_header Vary Accept-Encoding;
191	access_log off;
192	}
193	}
194
195	# Redirect everything else to the Fossil instance
196	location / {
197	include scgi_params;

198	scgi_pass 127.0.0.1:12345;
199	scgi_param HTTPS "on";
200	scgi_param SCRIPT_NAME "";
201	}
202	}
203
204	As you can see, this is a simple extension of [the basic nginx service
205	configuration for SCGI][scgii], showing off a few ideas you might want to
206	try on your own site, such as static asset proxying.
207
208	The `local/generic` file referenced above helps us reduce unnecessary
209	repetition among the multiple sites this configuration hosts:
	@@ -221,10 +192,34 @@
221	the `access_log` and `error_log` directives, which follow an obvious
222	pattern from one host to the next. Sadly, you must tolerate some
223	repetition across `server { }` blocks when setting up multiple domains
224	on a single server.
225
226	The configuration for `example.com` and `example.net` is similar.
227
228	See [the nginx docs](http://nginx.org/en/docs/) for more ideas.
229
























230	[Return to the top-level Fossil server article.](../)
231

	--- www/server/debian/nginx.md
	+++ www/server/debian/nginx.md
	@@ -66,15 +66,15 @@
66
67	Fossil provides four major ways to access a repository it’s serving
68	remotely, three of which are straightforward to use with nginx:
69
70	* HTTP — Fossil has a built-in HTTP server: [`fossil
71	server`](../any/none.md). While this method is efficient and it’s
72	possible to use nginx to proxy access to another HTTP server, we
73	don’t see any particularly good reason to make nginx reinterpret
74	Fossil’s own implementation of HTTP when we have a better option.
75	(But see [below](#http).)
76
77	* CGI — This method is simple but inefficient, because it launches
78	a separate Fossil instance on every HTTP hit.
79
80	Since Fossil is a relatively small self-contained program, and it’s
	@@ -107,103 +107,74 @@
107	$ sudo apt install fossil nginx
108
109
110	## <a name="scgi"></a>Running Fossil in SCGI Mode
111
112	For the following nginx configuration to work, it needs to contact a
113	Fossil instance speaking the SCGI protocol. There are [many ways](../)
114	to set that up. For Debian type systems, we primarily recommend
115	following [our systemd user service guide](service.md).
116
117	Another option would be to customize [the `fslsrv` shell
118	script](/file/tools/fslsrv) that ships with Fossil as an example of
119	launching multiple Fossil instances in the background to serve multiple
120	URLs.
121
122	However you do it, you need to match up the TCP port numbers between it
123	and those in the nginx configuration below.

































124
125
126	## <a name="config"></a>Configuration
127
128	On Debian and Ubuntu systems the primary user-level configuration file
129	for nginx is `/etc/nginx/sites-enabled/default`. I recommend that this
130	file contain only a list of include statements, one for each site that
131	server hosts:
132
133	include local/example.com
134	include local/foo.net
135
136	Those files then each define one domain’s configuration. Here,
137	`/etc/nginx/local/example.com` contains the configuration for
138	`.example.com` and its alias `.example.net`; and `local/foo.net`
139	contains the configuration for `*.foo.net`.
140
141	The configuration for our `example.com` web site, stored in
142	`/etc/nginx/sites-enabled/local/example.com` is:
143
144	server {
145	server_name .example.com .example.net "";
146	include local/generic;
147
148	access_log /var/log/nginx/example.com-https-access.log;
149	error_log /var/log/nginx/example.com-https-error.log;
150
151	# Bypass Fossil for the static documentation generated from
152	# our source code by Doxygen, so it merges into the embedded
153	# doc URL hierarchy at Fossil’s $ROOT/doc without requiring that
154	# these generated files actually be stored in the repo. This
155	# also lets us set aggressive caching on these docs, since
156	# they rarely change.
157	location /code/doc/html {
158	root /var/www/example.com/code/doc/html;
159
160	location ~* \.(html\|ico\|css\|js\|gif\|jpg\|png)$ {
161	expires 7d;
162	add_header Vary Accept-Encoding;
163	access_log off;
164	}
165	}
166
167	# Redirect everything else to the Fossil instance
168	location /code {
169	include scgi_params;
170	scgi_param SCRIPT_NAME "/code";
171	scgi_pass 127.0.0.1:12345;


172	}
173	}
174
175	As you can see, this is a pure extension of [the basic nginx service
176	configuration for SCGI][scgii], showing off a few ideas you might want to
177	try on your own site, such as static asset proxying.
178
179	The `local/generic` file referenced above helps us reduce unnecessary
180	repetition among the multiple sites this configuration hosts:
	@@ -221,10 +192,34 @@
192	the `access_log` and `error_log` directives, which follow an obvious
193	pattern from one host to the next. Sadly, you must tolerate some
194	repetition across `server { }` blocks when setting up multiple domains
195	on a single server.
196
197	The configuration for `foo.net` is similar.
198
199	See [the nginx docs](http://nginx.org/en/docs/) for more ideas.
200
201
202	## <a name="http"></a>Proxying HTTP Anyway
203
204	[Above](#modes), we argued that proxying SCGI is a better option than
205	making nginx reinterpret Fossil’s own implementation of HTTP. If you
206	want Fossil to speak HTTP, just [set Fossil up as a standalone
207	server](../any/none.md). And if you want nginx to [provide TLS
208	encryption for Fossil][tls], proxying HTTP instead of SCGI provides no
209	benefit.
210
211	However, it is still worth showing the proper method of proxying
212	Fossil’s HTTP server through nginx if only to make reading nginx
213	documentation on other sites easier:
214
215	location /code {
216	rewrite ^/code(/.*) $1 break;
217	proxy_pass http://127.0.0.1:12345;
218	}
219
220	The most common thing people get wrong when hand-rolling a configuration
221	like this is to get the slashes wrong. Fossil is senstitive to this. For
222	instance, Fossil will not collapse double slashes down to a single
223	slash, as some other HTTP servers will.
224
225	[Return to the top-level Fossil server article.](../)
226

Fossil SCM

Keyboard Shortcuts