aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml
blob: 0778aeed44ae06767547c230a4f1566dd9f01b29 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
  <title>The Website</title>

  <para>The &os; web site is part of the &os; documents.  Files for
    the web site are stored in the
    <filename>en_US.ISO8859-1/htdocs</filename> subdirectory of the
    document tree directory, <filename>~/doc</filename> in this
    example.</para>

  <sect1 xml:id="the-website-env">
    <title>Environment Variables</title>

    <para>Several environment variables control which parts of the
      web site are built or installed, and to which
      directories.</para>

    <tip>
      <para>The web build system uses &man.make.1;, and considers
	variables to be set when they have been defined, even if they
	are empty.  The examples here show the recommended ways of
	defining and using these variables.  Setting or defining these
	variables with other values or methods might lead to
	unexpected surprises.</para>
    </tip>

    <variablelist>
      <varlistentry xml:id="the-website-env-destdir">
	<term><varname>DESTDIR</varname></term>

	<listitem>
	  <para>DESTDIR specifies the path where the web site files
	    are to be installed.</para>

	  <para>This variable is best set with &man.env.1; or the user
	    shell's method of setting environment variables,
	    <command>setenv</command> for &man.csh.1; or
	    <command>export</command> for &man.sh.1;.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <variablelist>
      <varlistentry xml:id="the-website-env-englishonly">
	<term><varname>ENGLISH_ONLY</varname></term>

	<listitem>
	  <para>Default: undefined.  Build and include all
	    translations.</para>

	  <para><userinput>ENGLISH_ONLY=yes</userinput>: use only
	    the English documents and ignore all translations.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="the-website-env-webonly">
	<term><varname>WEB_ONLY</varname></term>

	<listitem>
	  <para>Default: undefined.  Build both the web site
	    and all the books and articles.</para>

	  <para><userinput>WEB_ONLY=yes</userinput>: build or install
	    only <acronym>HTML</acronym> pages from the
	    <filename>en_US.ISO8859-1/htdocs</filename> directory.
	    Other directories and documents, including books and
	    articles, will be ignored.</para>
	</listitem>
      </varlistentry>

      <varlistentry xml:id="the-website-env-weblang">
	<term><varname>WEB_LANG</varname></term>

	<listitem>
	  <para>Default: undefined.  Build and include all the
	    available languages on the web site.</para>

	  <para>Set to a space-separated list of languages to be
	    included in the build
	    or install.  The formats are the same as the directory
	    names in the document root directory.  For example, to
	    include the German and French documents:</para>

	  <screen><userinput>WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"</userinput></screen>
	</listitem>
      </varlistentry>
    </variablelist>

    <para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
      and <varname>ENGLISH_ONLY</varname> are &man.make.1; variables
      and can be set in <filename>/etc/make.conf</filename>,
      <filename>Makefile.inc</filename>, as environment variables on
      the command line, or in dot files.</para>
  </sect1>

  <sect1 xml:id="the-website-build">
    <title>Building and Installing the Web Pages</title>

    <para>Having obtained the documentation and web site source files,
      the web site can be built.</para>

    <para>An actual installation of the web site is run as the <systemitem class="username">root</systemitem>
      user because the permissions on the web server directory will
      not allow files to be installed by an unprivileged user.
      For testing, it can be useful to install the files as a normal
      user to a temporary directory.</para>

    <para>In these examples, the web site files are built by user
      <systemitem class="username">jru</systemitem> in their home
      directory, <filename>~/doc</filename>, with a full path of
      <filename>/usr/home/jru/doc</filename>.</para>

    <tip>
      <para>The web site build uses the <filename>INDEX</filename>
	from the Ports Collection and might fail if that file or
	<filename>/usr/ports</filename> is not
	present.  The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
	Collection</link>.</para>
    </tip>

    <example xml:id="the-website-examples-build">
      <title>Build the Full Web Site and All Documents</title>

      <para>Build the web site and all documents.  The resulting files
	are left in the document tree:</para>

      <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
&prompt.user; <userinput>make all</userinput></screen>
    </example>

    <example xml:id="the-website-examples-buildinstall-englishonly">
      <title>Build Only the Web Site in English</title>

      <para>Build the web site only, in English, as user
	<systemitem class="username">jru</systemitem>, and install
	the resulting files into <filename>/tmp/www</filename> for
	testing:</para>

      <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs/</userinput>
&prompt.user; <userinput>env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install</userinput></screen>

      <para>Changes to static files can usually be tested by viewing
	the modified files directly with a web browser.  If the site
	has been built as shown above, a modified main page can be
	viewed with:</para>

      <screen>&prompt.user; <userinput>firefox /tmp/www/data/index.html</userinput></screen>

      <para>Modifications to dynamic files can be tested with a web
	server running on the local system.  After building the site
	as shown above, this
	<filename>/usr/local/etc/apache24/httpd.conf</filename> can be
	used with <package>www/apache24</package>:</para>

      <programlisting># httpd.conf for testing the FreeBSD website
Define TestRoot "/tmp/www/data"

# directory for configuration files
ServerRoot "/usr/local"

Listen 80

# minimum required modules
LoadModule authz_core_module libexec/apache24/mod_authz_core.so
LoadModule mime_module libexec/apache24/mod_mime.so
LoadModule unixd_module libexec/apache24/mod_unixd.so
LoadModule cgi_module libexec/apache24/mod_cgi.so
LoadModule dir_module libexec/apache24/mod_dir.so

# run the webserver as user and group
User www
Group www

ServerAdmin you@example.com
ServerName fbsdtest

# deny access to all files
&lt;Directory /&gt;
    AllowOverride none
    Require all denied
&lt;/Directory&gt;

# allow access to the website directory
DocumentRoot "${TestRoot}"
&lt;Directory "${TestRoot}"&gt;
    Options Indexes FollowSymLinks
    AllowOverride None
    Require all granted
&lt;/Directory&gt;

# prevent access to .htaccess and .htpasswd files
&lt;Files ".ht*"&gt;
    Require all denied
&lt;/Files&gt;

ErrorLog "/var/log/httpd-error.log"
LogLevel warn

# set up the CGI script directory
&lt;Directory "${TestRoot}/cgi"&gt;
    AllowOverride None
    Options None
    Require all granted
    Options +ExecCGI
    AddHandler cgi-script .cgi
&lt;/Directory&gt;

Include etc/apache24/Includes/*.conf</programlisting>

      <para>Start the web server with</para>

      <screen>&prompt.root; <userinput>service apache24 onestart</userinput></screen>

      <para>The	web site can be viewed at
	<link xlink:href="http://localhost"/>.  Be aware that many
	links refer to the real &os; site by name, and those links
	will still go to the external site instead of the local test
	version.  Fully testing the local site will require
	temporarily setting <acronym>DNS</acronym> so
	<literal>www.FreeBSD.org</literal> resolves to
	<literal>localhost</literal> or the local
	<acronym>IP</acronym> address.</para>
    </example>

    <example xml:id="the-website-examples-buildinstall">
      <title>Build and Install the Web Site</title>

      <para>Build the web site and all documents as user
	<systemitem class="username">jru</systemitem>.  Install the
	resulting files as
	<systemitem class="username">root</systemitem> into the
	default directory,
	<filename>/root/public_html</filename>:</para>

      <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.user; <userinput>make all</userinput>
&prompt.user; <userinput>su -</userinput>
Password:
&prompt.root; <userinput>cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.root; <userinput>make install</userinput></screen>
    </example>

    <para>The install process does not delete any old or outdated
      files that existed previously in the same directory.  If a new
      copy of the site is built and installed every day, this command
      will find and delete all files that have not been updated in
      three days:</para>

    <screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -delete</userinput></screen>
  </sect1>
</chapter>