Index: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 49810) +++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml (revision 49811) @@ -1,282 +1,282 @@ The Website The &os; web site is part of the &os; documents. Files for the web site are stored in the en_US.ISO8859-1/htdocs subdirectory of the document tree directory, ~/doc in this example. Environment Variables - Several environment variables control which parts of the the + Several environment variables control which parts of the web site are built or installed, and to which directories. 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. DESTDIR DESTDIR specifies the path where the web site files are to be installed. This variable is best set with &man.env.1; or the user shell's method of setting environment variables, setenv for &man.csh.1; or export for &man.sh.1;. ENGLISH_ONLY Default: undefined. Build and include all translations. ENGLISH_ONLY=yes: use only the English documents and ignore all translations. WEB_ONLY Default: undefined. Build both the web site and all the books and articles. WEB_ONLY=yes: build or install only HTML pages from the en_US.ISO8859-1/htdocs directory. Other directories and documents, including books and articles, will be ignored. WEB_LANG Default: undefined. Build and include all the available languages on the web site. 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: WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1" WEB_ONLY, WEB_LANG, and ENGLISH_ONLY are &man.make.1; variables and can be set in /etc/make.conf, Makefile.inc, as environment variables on the command line, or in dot files. Building and Installing the Web Pages Having obtained the documentation and web site source files, the web site can be built. An actual installation of the web site is run as the root 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. In these examples, the web site files are built by user jru in their home directory, ~/doc, with a full path of /usr/home/jru/doc. The web site build uses the INDEX from the Ports Collection and might fail if that file or /usr/ports is not present. The simplest approach is to install the Ports Collection. Build the Full Web Site and All Documents Build the web site and all documents. The resulting files are left in the document tree: &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs/ &prompt.user; make all Build Only the Web Site in English Build the web site only, in English, as user jru, and install the resulting files into /tmp/www for testing: &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs/ &prompt.user; env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install 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: &prompt.user; firefox /tmp/www/data/index.html Modifications to dynamic files can be tested with a web server running on the local system. After building the site as shown above, this /usr/local/etc/apache24/httpd.conf can be used with www/apache24: # 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 <Directory /> AllowOverride none Require all denied </Directory> # allow access to the website directory DocumentRoot "${TestRoot}" <Directory "${TestRoot}"> Options Indexes FollowSymLinks AllowOverride None Require all granted </Directory> # prevent access to .htaccess and .htpasswd files <Files ".ht*"> Require all denied </Files> ErrorLog "/var/log/httpd-error.log" LogLevel warn # set up the CGI script directory <Directory "${TestRoot}/cgi"> AllowOverride None Options None Require all granted Options +ExecCGI AddHandler cgi-script .cgi </Directory> Include etc/apache24/Includes/*.conf Start the web server with &prompt.root; service apache24 onestart The web site can be viewed at . 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 DNS so www.FreeBSD.org resolves to localhost or the local IP address. Build and Install the Web Site Build the web site and all documents as user jru. Install the resulting files as root into the default directory, /root/public_html: &prompt.user; cd ~/doc/en_US.ISO8859-1/htdocs &prompt.user; make all &prompt.user; su - Password: &prompt.root; cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs &prompt.root; make install 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: &prompt.root; find /usr/local/www -ctime 3 -delete