ArchZoom Frequently Asked Questions with Answers.

------------------------------------------------------------------------------

1. About ArchZoom

  1.1  What is ArchZoom?
  1.2  What is GNU Arch and its terminology?
  1.3  Why do I need ArchZoom?
  1.4  How does it work?
  1.5  Can I run archzoom.cgi from command line?
  1.6  Why all these "?" and not "&" in urls?

2. Installation

  2.1  What should be installed and where?
  2.2  Can I make the archzoom.cgi base url shorter?

3. Configuration

  3.1  Why is the auto library updating option not enabled by default?
  3.2  Why is the tarball downloading option not enabled by default?
  3.3  Why is the global categories option not enabled by default?
  3.4  Why do I happen to see fancy chars or question marks in summaries?
  3.5  I don't like the look of pages, what to do?

4. Troubleshooting

  4.1  Why does my browser timeout when I browse the revision listing?
  4.2  Why does my browser timeout when I access some changeset or tree?
  4.3  Why can't I access my sftp archive?
  4.4  Are there any issues about making archzoom.cgi public on the web?

==============================================================================


------------------------------------------------------------------------------

1.1  What is ArchZoom?

This is a web based application that creates a convenient interface for
browsing GNU Arch archives.  Please visit the home page for screenshots
and additional information at http://migo.sixbit.org/software/archzoom/.

==============================================================================


------------------------------------------------------------------------------

1.2  What is GNU Arch and its terminology?

GNU Arch is an advanced revision control system.  It works with hierarchical
structure of archives, categories, branches, versions and revisions.  Atomic
changesets form new revisions.  Changeset is a set of file diffs, additions,
deletions, renames and permission changes.  There is one tree (snapshot)
associated with every revision.  There is one changeset log associated with
every revision.  One revision may include several external changeset logs in
case of merges.

Please visit http://wiki.gnuarch.org/ for more information.

==============================================================================


------------------------------------------------------------------------------

1.3  Why do I need ArchZoom?

Basically, you may want to have a convenient way to 1) privately browse your
own GNU Arch archives, 2) browse public archives of others, 3) let users of
your projects to track the development of these projects.

You may also use ArchZoom to allow your users to download the development
snapshots or individual changesets.

==============================================================================


------------------------------------------------------------------------------

1.4  How does it work?

ArchZoom runs tla to gather all needed information about archives and their
contents.  Some of the data may be cached.  If the debug mode is enabled,
add "?debug" to any archzoom url to view the things archzoom does in order
to generate any given page.

==============================================================================


------------------------------------------------------------------------------

1.5  Can I run archzoom.cgi from command line?

Yes, archzoom.cgi should work perfectly from the command line and generate
html page.  It accepts two optional command line arguments, the first is the
arch name, like "migo@homamail.com--Perl-GPL/archzoom--devel--0--patch-150",
and the second is url parameters, like "log&expand&debug&charset=utf-16".

==============================================================================


------------------------------------------------------------------------------

1.6  Why all these "?" and not "&" in urls?

For consistency.  So, you may add "?expand", "?nocache", "?css=bright.css"
to any url without worrying the url already contains one "?".  Note that it
is still standard compliant and you may freely use "&" if you like, i.e.
these two are the same: "?debug?charset=koi8-r" and "?debug&charset=koi8-r".

==============================================================================


------------------------------------------------------------------------------

2.1  What should be installed and where?

There are several solutions, the easiest is to follow the instructions in
README and run "make install".  This installs 2 things, archzoom.cgi script
and archzoom-data directory with several subdirectories. You may even move
archzoom.cgi and archzoom-data later by one level up or down, and the data
location will usually still be detected.

Suppose you have /www/html as your Apache document root. Then you may have
these possible layouts (the first is what "make install" does):

  /www/html/archzoom.cgi
  /www/html/archzoom-data/

  /www/html/cgis/archzoom.cgi
  /www/html/archzoom-data/

  /www/html/archzoom.cgi
  /www/archzoom-data/

  /www/html/cgi-bin/archzoom.cgi
  /www/archzoom-data/

With some Apache configurations you may need to do "chmod g-w archzoom.cgi".

==============================================================================


------------------------------------------------------------------------------

2.2  Can I make the archzoom.cgi base url shorter?

Sure, you may configure your Apache, so that the following urls produce the
list of the managed archives:

  http://localhost/archzoom/archzoom.cgi  # AddHandler cgi-script .cgi
  http://localhost:81/archzoom.cgi        #             --.--
  http://my-domain-org/archzoom/          # Alias /archzoom /www/archzoom.cgi
  http://my-domain-org:8080/              # Alias / /www/archzoom.cgi/
  http://my-domain-org/cgi-bin/archzoom   # cp|ln archzoom.cgi archzoom
  http://archzoom.sourceforge.net/demo    # cp|ln archzoom.cgi demo

