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?
  1.7  Does it support tla and baz?

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?
  4.5  Why don't I see a newly committed revision or an existing branch?

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


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

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 or baz 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", "?color=sunny"
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".

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


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

1.7  Does it support tla and baz?

Yes, all arch-magic projects should work with tla version >= 1.1 and baz
version >= 1.1.  If you think there is some problem (possibly introduced
by incompatible changes in new tla and baz releases), contact arch-magic
developers, or take a look at fixing this in arch-perl or archzoom.

By default, tla is used, set arch_backend in archzoom.conf to change this.

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


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

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.sourcecontrol.net/      # DirectoryIndex archzoom.cgi

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?

It is enabled since 0.5.0.  Still, the old answer below may be interesting.

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  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.

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


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

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

There are several alternative template sets to choose from, each such set
is potentially provided with several layout themes and several color themes.
Templates are used to produce the final html, and layout css with color css
define how this html looks.  The defaults are configurable in archzoom.conf.
To see how the alternatives look, add "?template=plain" or "?layout=fresh"
or "?color=bright" or "?template=default?layout=larger?color=metallic"
or "?color=ivory2" or "?template=plain?color=aubergine" to any url.

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

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


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

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.

To do the same with "global categories" page, run "./archzoom.cgi '*'".

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


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

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 may include your entire archives.  Even if no real human visitors
ever ask for the changeset of patch-123 or tree of patch-234 or any such
rare revisions.  You may 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

Starting with 0.4.1, this is not really a problem, since by default the
well behaved crawlers are only allowed to index the linked pages and are
not allowed to follow further.  So, configuring robots.txt is not really
needed, you may use configuration option http_headers instead.

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

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


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

4.5  Why don't I see a newly committed revision or an existing branch?

By default, archzoom uses internal caching for archive and revision
listings.  It is possible you see the cached page data.  The cache
timeouts are configured in archzoom.conf and usually are about 2-3 hours.

To recreate the page data without using a cache, add ?nocache to any page
url.  If you still have a problem, add ?debug too (unless you disabled it).

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