From c97d6d8c59540dea6e5f2483a63537e551250b90 Mon Sep 17 00:00:00 2001 From: Johannes Utzig Date: Thu, 19 Dec 2013 23:51:18 +0100 Subject: [PATCH] closes #129 - Create a setup guide --- src/site/markdown/installation.md | 9 +++++ src/site/markdown/jaasConfig.md | 32 ++++++++++++++++ src/site/markdown/standaloneInstallation.md | 41 +++++++++++++++++++++ src/site/markdown/startupParameters.md | 27 ++++++++++++++ src/site/markdown/warInstallation.md | 22 +++++++++++ src/site/site.xml | 14 +++++-- 6 files changed, 142 insertions(+), 3 deletions(-) create mode 100644 src/site/markdown/installation.md create mode 100644 src/site/markdown/jaasConfig.md create mode 100644 src/site/markdown/standaloneInstallation.md create mode 100644 src/site/markdown/startupParameters.md create mode 100644 src/site/markdown/warInstallation.md diff --git a/src/site/markdown/installation.md b/src/site/markdown/installation.md new file mode 100644 index 00000000..70bbd077 --- /dev/null +++ b/src/site/markdown/installation.md @@ -0,0 +1,9 @@ + +# Installation + +No matter if you choose to install Jabylon as a standalone application or deploy a WAR in your favorite application server, there is only minimal configuration effort involved. + +The following pages will cover the different installation methods: + + * [Installing as a web application](warInstallation.html) + * [Installing standalone](standaloneInstallation.html) \ No newline at end of file diff --git a/src/site/markdown/jaasConfig.md b/src/site/markdown/jaasConfig.md new file mode 100644 index 00000000..a96e10f2 --- /dev/null +++ b/src/site/markdown/jaasConfig.md @@ -0,0 +1,32 @@ + +# Security Settings + +Jabylon comes with 2 pre-installed security modules. However, it is designed in an extensible fashion so you can provide additional [JAAS](http://en.wikipedia.org/wiki/Java_Authentication_and_Authorization_Service) login module plug-ins as required. + +Which security modules are used in which order depends on the contents of `configuration/jaas.config`. You can add, delete, modify and reorder the modules there as you see fit. + + +## Database Login + +The default login module is the internal database login. All users, their passwords, roles and additional data is stored in the database. You do not have to configure anything to use this module. + +There are two system users predefined. The user `Administrator` with the password `changeme` has all permissions. The second user is called `Anonymous` and has no password. A user that is not logged in is automatically considered `Anonymous`. + +By default this user has permission to browse the projects, but not edit them. You can remove permissions or add additional ones as you see fit. + + +## LDAP Authentication + +The second pre-installed module enables LDAP authentication. On first login Jabylon creates a new user in the internal database that is linked to the LDAP account. The password will only be in LDAP (and the user cannot change it) but the roles and additional information (email, full name,...) are synced from LDAP into the internal database. + +To enable LDAP authentication you need to enter a few parameters into `configuration/jaas.config` + + * **ldap** the ldap server url + * **ldap.port** the ldap server port + * **root.dn** the root dn to query agains + * **manager** the CN of the manager. Jabylon will use this account to access LDAP + * **manager.password** the password of the manager. Jabylon will use this account to access LDAP + * **user.id** the uid attribute of a user + * **user.name** the full name attribute of a user (optional) + * **user.mail** the email attribute of a user (optional) + \ No newline at end of file diff --git a/src/site/markdown/standaloneInstallation.md b/src/site/markdown/standaloneInstallation.md new file mode 100644 index 00000000..19b2e424 --- /dev/null +++ b/src/site/markdown/standaloneInstallation.md @@ -0,0 +1,41 @@ + +# Installing as a Standalone Application + +Jabylon can be launched as a standalone application with an embedded jetty server. To do that, start by [downloading](./download.html) the standalone distribution and extracting it to a directory of your choice. Please make sure that the user running Jabylon has write permission in this directory. + +## Starting Jabylon on Linux + +If you are running Jabylon on a linux system you can use the available startup scripts. To do so, open a shell, `cd` to the directory where you extracted Jabylon and run + +`./jabylon.sh start` + +Jabylon should now start up and be available at [http://localhost:8080](http://localhost:8080). + +You can change the default port by specifying `--port {PORT}`. By default, Jabylon will be bound to all interfaces. To change this setting you can specifiy `--host {IP_ADDRESS}` + +Jabylon needs a working directory to store the translation projects and the embedded database. By default this directory is located at `jabylon/workspace`. To change this default specify `--data {WORKSPACE}` on command line. + +The logs will be placed to `logs/jabylon.log` by default. To change this location you can set the system property `-Djabylon.log`. + +Here is an example on how to configure these settings in a command line: + +`./jabylon.sh --port 10000 --host 127.0.01 --data /opt/jabylon start` + + +## Starting Jabylon on Windows + +There is currently no startup script for windows available so you will need to start the launcher jar directly. To do so, open a terminal and `cd` to the directory where you extracted Jabylon. To start with default settings (Port 8080) execute + +`java -jar plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar` + +To adjust the defaults you can set these system properties: + + * org.eclipse.equinox.http.jetty.http.host={HOST} to change the IP address that Jabylon will be bound to (all by default) + * org.eclipse.equinox.http.jetty.http.port={PORT} to change the port Jabylon is using + * osgi.instance.area={WORKSPACE} to change the location of the workspace + * jabylon.log={LOG_DIR) to change where the logfiles will be located + + The resulting command line could look like this: + + `java -Dosgi.instance.area=C:\Jabylon -jar plugins/org.eclipse.equinox.launcher_1.2.0.v20110502.jar` + diff --git a/src/site/markdown/startupParameters.md b/src/site/markdown/startupParameters.md new file mode 100644 index 00000000..6ae6da11 --- /dev/null +++ b/src/site/markdown/startupParameters.md @@ -0,0 +1,27 @@ + +# Available Startup Parameters + +Jabylon can be configured by providing a set of parameters and system properties. How to apply them depends on your deployment method. + + +## Command Line Parameters + +These parameters apply to the `jabylon.sh` script of the[standalone application](./download.html) + + * **--port -p** same as org.eclipse.equinox.http.jetty.http.port + * **--host -h** same as org.eclipse.equinox.http.jetty.http.host + * **--data -d** same as osgi.instance.area + + +## System Properties + + * **jabylon.log** the location for the log files + * default is `logs` + * **JABYLON_HOME** where the workspace should be created + * default is `workspace` + * **osgi.instance.area** the workspace and configuration data will end up in this directory + * default is the installation directory + * **org.eclipse.equinox.http.jetty.http.port** the port that Jabylon listens to + * default is 8080 + * **org.eclipse.equinox.http.jetty.http.host** the network interface that Jabylon listens to + * default is 0.0.0.0 (all) \ No newline at end of file diff --git a/src/site/markdown/warInstallation.md b/src/site/markdown/warInstallation.md new file mode 100644 index 00000000..83219f1c --- /dev/null +++ b/src/site/markdown/warInstallation.md @@ -0,0 +1,22 @@ + +# Installing as a web application + +Jabylon can be deployed into any Java EE application server. This document will show an example on how to do that in Tomcat 7 which can be downloaded [here](http://tomcat.apache.org/download-70.cgi) and Jetty 9 which can be downloaded [here](http://download.eclipse.org/jetty/). + +## Deploying Archiva in Tomcat 7 + +[Download](./download.html) the Jabylon WAR and copy it into `tomcat/webapps`. +Now you can run tomcat with e.g `bin/startup.sh`. Jabylon should automatically get deployed and be available at [http://localhost:8080/jabylon](http://localhost:8080/jabylon). + +Jabylon needs a working directory to store the translation projects and the embedded database. By default this directory is located at `$HOME/jabylon`. To change this default edit the file `conf/catalina.properties` and add the value `JABYLON_HOME=/opt/jabylon`. You will have to restart tomcat after saving the file. + +The logs will be placed to `logs/jabylon.log` by default. To change this location you can set the system property `jabylon.log` (this can be done in `conf/catalina.properties` again). + +## Deploying Archiva in Jetty + +[Download](./download.html) the Jabylon WAR and copy it into `jetty/webapps`. +Now you can run jetty with `java -jar start.jar`. Jabylon should automatically get deployed and be available at [http://localhost:8080/jabylon](http://localhost:8080/jabylon). + +Jabylon needs a working directory to store the translation projects and the embedded database. By default this directory is located at `$HOME/jabylon`. To change this default start jetty with the command line `java -DJABYLON_HOME=/opt/jabylon -jar start.jar`. + +The logs will be placed to `logs/jabylon.log` by default. To change this location you can set the system property `jabylon.log`. \ No newline at end of file diff --git a/src/site/site.xml b/src/site/site.xml index 2bcc0753..7ed38b00 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -7,7 +7,7 @@ Maven - http://maven.apache.org/images/apache-maven-project.png + http://maven.apache.org/ @@ -23,8 +23,16 @@ - - + + + + + + + + + +