interpolate version

git-svn-id: https://svn.apache.org/repos/asf/archiva/trunk@1431879 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 295 insertions, 0 deletions

diff --git a/archiva-docs/src/site/apt/adminguide/standalone.apt.vm b/archiva-docs/src/site/apt/adminguide/standalone.apt.vm
new file mode 100644
index 000000000..5c516c66e
--- /dev/null
+++ b/archiva-docs/src/site/apt/adminguide/standalone.apt.vm
@@ -0,0 +1,295 @@
+ ------
+ Installing Standalone Distribution of Apache Archiva
+ ------
+ Olivier Lamy
+ ------
+ 2013-01-03
+ ------
+
+~~ Licensed to the Apache Software Foundation (ASF) under one                      
+~~ or more contributor license agreements.  See the NOTICE file                    
+~~ distributed with this work for additional information                           
+~~ regarding copyright ownership.  The ASF licenses this file                      
+~~ to you under the Apache License, Version 2.0 (the                               
+~~ "License"); you may not use this file except in compliance                      
+~~ with the License.  You may obtain a copy of the License at                      
+~~                                                                                 
+~~   http://www.apache.org/licenses/LICENSE-2.0                                    
+~~                                                                                 
+~~ Unless required by applicable law or agreed to in writing,                      
+~~ software distributed under the License is distributed on an                     
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY                          
+~~ KIND, either express or implied.  See the License for the                       
+~~ specific language governing permissions and limitations                         
+~~ under the License.                                                              
+
+Installing Standalone Distribution of Apache Archiva
+
+  Installing the standalone distribution of Archiva is quite simple - for an example, see the {{{../quick-start.html} Quick Start}} guide.
+
+  However, the best way to use this installation technique is to separate the configuration from the installation to make it easy to
+  upgrade to newer versions in the future.
+
+* Running Archiva
+
+  Archiva can be run by executing:
+
+    * <<<bin/archiva>>>, or <<<bin\archiva.bat>>> for Windows (select the one for your environment). The argument can be <<<console>>> to run
+      interactively, or <<<start>>> to run in the background (in this case, run the script with <<<stop>>> to later stop the server). The logs
+      are available in the <<<logs>>> directory where Archiva is installed.
+
+  There is an issue with regard to the version of <<<tr>>> installed/used by default on Solaris so you might encounter a series of <<<Bad String>>> errors
+  when you run the Archiva binaries in Solaris. You need to use a different version of <<<tr>>> in order to get it to work. See
+  {{{http://jira.codehaus.org/browse/MRM-1467} MRM-1467}} for more details.
+
+  <<NOTE>>: since 1.4-M3 Archiva is now available on / (ROOT) context.
+
+  If you want to use an other context path, you must edit the file in contexts/archiva.xml
+
++---
+<Configure class="org.eclipse.jetty.webapp.WebAppContext">
+
+  <!-- contextPath used -->
+  <Set name="contextPath">/</Set>
+  <Set name="war"><SystemProperty name="jetty.home" default="."/>/apps/archiva</Set>
+
+  <Set name="extractWAR">false</Set>
+  <Set name="copyWebDir">false</Set>
+
+</Configure>
++---
+
+* Installing as a Service on Linux
+
+  On Linux, the <<<bin/archiva>>> script is suitable for linking or copying
+  to <<</etc/init.d/archiva>>> and running as <<<root>>>, as long as the
+  <<<RUN_AS_USER>>> environment variable is set within the script. This will
+  allow you to start and stop the service with:
+
++----+
+$ service archiva start
+$ service archiva stop
++----+
+
+** Starting on boot for RedHat-based systems
+
+  The startup script is enabled to <<<chkconfig>>>. Run the following as
+  <<<root>>>:
+
++----+
+$ chkconfig --add archiva
+$ chkconfig archiva on
++----+
+
+** Starting on boot for Debian/Ubuntu-based systems
+
+  Debian-based systems come with a script to create appropriate <<<rc.d>>>
+  links for a startup script:
+
++----+
+$ update-rc.d archiva defaults 80
++----+
+
+* Installing as a Service on Windows
+
+  On Windows, to use the <<<start>>> and <<<stop>>> commands you must first install it as a service. This is done by running:
+
+----
+.\bin\archiva.bat install
+----
+
+  You can then use the <<<start>>> and <<<stop>>> commands as well as the traditional Windows service management console to manage the Archiva
+  service.
+
+  This procedure installs the service to run as the local system user. You must ensure that it has access to read the installation, and to write
+  to the logs and data directories.
+
+  Note on last Windows version, you need to configure correctly path to your java executable.
+  In wrapper.conf file:
+
+---
+wrapper.java.command=fullpath to your java executable
+---
+
+  You can later remove the service with:
+
+----
+.\bin\archiva.bat remove
+----
+
+* Installing as a Service on Mac OS X
+
+  On OS X, you can use <<<launchd>>> to run a service. Create the following
+  as root in <<</Library/LaunchDaemons/org.apache.archiva.plist>>>:
+
++----+
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>org.apache.archiva</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Applications/Archiva/apache-archiva-${project.version}/bin/archiva</string>
+        <string>console</string>
+    </array>
+    <key>Disabled</key>
+    <false/>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>UserName</key>
+    <string>archiva</string>
+    <key>StandardOutPath</key>
+    <string>/Applications/Archiva/apache-archiva-${project.version}/logs/launchd.log</string>
+    <!-- Optional - store data separate from installation (see below) -->
+    <key>EnvironmentVariables</key>
+    <dict>
+      <key>ARCHIVA_BASE</key>
+      <string>/Users/archiva/Library/Archiva</string>
+    </dict>
+    <!-- Optional: force it to keep running
+    <key>KeepAlive</key>
+    <true/>
+    -->
+</dict>
+</plist>
++----+
+
+  To install the service, run the following:
+
++----+
+$ sudo chown root:wheel /Library/LaunchDaemons/org.apache.archiva.plist
+$ sudo launchctl load -w /Library/LaunchDaemons/org.apache.archiva.plist
++----+
+
+  Start and stop the service with:
+
++----+
+$ sudo launchctl start org.apache.archiva.plist
+$ sudo launchctl stop org.apache.archiva.plist
++----+
+
+  To uninstall the service:
+
++----+
+$ sudo launchctl unload -w /Library/LaunchDaemons/org.apache.archiva.plist
++----+
+
+* Separating the base from the installation
+
+  The standalone installation of Archiva is capable of separating its configuration from installation
+  in much the same way Tomcat does.
+
+  This is achieved by the following steps:
+
+   [[1]] Create the base location. For example, you might install Archiva in
+         <<</opt/archiva-1.4>>> and the data in <<</var/archiva>>>. Create the
+         directories <<</var/archiva/logs>>>, <<</var/archiva/data>>>,
+         <<</var/archiva/temp>>> and <<</var/archiva/conf>>>.
+
+   [[2]] Move the configuration files from the Archiva installation (e.g. <<</opt/archiva-1.4/conf>>> to the new location (e.g. <<</var/archiva/conf>>>). If you've previously run Archiva, you may need to edit <<<conf/archiva.xml>>> to change the location of the repositories.
+
+   [[3]] (Optionally, leave a README file in the old conf location as a reminder of where you moved the config files.)
+
+   [[4]] Set the environment variable <<<ARCHIVA_BASE>>> to the new location (e.g. <<</var/archiva>>>). In bash, be sure to export the variable.
+
+   [[5]] Start Archiva standalone as described above from the installation location
+
+* Configuring Archiva
+
+  Archiva's configuration is loaded from the following files, in order of precedence:
+
+    * <<<~/.m2/archiva.xml>>>
+
+    * <<<$ARCHIVA_BASE/conf/archiva.xml>>>
+
+    * <<<conf/archiva.xml>>> in the Archiva installation
+
+  When Archiva saves its configuration, all configuration is stored in a single file. The file chosen is by the following rules:
+
+    * If <<<~/.m2/archiva.xml>>> exists, it is saved there
+
+    * Otherwise, if <<<$ARCHIVA_BASE/conf/archiva.xml>>> exists, it is saved there
+
+    * If neither apply, it is saved to <<<~/.m2/archiva.xml>>>.
+
+  The configuration will never be saved in the Archiva installation directory if you are using a separate base directory.
+
+  Note that the configuration can be edited, but only when Archiva is not running as it will not reload a changed configuration file, and will save over it
+  if something is changed in the web interface.
+
+* Database
+
+ By default, Archiva uses embedded {{{http://db.apache.org/derby}Apache Derby}}
+ to store the user information. It can be configured to use an external database
+ by providing a JDBC driver and editing the <<<jetty.xml>>> file.
+
+ [[1]] Place the jar containing the JDBC driver in the <<<lib>>> directory of the Archiva installation.
+
+ [[2]] Edit <<<conf/wrapper.conf>>> to add it in the jetty classpath
+
++------+
+ Find lines with:
+ wrapper.java.classpath.x=%REPO_DIR%/tomcat-juli-7.0.34.jar
+
+ Add one
+
+ wrapper.java.classpath.x+1=%REPO_DIR%/yourjdbcdriver.jar
+
++------+
+
+ [[3]] Edit <<<conf/jetty.xml>>>, providing the JDBC driver class
+ name, database url, username, and password.
+
+ []
+
+ The example below uses Mysql for the database server. You can take a look at
+ {{{http://cwiki.apache.org/confluence/display/ARCHIVA/Archiva+with+MySQL}Archiva with MySQL}}
+ for more details.
+
++------+
+  <!-- omitted xml -->
+
+  <!-- Users / Security Database -->
+
+  <New id="users" class="org.eclipse.jetty.plus.jndi.Resource">
+    <Arg>jdbc/users</Arg>
+    <Arg>
+      <New class="org.apache.tomcat.jdbc.pool.DataSource">
+        <Set name="driverClassName">com.mysql.jdbc.Driver</Set>
+        <Set name="url">jdbc:mysql://localhost/archiva</Set>
+        <Set name="username"></Set>
+        <Set name="password"></Set>
+        <Set name="initialSize">15</Set>
+        <!-- depends on your concurrent users numbers -->
+        <Set name="maxActive">30</Set>
+        <Set name="maxWait">10000</Set>
+        <Set name="removeAbandoned">true</Set>
+        <Set name="logAbandoned">true</Set>
+        <Set name="removeAbandonedTimeout">10000</Set>
+        <Set name="testOnBorrow">true</Set>
+        <!-- very rigourous sql query validation -->
+        <Set name="validationQuery">select 1</Set>
+      </New>
+    </Arg>
+  </New>
+  <!-- omitted xml -->
++------+
+
+ More information about using Derby Network Server as an external user database
+ for Archiva can be found on the wiki:
+ {{{http://cwiki.apache.org/confluence/display/ARCHIVA/Archiva+User+DB+on+Derby+Network+Server}
+ Archiva User DB on Derby Network Server}}
+
+* Installing with Puppet
+
+  If you use Puppet to manage your infrastructure, you can use a third-party
+  Puppet module to install Archiva. This will take care of adding the
+  required users, databases and configuration based on official release
+  tarballs.
+
+  * {{{https://forge.puppetlabs.com/maestrodev/archiva} Puppet module for
+    Apache Archiva}}
+