diff options
Diffstat (limited to 'archiva-docs/src/site/apt/guides')
4 files changed, 576 insertions, 0 deletions
diff --git a/archiva-docs/src/site/apt/guides/configuration.apt b/archiva-docs/src/site/apt/guides/configuration.apt new file mode 100644 index 000000000..c307dff93 --- /dev/null +++ b/archiva-docs/src/site/apt/guides/configuration.apt @@ -0,0 +1,63 @@ + ------ + Archiva Configuration + ------ + The Maven Team + ------ + 8 March 2007 + ------ + +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +Archiva Configuration + +* Web Configuration + + Archiva can be fully configured from the web interface (with the exception of the {{{security-configuration.html} security properties, presently}}). + + ... + +~~TODO: more details needed, but I wanted to get this started + +* File system configuration + + While Archiva can be fully configred by the web interface, the configuration will be saved to the file system and can be edited from there if needed. + + Archiva's configuration is loaded from the following files, in order of most precedent: + + * <<<~/.m2/archiva.xml>>> + + * <<<$ARCHIVA_BASE/conf/archiva.xml>>> + + * <<<$ARCHIVA_HOME/conf/archiva.xml>>> + + When Archiva saves it's configuration, all configuration is stored to a single file. The file chosen is by the following rules: + + * If <<<~/.m2/archiva.xml>>> exists, it is saved there + + * Otherwise, it is saved to <<<$ARCHIVA_BASE/conf/archiva.xml>>>, regardless of whether it previously existed. + + The configuration will never be saved in <<<$ARCHIVA_HOME>>>. + + 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. + +~~TODO: format? + diff --git a/archiva-docs/src/site/apt/guides/getting-started.apt b/archiva-docs/src/site/apt/guides/getting-started.apt new file mode 100644 index 000000000..f8d6c42b6 --- /dev/null +++ b/archiva-docs/src/site/apt/guides/getting-started.apt @@ -0,0 +1,120 @@ + ----- + Getting Started with Archiva + ----- + Henri Yandell + ----- + 1 October 2006 + ----- + +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +To deploy Archiva on Plexus + + Plexus is a container developed as a part of Maven. It provides a very simple way to get started with Archiva: + + * Unpack the archiva-plexus-runtime/target/archiva-bin.tar.gz archive into a directory of your choice. + + * Start with: ./bin/plexus.sh start or a platform specific version. + + * A Derby exception "Schema 'SA' does not exist" occurs, but is not of concern. + +To deploy Archiva on Tomcat 5.5 + + * Create a directory in tomcat called archiva, at the same level as bin, conf, logs and the others. + + * Copy the war file from apps/archiva/lib into the new directory + + * Create a conf/Catalina/localhost/archiva.xml file with the following data: + ++-------------------------------------------------------------------------+ + <?xml version="1.0" encoding="UTF-8"?> + <Context path="/archiva" + docBase="${catalina.home}/archiva/archiva-webapp-1.0-SNAPSHOT.war"> + + <Resource name="jdbc/users" auth="Container" type="javax.sql.DataSource" + username="sa" + password="" + driverClassName="org.apache.derby.jdbc.EmbeddedDriver" + url="jdbc:derby:database/archiva;create=true" /> + + <Resource name="jdbc/archiva" auth="Container" type="javax.sql.DataSource" + username="sa" + password="" + driverClassName="org.apache.derby.jdbc.EmbeddedDriver" + url="jdbc:derby:database/archiva;create=true" /> + + <Resource name="mail/Session" auth="Container" + type="javax.mail.Session" + mail.smtp.host="localhost"/> + </Context> ++-------------------------------------------------------------------------+ + + * <<Note>>: Tomcat 5.5.20 and 5.5.23 are missing MailSessionFactory and a + few other classes. JNDI mail sessions will <not> work. Use Tomcat 5.5.17 + instead, or see {{{http://issues.apache.org/bugzilla/show_bug.cgi?id=40668} + Bug 40668}} for a workaround. + + * Copy $HOME/.m2/org/apache/derby/derby/10.1.3.1/derby-10.1.3.1.jar (or from the remote repository) into the Tomcat + common/lib + + * To deal with a current bug, you'll also need to add the following to your ${catalina.home}/conf/web.xml in the + relevant section (search for jspx): + ++-------------------------------------------------------------------------+ + <servlet-mapping> + <servlet-name>jsp</servlet-name> + <url-pattern>*.jspf</url-pattern> + </servlet-mapping> ++-------------------------------------------------------------------------+ + + When you first start Archiva, you will see an Exception that schema SA does not exist - however it doesn't appear to + cause a problem. If you use a username other than 'sa', such as 'archiva', then you seem to get the same error but + Tomcat fails to start the context and you have to shutdown and restart again. + +Setting up your Archiva instance + + * Goto {{http://localhost:8080/archiva/}} + + * On the first page - setup your administration user. The password requires a numerical character and must not be + longer than 8 chars. You'll then need to log in. User 'admin' as the username and the password you've entered. + + * On the second page - setup your first repository. It can be both an m1 and an m2 repository. + + * On the third page - setup your indexing. Mostly this means choosing a directory to put the index in. It'll + re-index every hour. + +Updating Archiva within a Tomcat + + While exploring Archiva, or perhaps while developing with it, you will want to delete the + current state. Presuming you followed the instructions above, you will need to remove the + following files from the ${catalina.home} directory. Ensure your Tomcat has first been + shutdown. + ++-------------------------------------------------------------------------+ + # Remove the database + rm -r bin/database/ bin/derby.log + # Remove the archiva configuration + rm $HOME/.m2/archiva.xml + # Remove the temporary Tomcat files + rm webapps/archiva/ work/Catalina/localhost/archiva/ logs/* + # Remove the war file (if you're deploying a new one) + rm archiva/*.war ++-------------------------------------------------------------------------+ diff --git a/archiva-docs/src/site/apt/guides/maven-configuration.apt b/archiva-docs/src/site/apt/guides/maven-configuration.apt new file mode 100644 index 000000000..26fb1447a --- /dev/null +++ b/archiva-docs/src/site/apt/guides/maven-configuration.apt @@ -0,0 +1,267 @@ + ----- + Client Configuration + ----- + ----- + 17 November 2006 + ----- + +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +Configuring Maven-2 to use an Archiva repository + + To get your local Maven 2 installation to use an Archiva proxy you need to add the repositories you require to your 'settings.xml'. This file is usually found in ${user.dir}/.m2/settings.xml (see the {{{http://maven.apache.org/settings.html}Settings Reference}}). + + You will need to add one entry for each repository that is setup in Archiva. If your repository contains plugins; remember to also include a <pluginRepository> setting. + + <URL-TO-ARCHIVA> => where to find Archiva eg. http://localhost:8080/archiva + + <REPOSITORY-ID> => Identifer for the proxied repository inside Archiva eg. internal, releases + + ~~ <URL-NAME> => Another identifier, this time for normal repositories [one of the these will go away] + +* Configuring a Repository + + [[1]] create a new profile to setup your repositories + ++-------------------------------------------------------------------------+ + <settings> + ... + <profiles> + <profile> + <id>Repository Proxy</id> + <activation> + <activeByDefault>true</activeByDefault> + </activation> + <!-- ******************************************************* --> + <!-- repositories for jar artifacts --> + <!-- ******************************************************* --> + <repositories> + <repository> + ... + </repository> + ... + </repositories> + <!-- ******************************************************* --> + <!-- repositories for maven plugins --> + <!-- ******************************************************* --> + <pluginRepositories> + <pluginRepository> + ... + </pluginRepository> + ... + </pluginRepositories> + </profile> + ... + </profiles> + ... + </settings> ++-------------------------------------------------------------------------+ + + [[2]] add your repository configuration to the profile... + + You can copy the repository configuration from the POM Snippet on the Archiva Administration Page for a normal repository. It should look much like: + ++-------------------------------------------------------------------------+ + <repository> + <id>repository-1</id> + <url>URL-TO-ARCHIVA/repository/REPOSITORY-ID</url> + <releases> + <enabled>true</enabled> + </releases> + <snapshots> + <enabled>false</enabled> + </snapshots> + </repository> ++-------------------------------------------------------------------------+ + +* Configuring Maven-2 to deploy to an Archiva repository + + [[1]] Create a user in Archiva to use for deployment + + [[2]] The deployment user needs the Role 'Repository Manager' for each repository that you want to deploy to + + [[3]] Define the server for deployment inside your 'settings.xml', use the newly created user for authentication + ++-------------------------------------------------------------------------+ + <settings> + ... + <servers> + <server> + <id>deployment.webdav</id> + <username>{archiva-deployment-user}</username> + <password>{archiva-deployment-pwd}</password> + </server> + ... + </servers> + ... + </settings> ++-------------------------------------------------------------------------+ + +* Deploying to Archiva + + [[1]] Configure the distributionManagement part of your pom.xml + ++-------------------------------------------------------------------------+ + <project> + ... + <distributionManagement> + <repository> + <id>deployment.webdav</id> + <name>Internal Release Repository</name> + <url>dav:URL-TO-ARCHIVA/repository/REPOSITORY-ID/</url> + </repository> + <snapshotRepository> + <id>deployment.webdav</id> + <name>Internal Snapshot Repository</name> + <url>dav:URL-TO-ARCHIVA/repository/REPOSITORY-ID/</url> + </snapshotRepository> + </distributionManagement> + ... + </project> ++-------------------------------------------------------------------------+ + + [[2]] Add a build extension to your pom.xml to use webdav + ++-------------------------------------------------------------------------+ + <project> + ... + <build> + <extensions> + <extension> + <groupId>org.apache.maven.wagon</groupId> + <artifactId>wagon-webdav</artifactId> + <version>1.0-beta-2</version> + </extension> + </extensions> + </build> + ... + </project> ++-------------------------------------------------------------------------+ + + [[3]] Finally the user that is running archiva (tomcat-user, plexus-user,..) must have write access to the deployment repository. + +* Deploying Third-Party Artifacts to Archiva + + [[1]] In the directory from which you intend to execute "<<<mvn + deploy:deploy-file>>>", save the following content as <<<pom.xml>>>. + ++-------+ +<project> + <modelVersion>4.0.0</modelVersion> + <groupId>com.example</groupId> + <artifactId>webdav-deploy</artifactId> + <packaging>pom</packaging> + <version>1</version> + <name>Webdav Deployment POM</name> + + <build> + <extensions> + <extension> + <groupId>org.apache.maven.wagon</groupId> + <artifactId>wagon-webdav</artifactId> + <version>1.0-beta-2</version> + </extension> + </extensions> + </build> + +</project> ++-------+ + + This pom will not be deployed with the artifact, it simply serves to make the + wagon-webdav jar available to the build process. + + Alternately, save this file somewhere else, and use "<<<mvn ... -f + /path/to/filename>>>" to force the use of an alternate POM file. + + [[2]] Deploy the artifact: + ++------+ +mvn deploy:deploy-file -Dfile=filename.jar -DpomFile=filename.pom + -DrepositoryId=deployment.webdav + -Durl=dav:URL-TO-ARCHIVA/repository/REPOSITORY-ID ++------+ + +Archiva as a Proxy + +* Creating a New Proxy Repository + + Archiva has pre-configured proxy connectors for the 'internal' managed repo and the 'central' and 'maven2-repository.dev.java.net' remote repositories. + + To create a new proxy repository, just do the following: + + [[1]] Add a new managed repository + + Go to Repositories --> Add (Managed Repository) + + Create the managed repository (let's say 'releases') which would serve as the proxy repo. + + Do not forget to set the necessary permissions or user roles in Users Management if you want this repository to be secured. + + [[2]] Add a remote repository + + Go to Repositories --> Add (Remote Repository) + + Add the remote repository you want to proxy. + + [[3]] Create a proxy connector + + Go to Proxy Connectors --> Add + + Fill up the following fields: + + * Network Proxy* - if your network connection has a network proxy, then this should be configured via the Network Proxies in Archiva. Select the network proxy, if you're using one, that will be used for this proxy connector. + + * Managed Repository* - the managed repository you want to connect to the remote repository. + + * Remote Repository* - the repository you want to proxy + + * Policies - the download policies that will be used by Archiva when proxying + + * Properties + + * Black List Patterns - the patterns that will be blacklisted during proxying + + * White List Patterns - the patterns that will be included during proxying + +* Using the Proxy Repository with Maven + + Set-up your settings.xml file as shown above in sections 1 and 2 of Configuring a Repository. In this case, use the repository configuration of the managed repository you've created. + + Then, configure the <server> settings in the settings.xml file as shown below: + ++-------------------------------------------------------------------------+ + <settings> + ... + <servers> + <server> + <id>releases</id> + <username>{archiva-user}</username> + <password>{archiva-pwd}</password> + </server> + ... + </servers> + ... + </settings> ++-------------------------------------------------------------------------+ + + Execute a Maven 2 build. Artifacts should be downloaded from the proxy repository/repositories you've set in your settings.xml + +
\ No newline at end of file diff --git a/archiva-docs/src/site/apt/guides/security-configuration.apt b/archiva-docs/src/site/apt/guides/security-configuration.apt new file mode 100644 index 000000000..2263cb409 --- /dev/null +++ b/archiva-docs/src/site/apt/guides/security-configuration.apt @@ -0,0 +1,126 @@ + ------ + Archiva Security Configuration + ------ + The Maven Team + ------ + 17 February 2007 + ------ + +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +Archiva Security Configuration + +* Properties + + Archiva makes use of Redback to handle user ids, passwords and roles. + + Security properties and password rules can be configured in the + <<<security.properties>>> file, which by default is searched for in: + + * <<<~/.m2/security.properties>>> + + * <<<$ARCHIVA_HOME/conf/security.properties>>> + + [] + + (In the above list, <<<~>>> is the home directory of the user who is running + Archiva, and <<<$ARCHIVA_HOME>>> is the directory where Archiva is installed, + such as <<</opt/archiva-1.0-SNAPSHOT>>>.) + +~~ TODO: Link to plexus-redback documentation when available + + Following are some of the properties you can modify. For a complete list, + consult the default properties file in Redback's svn repo: + {{{http://svn.codehaus.org/redback/redback/trunk/redback-configuration/src/main/resources/org/codehaus/plexus/redback/config-defaults.properties} + config-defaults.properties}} + ++-----+ +# Security Policies +#security.policy.password.encoder= +security.policy.password.previous.count=6 +security.policy.password.expiration.days=90 +security.policy.allowed.login.attempt=3 + +# Password Rules +security.policy.password.rule.alphanumeric.enabled=false +security.policy.password.rule.alphacount.enabled=true +security.policy.password.rule.alphacount.minimum=1 +security.policy.password.rule.characterlength.enabled=true +security.policy.password.rule.characterlength.minimum=1 +security.policy.password.rule.characterlength.maximum=8 +security.policy.password.rule.musthave.enabled=true +security.policy.password.rule.numericalcount.enabled=true +security.policy.password.rule.numericalcount.minimum=1 +security.policy.password.rule.reuse.enabled=true +security.policy.password.rule.nowhitespace.enabled=true ++-----+ + + <<Note:>> Archiva's list of configuration files is <itself> configurable, and + can be found in: + <<<$ARCHIVA_HOME/apps/archiva/webapp/WEB-INF/classes/META-INF/plexus/application.xml>>> + +* 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 <<<plexus.xml>>> file. + + [[1]] Place the jar containing the JDBC driver in <<<$ARCHIVA_HOME/core>>>. + + [[2]] Edit <<<$ARCHIVA_HOME/conf/plexus.xml>>>, providing the JDBC driver class + name, and the database url, username, and password. + + [] + + For example: + ++------+ +<!-- + Datasources +--> +<resource> + <name>jdbc/users</name> + <type>javax.sql.DataSource</type> + <properties> + <property> + <name>driverClassName</name> + <value>org.apache.derby.jdbc.ClientDriver</value> + </property> + <property> + <name>url</name> + <value>jdbc:derby://localhost:1527/archiva-users;create=true</value> + </property> + <property> + <name>username</name> + <value>user1</value> + </property> + <property> + <name>password</name> + <value>user1</value> + </property> + </properties> +</resource> ++------+ + + More information about using Derby Network Server as an external user database + for Archiva can be found on the wiki: + {{{http://docs.codehaus.org/display/MAVENUSER/Archiva+User+DB+on+Derby+Network+Server} + Archiva User DB on Derby Network Server}} |