Ticket #348: PLUMI_INSTALL.txt

File PLUMI_INSTALL.txt, 22.2 KB (added by jimby, 5 years ago)

Updated PLUMI INSTALL guide (20100318)

Line 
1Hi All,
2
3Here is the guide I've developed for installing Plumi 3 on new installations.
4
5Your comments and suggestions are welcome.
6
7Note:  A complete documentation set now exists at:
8
9http://en.flossmanuals.net/Plumi/Introduction
10
11(see also:  http://en.flossmanuals.net/bin/view/Plumi/WebHome  if you want
12to contribute to the manual)
13
14The remainder of this document is based on my own experience.
15========================================================================================
16========================================================================================
17========================================================================================
18
19
20----------------------   Start of PLUMI_INSTALL.txt ----------------------------------
21
22
23
24Introductory Remarks
25
26This is a guide for installing Plumi on new hosts where there is no
27pre-existing Zope or Plone install.  This install used
28FreeBSD 7.3-PRERELEASE for testing, but other BSD versions should work
29where Plone is known to work.
30
31The basic idea is to download and install Plone with the Unified Installer.
32That version is then updated with the plumi.buildout trunk code overlaid on
33the Plone instance configuration.  Next, buildout is run to rebuild the Plone
34site using the overwritten instance.
35
36Once Plone is rebuilt, the Plumi application (a Plone product) can be installed.
37The Plumi application pulls in additional dependencies as needed.  The Plone
38site is then fully Plumi-zed.  You can then run tests with the new Plumi site.
39
40Some random simple customizing steps follow the install.  These are not
41needed to get plumi up and running.
42
43The steps in this guide assume the named instance "bsdtv".  Make the
44necessary adjustments for your instance name, or modify the steps if
45you are not using an instance name (i.e. you are using the default
46"Plone" instance).
47
48The guide also assumes you have a host with a correctly configured DNS name
49and that DNS is correctly functioning on the host and any clients you are
50using.  The DNS name used for this guide is "www.bsdtv.org".
51
52Multiple terminal sessions may be needed simultaneously in this guide.
53For example it is often necessary to run the Plone (or Plumi) instance in
54one terminal session, and the transcode daemon in a separate terminal session.
55Once installation testing is complete, this is not necessary.
56
57Any Plone site (including Plumi) needs a functioning mail server.  Ensure that
58your host system has a fully configured and working mailserver configured
59before beginning the installation.
60
61In most examples in this guide, the instance directory is always given as a
62fully qualified path name i.e.  "/usr/local/Plone/bsdtv"  Generally, the
63instance name for a default install will be something like
64"/usr/local/Plone/zinstance".  Path names may be different on different
65platforms.  Adjust as needed.
66
67Most commands in this guide will be run from the instance bin directory.
68You may be able to save time by adding the directories onto your PATH
69variable:
70
71PATH=_standard_path_directories_here:/usr/local/Plone/bsdtv/bin:/usr/local/Plone/zinstance/bin
72
73As with any tutorial, don't just blindly cut and paste commands.
74Read the commands in each step and understand what they do before
75using them.  Also, be alert for errors with command options, or default
76command locations (such as /bin/bash  vs. /usr/local/bin/bash)
77
78
79In this installation, squid is not used. Modifications for this case
80are noted where they apply below.  The resulting system configuration
81is similar to the figure below (best viewed in a fixed font):
82
83      [Internet user]
84             ^
85             |
86             |
87             v
88     +-------+-------+
89     |   Apache      |
90     |  listening    |
91     |  on port 80   |
92     |               |
93     | Rewrite rules |
94     |   bounce to   |
95     |  Zope server  |
96     |  on port 8080 |
97     |               |
98     | or FTP Server |
99     | on port 8021  |
100     |               |
101     |or Transcoding |
102     |Server on port |
103     |     8888      |
104     |               |
105     +------+--------+
106            ^
107            |
108            |
109            +----------------------+---------------------+
110            |                      |                     |
111            v                      v                     v
112     +------+--------+  +----------+--------+  +---------+----------+
113     |  Zope server  |  |   FTP Server on   |  | Transcoding Server |
114     |  with Plone   |  |     Port 8021     |  |  on Port 8888      |
115     | listening on  |  |                   |  |                    |
116     |   port 8080   |  +-------------------+  +--------------------+
117     |               |
118     +---------------+
119
120
121It's possible to run the server processes on separate hosts,
122but this installation uses one host for all 4 main processes
123(Apache, Zope/Plone/Plumi, FTP, and the Transcoding Daemon).
124
125
126I welcome your comments and suggestions.  Please reply on plumi-discuss.
127
128
129Best Regards,
130Jim Brown
131BSDCG
132
133jimbyg@gmail.com
134
135
136PS- "Well, it worked for me..."
137
138
139========================================================================
140Step 1.0
141
142Description:  In this step, the Plone Unified Installer takes care of setting up
143Python 2.4, the Python virtual environment, Plone itself, a random password,
144and in the default case, the plone uid and gid.
145
146  # Download Plone 3.3.4 Unified Installer and unpack it.
147
148  cd $HOME
149  wget http://launchpad.net/plone/3.3/3.3.4/+download/Plone-3.3.4-UnifiedInstaller.tgz
150  tar xvzf Plone-3.3.4-UnifiedInstaller.tgz
151
152  cd Plone-3.3.4-UnifiedInstaller
153
154  # Read the README.txt file for installation instructions and options.
155  # For a standalone installation using the default instance run:
156
157###  /bin/sh install.sh standalone
158
159  # This guide uses the instance name "bsdtv" for the Plumi install.
160
161  /bin/sh ./install.sh --instance=bsdtv standalone
162
163
164  # This step takes some time.  Grab yourself a cup of coffee.
165
166  # Note the admin password displayed at the end of the install and
167  # write it down.  It is used in several steps below.
168
169=========================================================================
170Step 2.0
171
172Description:  The Plone Unified installer installs the instance
173on disk as "bsdtv", but the on-line URL still requires /Plone.  If you
174are running a named instance the name must be changed in the Zope
175Management Interface (ZMI).
176
177This step is not needed for the default install.
178
179  # Change directory to the instance directory and run the instance.
180
181  cd /usr/local/Plone/bsdtv
182
183  bin/instance fg
184
185  # Web to the ZMI, and login as admin using the password from the above
186  # install.
187
188  #  http://www.bsdtv.org:8080/manage
189
190  # Check the "Plone" entry and Use the "Rename" button
191  # to change the name of the site to "bsdtv" from "Plone".
192
193  # Restart bin/instance fg
194
195  # You can now web to:
196
197  # http://www.bsdtv.org:8080/bsdtv
198
199  # Stop the instance (ctl-c or ctl-\ in the terminal window).
200
201=========================================================================
202Step 3.0
203
204Description:  The zope and plone installs use different uids.  Making them the
205same ensures the plumi install can complete successfully.
206
207Edit the password file and group file to make the names and id numbers the same.
208Only the zope user needs a working directory and shell.  The plone
209user does not.
210Add (if needed) plone and zope users with same uid,gid and a home directory
211for the zope user.
212
213Example /etc/passwd entries:
214
215  plone:*:2134:2134:Plone Admin:/nonexistent:/usr/sbin/nologin
216  zope:*:2134:2134:Zope:/home/zope:/usr/local/bin/bash
217
218Example /etc/group entries:
219
220  plone:*:2134:
221  zope:*:2134:
222
223=========================================================================
224Step 4.0
225
226Description:  Get the plumi.buildout trunk code and overlay it on the instance
227'bsdtv' directory. Set permissions as described below. Otherwise things break
228during buildout or running the instance.
229
230  # Download plumi.buildout/trunk into a temporary directory.
231  cd $HOME
232  rm -rf bsdtv
233  svn co https://svn.plone.org/svn/collective/plumi.buildout/trunk bsdtv
234  chown -R plone:plone $HOME/bsdtv
235
236  # The /usr/local/Plone/bsdtv already exists (from install.sh above)
237  # This step just updates that directory with the plumi.buildout trunk.
238  # BSD style cp command options.
239
240  cd /usr/local/Plone
241  cp -aR $HOME/bsdtv .
242
243  # Ensure that the var and src directorys have correct permissions for
244  # running buildout.
245  cd /usr/local/Plone/bsdtv
246  chown -R plone:plone var src
247
248  # Remove readme in the src directory.  It crashes bin/buildout.
249  cd /usr/local/Plone/bsdtv
250  rm /usr/local/Plone/bsdtv/src/README.txt
251
252==================================================================================
253Step 5.0
254
255Description:  Edit site.cfg for our specific installation. There are several
256changes needed.  Note that squid is not used in this installation, so
257only the minimum squid configuration is needed.  See below.
258
259  # Save original files
260
261  cd /usr/local/Plone/bsdtv
262  /bin/cp buildout.cfg buildout.cfg.orig
263  /bin/cp site.cfg site.cfg.orig
264
265  # Edit  site.cfg as needed.
266
267#----------------------- START of site.cfg ---------------------------
268[site]
269# start with offbeat password, and hint that it should be made unique in-site:
270user = admin:admin
271effective-user = zope
272http-address = www.bsdtv.org:8080
273
274# Set httpd-address this way for the buildout and plumi install.  The
275# http-address variable sets the property "plonesite_address" on the
276# ZMI plone_properties/plumi_properties/manage_workspace page.
277# After the install the property should be changed to http://www.bsdtv.org:8080/bsdtv
278# (if running standalone without Apache) or http://www.bsdtv.org (with no port value)
279# if running with Apache.
280#
281# A colon and port number is required for http-address for the buildout
282# and install.  Otherwise there are build or startup errors.
283
284ftp-address = www.bsdtv.org:8021
285transcode_host = www.bsdtv.org
286transcode_port = 8888
287videofolder = transcoded
288
289#squid configs
290squid_address = www.bsdtv.org:8080
291squid_backend = ${site:http-address}
292squid_hostname = example.org
293squid_email = plumi@example.org
294
295# Only the squid_address entry is needed in this installation tutorial.
296# Squid is not used, but the squid_address variable is used by the
297# buildout process.
298# Also, because squid is not used, we change the port number to
299# 8080 to feed right into Zope/Plone/Plumi. Squid_backend,
300# squid_hostname, and squid_email are not used at all
301# and can safely be ignored.
302
303# Apache configs
304apache_backends = www.bsdtv.org:${site:squid_address}
305transcode_backends = www.bsdtv.org:${site:transcode_host}:${site:transcode_port}
306apache_zope2_vhm_map = www.bsdtv.org:/bsdtv
307
308#----------------------- END of site.cfg ---------------------------
309
310====================================================================================
311Step 6.0
312
313Description:  Set up the egg cache for the buildout.
314
315  rm -rf /home/zope/.python-eggs
316  mkdir /home/zope/.python-eggs
317  chown zope:plone  /home/zope/.python-eggs
318
319====================================================================================
320Step 7.0
321
322Description:  Now run buildout.  Buildout should run to completion,
323even though there are some errors with skins and kupu and some other things.
324
325  cd /usr/local/Plone/bsdtv
326  bin/buildout  -n -v
327
328  # This step also takes some time. Time for a second cup.
329  # Apparently, buildout changes ownership of certain files in var and src.
330  # So we have to restore them to the plone:plone uid:gid.
331
332  cd /usr/local/Plone/bsdtv
333  chown -R plone:plone var src
334
335====================================================================================
336Step 8.0
337
338Description: Check the /tmp directory for Apache buildout cruft, especially
339if you have done more than one install.  Each Apache build can take up as
340much as 50MB of storage in /tmp.  The installation programs will be modified
341to clean up /tmp in a later release, but for now this should be done by hand.
342
343The /tmp directory is used by Plone when doing product installs, and
344product installation can fail if there is not enough space in /tmp.
345
346Delete entries similar to the /tmp/tmpxxxxxbuildout-apachebuild  as shown below:
347
348  #ls -al /tmp
349  ...
350  drwx------   3 root  wheel     512 Mar 16 15:42 tmp202X0obuildout-apachebuild
351  drwx------   3 root  wheel     512 Mar 17 11:23 tmp4cck05buildout-apachebuild
352  drwx------   3 root  wheel     512 Mar 16 21:43 tmpICPBE1buildout-apachebuild
353  ...
354
355====================================================================================
356Step 9.0
357
358Description: Tweak the Apache configuration files. The buildout installs
359Apache httpd.conf in a custom location, under the instance directory.
360
361  vi /usr/local/Plone/bsdtv/parts/apachebuild/conf/httpd.conf
362
363  #
364  # ServerAdmin: Your address, where problems with the server should be
365  # e-mailed.  This address appears on some server-generated pages, such
366  # as error documents.  e.g. admin@your-domain.com
367  #
368  ServerAdmin admin@www.bsdtv.org
369
370  #
371  # ServerName gives the name and port that the server uses to identify itself.
372  # This can often be determined automatically, but we recommend you specify
373  # it explicitly to prevent problems during startup.
374  #
375  ServerName www.bsdtv.org:80
376
377  # Tweaks to rewrite logging level in:
378
379  vi  /usr/local/Plone/bsdtv/parts/apacheconf/conf.d/virtual_www.bsdtv.org.conf
380
381  # and
382
383  vi  /usr/local/Plone/bsdtv/parts/apachetranscodeconf/conf.d/virtual_www.bsdtv.org.conf
384
385  # Change RewriteLogLevel value to 2 (reasonable value for debugging.)
386  # Change the value back to 0 after installation testing.
387
388====================================================================================
389Step 10.0
390
391Description:  Get ready to run Plone with Apache.  Startup the
392instance and Apache
393in separate terminal windows.  (The transcode daemon is not needed at
394this time.)
395
396  cd /usr/local/Plone/bsdtv
397
398  bin/instance fg
399
400  # Apache is configured to use Virtual Hosting.  Check the configuration as follows:
401
402  apachectl -S
403
404  # Output will look similar to:
405  #
406  #  VirtualHost configuration:
407  #  wildcard NameVirtualHosts and _default_ servers:
408  #  *:80                   is a NameVirtualHost
409  #           default server www.bsdtv.org (/usr/local/Plone/bsdtv/parts/apacheconf/conf.d/virtual_www.bsdtv.org.conf:1)
410  #           port 80 namevhost www.bsdtv.org (/usr/local/Plone/bsdtv/parts/apacheconf/conf.d/virtual_www.bsdtv.org.conf:1)
411  #           port 80 namevhost www.bsdtv.org (/usr/local/Plone/bsdtv/parts/apachetranscodeconf/conf.d/virtual_www.bsdtv.org.conf:1)
412  #  Syntax OK
413  #
414  #
415  # You must now start Apache to communicate with the bsdtv instance.
416  # The configuration files should already be correctly set up by
417  # the buildout.
418
419  apachectl start
420
421  # Web to www.bsdtv.org  The Plone site should come up.
422  # Log in as admin using the password from the install step above
423  #
424  # Do Plone mailserver setup.
425
426====================================================================================
427Step 11.0
428
429Description:  Add the Plumi application.
430
431  # Go to Site Setup -> Add-on Products
432
433  # Check "Plumi application setup x.y.z" and click Install to add the
434  # Plumi application.
435  #
436  # You do not need to check anything else at this time.  The Plumi
437  # application will bring in the dependencies that it needs.  This step
438  # may also take some time. The page will eventually refresh.
439  #
440  # Time for a third cup.
441
442  # Check and/or change the property on the properties page:
443
444  # http://www.bsdtv.org:8080/bsdtv/portal_properties/plumi_properties/manage_workspace
445
446  # If "localhost" is shown, change it to the network DNS name of
447  # the server (www.bsdtv.org)
448  #
449  # Change the "plonesite_password" to the password given from the
450  # install above.  This will not be necessary in a future release.
451  #
452  # Note- you must change the this entry.  If you do not, videos will
453  # probably not be transcoded and will probably not display correctly.
454  #
455  # Save the changes.
456
457  Stop Plone/Plumi/Zope instance and close all browser(s).  Stop Apache if running.
458
459====================================================================================
460Step 12.0
461
462Description:  Additional steps.
463
464Plumi uses ffmpeg, ffmpeg2theora, and qt-faststart  to assist
465in the transcoding steps.  Your host will need these packages
466installed to perform transcoding.
467
468Note:  BSD installs may add packages as follows:
469
470  pkg_add -r ffmpeg
471  pkg_add -r ffmpeg2theora
472  pkg_add -r qt-faststart
473
474Note:  ffmpeg may need to be configured to allow certain codecs.
475Check the transcode daemon logs if transcoding is not working correctly.
476You may need to recompile ffmpeg or other packages above to ensure
477correct transcoding.
478
479Other systems may need these and possibly other packages.
480
481Plone is now fully Plumi-zed!
482
483Stop everything and close all browsers.
484
485====================================================================================
486Step 13.0
487
488Description:  Testing video uploading and transcoding.
489
490Now run the plumi applications as foreground processes in
491separate windows for testing.
492
493  # In separate windows run (as root):
494
495  cd /usr/local/Plone/bsdtv
496  bin/transcodedaemon fg
497
498  # Other window.
499  cd /usr/local/Plone/bsdtv
500  bin/instance fg
501
502  # In another window
503  apachectl start
504
505Web to the Plumi site (www.bsdtv.org) login as admin,
506and run tests  to add, transcode, and display videos.
507
508Testing:
509
510  Login as admin and click to 'my folder -> Videos'
511
512  Click 'add new -> plumi video'
513
514  This is a 3 step process.  Complete each step entering the required fields.
515  If possible, check your network connection to ensure the file is uploading
516  correctly.  Some ISPs, hotels, hotspots, etc. limit traffic.
517
518  Once the file uploads, the thumbnail will display on the video description page.
519  It's possible that transcoding may take additional time.  For best test results
520  wait until transcoding is complete for all encodings.
521
522  Click to 'Home' -> 'my folder' -> 'videos'
523
524  View the video by clicking on the thumbnail image .  This should start
525  the 'flowplayer' application.  If it does not, a possible cause is that
526  the admin password was not set correctly on the
527  plumi_properties/manage_workspace page (see above).
528
529  For the video to be visible to anonymous surfers, it must be published. Change
530  the state of the video from 'pending review' to 'publish'.  The  video
531  show up on the main page.
532
533  Logout and restart the browser.  Web to your new Plumi site and click on the
534  video thumbnail.  The flowplayer application should begin to play the video.
535
536!!!!!!!!!  NOTE:  IF YOU HAVE TROUBLE WITH plumi ONLY DISPLAYING THUMBNAILS:
537
538The root cause is that the transcoder step is failing.  Check the
539transcoder logs.  In one case, the libfaac  library was not built into ffmpeg.
540Rebuilding/reinstalling  ffmpeg with libfaac enabled solved the problem.
541
542In another case, the site.cfg values were not set correctly at buildout time.
543This causes the plumi application to send an incorrect "DOWNLOAD" entry
544to the transcoder daemon.
545
546In yet another case, the transcoder daemon was not started.  Ensure that the
547transcoder daemon is started.  Watch the logs for activity.
548
549Only a short video is needed for testing.  A 5 MB .avi file should work fine.
550
551=======================  END of Plumi Install Tutorial  ===========================
552
553
554Simple Random Customizing Notes
555---------------------------------------
556
557Change background to blue:
558
559   Ugly Green:
560   src/plumi.skin/plumi/skin/browser/stylesheets/plumi.css: background-color: #abbd10;
561   src/plumi.skin/plumi/skin/browser/stylesheets/plumi.css:    color: #abbd10;
562
563
564   Nice Blue:
565   src/plumi.skin/plumi/skin/browser/stylesheets/plumi.css: background-color: #55749D;
566   src/plumi.skin/plumi/skin/browser/stylesheets/plumi.css:    color: #55749D;
567
568   You may have to restart Plumi and restart the browser for the css
569   to take effect.
570
571Change logo:
572
573  http://plone.org/documentation/kb/change-the-logo-in-plone-3/view?searchterm=change%20logo
574  Follow the guidelines in Section 1. "Changing the Image and its Title ; Alternative Approach"
575
576Change favicon:
577  http://plone.org/documentation/kb/setting-the-site-icon-favicon-for-your-plone-site/view?searchterm=favicon
578  Favicon must be loaded as a FILE, not an IMAGE.
579
580Change camera icon:
581
582   ZMI at  /bsdtv/portal_skins/plumi_skin_custom_images
583   customize the  plumi-icon32x32.png image
584   also the  plumi-icon32x32b.png image
585
586User Mods:
587
588  ZMI -> Site Setup -> Security Settings
589
590
591[Y] Enable self-registration
592      Allows users to register themselves on the site. If not selected, only
593      site managers can add new users.
594[N] Let users select their own passwords
595      If not selected, passwords will be autogenerated and mailed to users,
596      which verifies that they have entered a valid email address.
597[Y] Enable User Folders
598      If selected, home folders where users can create content will be created
599      when they log in.
600[N] Allow anyone to view 'about' information
601      If not selected only logged-in users will be able to view information
602      about who created an item and when it was modified.
603
604Navigation:
605
606[Y] Automatically generate tabs
607[Y]  Generate tabs for items other than folders.
608[ALL] Displayed content types
609
610[Y] Filter on workflow state
611      Only "Published is checked"
612
613Mail:
614
615  Note:  Set up latest Postfix before releasing to production.
616
617  Server: localhost
618  Site "From" Name:   BSDTV Site Admin
619  Site "From" Address:  info@www.bsdtv.org
620
621Errors:
622
623  Keep 50 exceptions
624
625Calendar:
626
627  First day of week in the calendar  : Sunday  (follows US style)
628
629Tagcloud:
630
631To get the tag cloud working, click on "Manage Portlets" and remove the 'blank'
632portlet if it appears instead of the tag cloud.  Add the "Customizable
633Tagclould Portlet"  Click the link for the portlet and configure it for
634maximum number of tags, etc.
635
636Tags are entered on upload step 2.  Enter any value, one per line.
637To promote an article (or News item) to the "Featured" list, enter
638the word "featured" (no quotes) as a tag.
639
640
641======================  End Random Simple Configurations =======================
642