path: root/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml

<?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>