Contact your httpd.conf documentation if needed.

==============================================================================


------------------------------------------------------------------------------

3.1  Why is the auto library updating option not enabled by default?

Using the revision library may speed up the tree operations dramatically,
especially with remote archives without many cached revisions (cacherev).
It is highly suggested to set auto_library_updating = 1 in archzoom.conf.
However you should be aware that the revision library may take a lot of
disk space (supposing your visitors sooner or later visit all links and
large active projects have large amount of revisions).  If you enable this
option, it is suggested to setup a cron job to control the size of revlib
using axp script.  The axp script is included in the archzoom package or
may be downloaded separately, see README.

==============================================================================


------------------------------------------------------------------------------

3.2  Why is the tarball downloading option not enabled by default?

Creating and downloading tarballs on the fly from any revision changeset
and tree is one of the most requested features.  The only reason it is not
enabled by default is because this is not a read-only operation, it invokes
external tar (and cp if needed) and creates temporary directory in /tmp.
I want to be conservative and let people know what they enable.  Other
than this, it is safe to set tarball_downloading = 1 in archzoom.conf.

==============================================================================


------------------------------------------------------------------------------

3.3  Why is the global categories option not enabled by default?

If several remote archives are registered, querying all archives for the
list of their categories may be slow.  Other than this, it is safe to set
globcats_enabled = 1 in archzoom.conf.  If set, then globcats_cache option
is used too.  Actually the cache makes this operation almost cheap, since
the archives are only queried once in 3 hours at most.

==============================================================================


------------------------------------------------------------------------------

3.4  I don't like the look of pages, what to do?

There are several alternative css, and alternative template sets, see
archzoom.conf.  Add "?css=bright.css" or "?template=plain" to any url to
see how these look.

Consider to create your own css or even the whole template set.  If good,
it may be included in the future archzoom versions.

==============================================================================


------------------------------------------------------------------------------

3.5  Why do I happen to see fancy chars or question marks in summaries?

Try to see whether adding something like "?charset=iso-8859-1" to the url
solves your problem.

==============================================================================


------------------------------------------------------------------------------

4.1  Why does my browser timeout when I browse the revision listing?

Unfortunately, commands 'tla abrowse' and 'tla revisions' with options like
--summary take a lot of time in case of remote archives.  Consider to mirror
archives, local archives should work much quicker.

If these tla operations exceed the browser timeout (that is usually one or
more minutes), but you (as the owner of the system archzoom.cgi runs on)
absolutely need to temporarily browse the revisions, use the following
trick.  Run: "./archzoom.cgi your--archive/category--branch--version" from
the command line.  After several minutes of running, the result will be
cached (see archzoom.conf), then you may revisit the url in the browser.

==============================================================================


------------------------------------------------------------------------------

4.2  Why does my browser timeout when I access some tree?

Unfortunately, commands like 'tla library-add' or 'tla get' may take quite a
time for large projects even with only local archives. Consider to notify
the branch creator and ask him to add cacherevs every 50 or even 20 or 25
revisions, using 'tla cacherev'.

If some ancestry revision is found in the revision library, building the
tree should be faster, so consider also to configure automatically updated
revision library or manually populate revisions. See also other questions.

==============================================================================


------------------------------------------------------------------------------

4.3  Why can't I access my sftp archive?

First, you can only access sftp archives that don't normally require
interactive authorization in the start of every session. Think about an
empty pass-phrase to allow such non-interactive access.

Please also remember that the user archzoom is operating under is not the
same user you are used to, so a new authorization may be required. Think
about copying the relevant entry from your .ssh/known_hosts to that of the
arch/apache user.

Please also note that there are very legitimate reasons for interactive
authorization prompts, these are part of the ssh initialization. The site's
public key may change with a time, then you ought to manually login as the
arch/apache user and start ssh/sftp to answer these interactive prompts.
Or, as mentioned, synchronize .ssh/known_hosts.

==============================================================================


------------------------------------------------------------------------------

4.4  Are there any issues about making archzoom.cgi public on the web?

You should be aware that web crawlers (like googlebot) visit and revisit
every linked web page in the internet. If you enable automatical population
of the revision library (that is recommended to save resources), then this
means it will include your entire archives sooner or later. Even if no real
human visitors ever ask for the changeset of patch-123 or tree of patch-234
or any such rare revisions. Please consider to disable crawlers by creating
robots.txt in the root of your web site with the folowing content:

  User-agent: *
  Disallow: archzoom.cgi     # or just "*" if this is archzoom-only host

See also question 3.1 that discusses the suggested revision library setting.

==============================================================================
