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 HTML, CSS, 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. For options, Google the phrase "website hosting".
Free web hosting is worth what you pay for it. Competent hosting can be had (in 2015)
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 7.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 |
| host RSA key fingerprint |
fingerprint |
SHA256:qrn&d9dz |
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 (66.33.223.247)' \
can't be established.
RSA key fingerprint is SHA256:S1Hrn4+ysHSCfbvudft9gaGe \
DfEO3w93ccg9dzLsnDM.
Are you sure you want to continue connecting (yes/no)?
The authenticity of the host is preserved in /home/$USER/.ssh/known_hosts,
so they check will not be repeated,
Check the fingerprint shown in the message against the fingerprint from the host vendor. If they differ, contact the vendor. If the vendor has not provided the fingerprint, it is probably safe to say "yes" anyway.
For high security sites, you could consider changing to another host vendor.
(The above message exchange can be avoided by running
ssh-keyscan sitename >> /home/$USER/.ssh/known_hosts
This circumnavigates the fingerprint check; that is not a good idea.)
After the connection has been established and you are typing to a shell, enter the commands
cd pagesdir
pwd
ls
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. Directory trees. Web pages are in a directory tree
on the host to facilitate navigation of the site.
With Pictools, the build machine has a parallel tree for the page sources.
It also has a staging area exactly parallel to the host.
During a build, the staging area files are derived from the sources;
then the staging area is copied to the host.
Pictures are stored in their own, separate tree.
See directories.php.
On your build machine, create three directories: the source tree,
the staging area, and the pictures tree.
The properties naming these directories will be SRCROOT, STAGINGAREA,
and PICTURESROOT.
The first of these is defined in the next section.
The remaining two are defined in Pictools.properties;
see section 9, below.
5. Tailor your shell environment.
Installation to the host is carried out with make commands
entered into a terminal running a shell. Environment variables
give parameters required by the Makefiles.
These variables are set either in the windows environment or
pictools.properties (section 9).
To set Windows environment variables, bring up the windows "Settings"
menu and search for "env". Choose the option "Edit the environment variables for your account". The values for directories must be in Windows form; they begin with a drive-letter, a colon, and a back-slash. For Pictools they must not end with a slash. Spaces may not occur; use the short form of file names (as shown with the cmd /c "dir /x" command).
These variables need to be set
| Variable | Description | Sample |
|---|
| ANT_HOME |
Where ant is installed |
C:\PROGRA~1\Netbeans-16\netbeans\extide\ant |
| HOME |
User's home directory; initially /home/$USER |
U:\Fred |
| JAVA_HOME |
Where Java is installed |
C:\PROGRA~1\Java\jre1.8.0_361 |
| JAVAROOT |
root of user's tree of Java sources |
U:\Fred\Java |
| PICTOOLS |
directory containing installed/uploaded Pictools |
%SRCROOT%\pictools |
| SRCROOT |
root directory of user's tree of webpage sources |
U:\Fred\Physpics\websrc |
HOME is automatically converted to cygwin form when a terminal window is opened.
All the rest are converted in the .login file.
6. Avoid entering passwords.
SSH, or Secure Shell mediates secure
access to a server by sharing a secret key, generally housed in directory .ssh of the home directory. Create the secret by starting a
cygwin terminal and running ssh-keygen in it.
(You may need to append the argument -m PEM.)
Answer the prompts with the ENTER key.
Note the directory where ssh-keygen has stored the key
(usually /home/$USER/.ssh)
and cd to there.
Then enter these commands, entering 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.
(Most Cygwin commands use the environment value HOME
as the home directory. ssh-keygen does not. It puts its results in /home/$USER. You may want to copy .ssh from its default location to your chosen $HOME directory.)
.ssh files avoid passwords in other contexts as well. In Filezilla choose the Logon Type "Key file" and fill the "Key file" box with the name of the private key file (usually cygwin-home/.ssh/id_rsa). In DreamWeaver, choose "Private Key File" for Authentication and fill the "Identity File" box with the private key (usually cygwin-user-home/.ssh/id_rsa)
When you start up a
new session on the host, it will
begin execution of a shell. If you
want the default, just ssh to the
server. If you want some other
shell, There are various methods.
You can add an exec command to the
end of the initialization script
for the default shell.
7. Download physpics.com/pictools/pictools.tgz.
Move it to the parent directory of SRCROOT. At this writing it is a little under seven and a half 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
six directories (admin, images, library, pictools, scripts,
Templates) with a little over 300 files and occupying
almost nine megabytes of disk.
The manifest
shows what files are installed and serves as an index to related
documentation.
A leading ".../" on a path
is short for SRCROOT, as defined in step 4.
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.
- stagingarea
- 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
- picturesroot
- Root of the tree of pictures. For me the subdirectories are years. Example:
/cygdrive/h/Fred/pictures/selected (unselected
pictures are in sibling directory ../raw; they are not 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 website 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
The printout will be mostly uninteresting.
When done, visit directory /admin in a terminal and issue the command's
make rebuildmapdata
(see the end of urlmap.sq3)
12. Browse to your new site. You should see something like this
Coming soon to a screen near you
(When you click the DEMO button
you will see a sample picture thumbs page with
links to view the pictures or view them in a slide show.
These features arise auotmatically
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 running as some user, say username, on the host server.
On DreamHost, username is managed on the domain management panel's user management section. For each user there is a password, a home directory, and a default shell. This is where you choose which shell is chosen by ssh'ing to username@sitename.
If you followed the steps in tools.php, you have an icon that opens a local tty. As shown there, its target property is
C:\cygwin64\bin\mintty.exe -i /Cygwin-Terminal.ico -
To get a server tty, copy/paste your Cygwin
terminal icon on your desktop.
Right click the new icon, click "Properties",
and replace the dash at the end of the Target value with this:
-tPHYSPICS -h e -e /bin/ssh username@sitename
Clicking the new shortcut will open a terminal window executing commands
on your site server. The current directory will be username's home
page and the web-visible files will be in subdirectory pagesdir.
While you have a terminal connected
to the site is a good time to set up pictool administrator access.
First ask a search engine for "my ip".
The response should be a string of digits with three embedded dots:
for instance, 66.249.77.222 (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.
When cookies get out of sync it may be necessary to reset
.gate to ip-address:0
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:
