> pictools > doc > setup
> pictools > doc > setup
Pictools: Building Sites and Pages
V3.3 (342)
1. Setup
Installing Pictools and setting initial properties

This page elaborates on the steps in INSTALL.html.

To use Pictools you will have to deal with Windows and Cygwin, the distribution of Unix for Windows. You will need to know how to create and navigate through Unix directories with bash or tcsh. And what it means to run "make". If you lack these capabilities, do not use Pictools. It will also be useful to have previously seen some HTMLCSS, javascript, and PHP code. Much useful information about running a site is available at http://www.thesitewizard.com.

1. Load tools to your local computer where you will edit webpages for your site. See tools.php for needed tools.

2. Hosting. Generally one organization will both register your site name and host the site's files. Google "website hosting". Free web hosting is worth what you pay for it. Competent hosting can be had for a little over a hundred dollars per year. In 2015, good host service comparisons were published in PC Magazine and PC World. Physpics is hosted at DreamHost.com; they do a good job.  See thesitewizard for criteria in choosing a hosting service. A plethora of reviews resides at whoishostingthis.

Pictools requires "ssh" access, not just "ftp" access. With ftp you are limited to transferring files back and forth. With ssh access, you can execute programs on the host computer. An even higher level of service is your own virtual server. With this you can control an entire computer. You may not want to learn everything that entails. Pictools also requires that PHP be running on the server. Version 5.4 or later should suffice. For serving some files, Pictools requires that the server support xsendfile; at DreamHost you have to request that this be enabled.

Be sure to get from the hosting company several items:

item symbolic name sample value
name of your site sitename physpics.com
login name of the user managing the site username physpics
password for the above user password gib3erI%
subdirectory of user login containing site pages pagesdir httpdocs

When a symbolic name appears below, replace it with whatever the value from the hosting company.

More about pagesdir. When the site manager logs in with username and password, the initial current directory will be that user's home directory. The pages corresponding to pages visible on the site will reside in a subdirectory of that home directory. In short, pagesdir is the argument to cd to get from the home directory to the root of the site pages.

3. Test the site. Browse to sitename. Most hosts will have installed a dummy page. View the site with your choice of browser.

In a Cygwin terminal window give the command: ssh username@sitename, entering password when prompted. The first time you try to connect to a site, a message like this appears:

The authenticity of host 'physpics.com (' \
            can't be established.
RSA key fingerprint is SHA256:S1Hrn4+ysHSCfbvudft9gaGe \
Are you sure you want to continue connecting (yes/no)?

It is usually safe to just enter "yes".  It is not safe if a malicious user, say "Malfoy," has usurped control of your connection to the destination. He would be a "man-in-the-middle" and could exploit his position to grab passwords. How can you tell if Malfoy is listening? You can't. Ssh defeats Malfoy by a clever exchange of encrypted messages that include address information. This exchange requires you to verify that you do believe that your server has the displayed fingerprint. Saying "yes" is that verification. So how do you know if that is the correct fingerprint? Ideally the hosting service has sent it to you. Most don't. You could ask the service's support group. This is a perfect opportunity to find out what kind of support you can expect. Anyway, the simplest plan is to just say "yes"; most people do.

After the connection has been established and you are typing to a shell, enter the commands

cd pagesdir

The value from the pwd command is the document root. You will need this value in step 10, below. The ls command shoud list the file for the dummy page. Display its contents with less, more, or cat.

4. Directories. Web pages are generally in a tree to facilitate user navigation of the site. See directories.php. This tree structure is mirrored in the source files and the staging area. Under pictools, pictures are stored in their own, separate tree. Create three directories to be the roots of these trees: the source tree, the staging tree, and the pictures tree. The properties naming these directories will be SRCROOT, STAGINGAREA, and PICTURESROOT. Each value must be a full path name with no filnal slash..It must be in Cygwin form by beginning with "/cygdrive/X/ and continuing with directory names delimited by slashes.

For a tree at h:\site\websrc, the value of SRCROOT is /cygdrive/h/site/websrc. When the staging area is at h:\site\stage, STAGINGAREA is /cygdrive/H/site/stage.  If pictures are on the p: disk in directory \pictures\select, the value of PICTURESROOT is /cygdrive/p/pictures/selected. Each element of the SRCROOT tree may have its own images directory for small pictures, icons and graphics. For instance the images for these pictools documents are in SRCROOT/pictools/doc/images. For development files that are not needed on the website itself I have yet another tree with the same structure as the site; my root for this tree is SRCROOT/../resources.

5. Tailor your shell environment. Append the lines below to $HOME/.login to define SRCROOT and PICTOOLS. (Or for bash make the analogous changes to $HOME/.profile.)

 # Set environment variables for Pictools 
setenv SRCROOT /cygdrive/h/Fred/Physpics/websrc
setenv PICTOOLS $SRCROOT/pictools
# prepend PICTOOLS to path
setenv PATH "${PICTOOLS}:${PATH}"
#echo $PATH | tr ':' '\n'

# If you are using ANT, convert the environment:
setenv ANT_HOME `cygpath --unix $ANT_HOME`
setenv M2_HOME `cygpath --unix $M2_HOME`
setenv M2 `cygpath --unix $M2`
cd $SRCROOT # switch to directory SRCROOT

Alternative. You can convert all environment variables with this script (for csh):

printenv      \ 
   | gawk -F = '$1~/^[A-Za-z][A-Za-z0-9_]*$/  \
      {a="'"'"'"; line = $0; var=$1; \
      cmd = "cygpath --unix " a ENVIRON[var] a;  \
      (cmd|getline); val=$0; close(cmd);  \
      if (line != (var "=" val)) \
          print "setenv " var " " a val a; }' \
   | source /dev/stdin

6. Avoid passwords. In a cygwin terminal, run ssh-keygen answering the prompts with the ENTER key. Note the directory where it has stored the key (usually /home/$USER/.ssh) and cd to to there. Then enter these commands, giving your password as needed.

scp id_rsa.pub username@sitename:.ssh/incoming_id 
ssh username@sitename \
		'cat .ssh/incoming_id >> .ssh/authorized_keys'
ssh username@sitename 'rm .ssh/incoming_id'

After the first two lines, the password will no longer be needed. Security is now enforced by the shared secret in /home/$USER/.ssh.

7. Download Pictools.tgz. Either download it directly to SRCROOT/.. or move it there after downloading. At this writing it is a little over six megabytes.

8. Untar. Open a terminal and change directory to SRCROOT itself and.then give the command

tar -x --skip-old-files --warning=existing-file -z -f ../pictools.tgz

The two double-minus options arrange that modified files are not overridden if you reinstall Pictools.tgz. (Expect five warning messages about skipping creation of directories. The directories do get made.)

The result of the tar extraction is seven directories with the following content sizes (as of build 255). The total installed size is 7.4 megabytes. The manifest shows what files are installed and serves as index to related documentation.

A leading dash on a path (/...) is short for SRCROOT, as set in step 6.

9. Tailor properties. Edit /Pictools.properties. At the top give your own definitions for manager.href and manager.name. This name is used as both the author and copyright holder. href can be a mailto:user@mailer.com or it can be an URL. If the latter, the page is called (at least from box404.php) with a query:

?subject="404 for page xxxx.xxx"

In the SITE STRUCTURE and PICTURES sections edit these name to have these values:

stagingarea: webstage
sshdest: username@sitename
picsdir: pagesdir
picturesroot: webpictures
where the italicized names represent values described in prior sections. None of these values should end in a slash. Here's what the values mean.
Root of the tree of staging directories to which pages get built before uploading. After being built, they can be browsed on the local machine. Example: /cygdrive/h/Fred/stage ; the browser path to this directory is file:///h:/Fred/stage.\
sshdest, picsdir
sshdest is in the form username@sitename ; Example: Fred@physpics.com
picsdir is the directory string from username's home directory to the site directory corresponding to picroot. Example: httpdocs.
These two properties with a colon between then give the scp destination prefix for uploads to the serve. Example: Fred@physpics.com:httpdocs
Root of the tree of pictures. For me the subdirectories are years. Example: /cygdrive/h/Fred/pictures/selected (unselected pictures are in sibling directory .../Fred/pictures/raw; none of them are uploaded to the site.

The administrator command page shows information derived from the Apache server logs. These properties give the location of those logs.

log.http.access = (edit –/Pictools.properties to define this)
Location of the Apache server access log for yesterday. Example value: /home/physpics/logs/physpics.com/http/access.log
log.http.access0 = (edit –/Pictools.properties to define this)
Location of the Apache server access log for yesterday. Example value: /home/physpics/logs/physpics.com/http/access.log.0
log.http.error = (edit –/Pictools.properties to define this)
Location of the Apache server error log for today. Example value: /home/physpics/logs/physpics.com/http/error.log

10. PHP on server. Most hosting services tailor PHP with a .php.ini file. My service instead reads /home/physpics/.php/phpversion/phprc. I've been using these contents:

log_errors = 1
display_errors = 0
error_reporting = E_ALL
error_log = /home/physpics/physpics.com/admin/logs/phperrors.txt
mail.log = /home/physpics/physpics.com/admin/logs/maillog.txt
output_buffering = 0
extension = fileinfo.so
always_populate_raw_post_data = -1 ; if limits are being exceeded, adding try these max_execution_time = 50
post_max_size = 105M
memory_limit = 128M max_input_time = 500

Change the text in red to suit your site.

The propcon tool needs a few values defined so it can find default and override properties. In particular it needs the webside location of PICTOOLS. Its location will be DocRoot/pictools, where DocRoot is the document root value found in step 4 above. Edit /.htaccess to prepend

SetEnv PICTOOLS DocRoot/pictools

See also htaccess.php.

11. Upload. Open a new cygwin terminal and change directory to SRCROOT. If using DreamHost, set shell variable AFTERSSH to sleep 10. (You can set AFTERSSH in Pictools.properties, but that will slow down all future partial uploads,) Then give the command

make uploadall

There will be plenty of uninteresting command printout.

12. Browse to your new site. You should see something like this

DEMO picture set
Pictools Documentation

  pen in hand Coming soon to a screen near you

(When you click the DEMO button you will see a sample picture thumbs page. It has links to view the pictures and to view a slide show. All this functionality is automatically built because there is a captions file, DemoPics.cap. in source directory /pictools/doc.  The pictures themselves reside in the distribution in /pictools/doc/images/DemoPics. They are copied to your PICTURESROOT/DemoPics during step 10, Upload, just above. The pictures are then scaled and uploaded as described in the last section of MakeTargets.)

13. Terminal window onto server.  It is convenient to have a desktop icon that opens a shell window on the server. To get one, copy/paste your Cygwin terminal icon on your desltop. Right click the new icon and click "Properties". In the "Target" value replace the -t title value to something like the server's hostname. Change the -e value to

 -e /usr/bin/ssh -o ServerAliveInterval=200 username@sitename

Clicking the new shortcut will open a terminal window executing commands on your site server. The current directory will be the named user's home page. The actual served files will be in subdirectory pagesdir of that home page.

While you have a terminal connected to the site is a good time to set up administrator control. First ask a search engine for "my ip". The response should be a string of digits with three embedded dots: for instance, (which is an address for Google). In your terminal, change directory to ~/pagesdir/admin and give the command

echo youripaddress:0> .gate

Thereafter you will see the command page when you navigate to /admin/command.php

14. Tailor Site Files. Several files are incorporated in every Pictools page and can be modified to change them all. I recommend leaving them alone until you have built a number of text pages and pictures pages. That way you can more easily see the effects of your changes. Here are the documents for the files most likely to need to be tailored:

Copyright © 2018 ZweiBieren, All rights reserved. Dec 20, 2018 12:18 GMT Page maintained by ZweiBieren