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