Skip to content

Commit c5bf343

Browse files
idlewisidlewis
committed
Merge pull request #29 from WASdev/update-docs
Doc updates.
2 parents 20c5120 + 8634deb commit c5bf343

4 files changed

Lines changed: 184 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 30 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,66 @@
11
# LARS
22

3-
The Liberty Asset Repository Service implements a repository for Liberty features that you can deploy locally. You can host features you have developed and features retrieved from the Websphere Liberty Repository, and then use your Liberty server's installUtility command to install the hosted features into your server.
3+
The Liberty Asset Repository Service implements a repository for
4+
Liberty features that you can deploy locally. You can host features
5+
you have developed and features retrieved from the Websphere Liberty
6+
Repository, and then use your Liberty server's installUtility command
7+
to install the hosted features into your server.
48

5-
LARS is currently pre-release. Although it has been tested as a repository for a Liberty server, we recommend it is currently used for evaluation only.
9+
## Documentation
610

7-
# Building
11+
The LARS documentation is organized into a number of pages:
812

9-
Make sure you have the following prerequisites installed: (older or newer versions may work but this is what we've tested with)
13+
* [Building LARS] (doc/BUILDING.md)
14+
* [Installing LARS] (doc/INSTALL.md)
15+
* [Using `larsClient`] (doc/LARSCLIENT.md)
1016

11-
* [gradle v2.0](http://gradle.org/downloads)
12-
* [mongoDB v2.6](https://www.mongodb.org/downloads)
13-
* [WAS Liberty Profile 8.5.5.5](https://developer.ibm.com/wasdev/downloads/#asset/runtimes-8.5.5-wlp-runtime)
14-
* [MongoDB Integration 2.0 Feature](https://developer.ibm.com/assets/wasdev/#asset/features-com.ibm.websphere.appserver.mongodb-2.0)
15-
* A Java 7 JDK
17+
## Getting started
1618

17-
Either clone the repository or download and extract a snapshot
19+
The easiest way to install LARS is directly from the Liberty
20+
Repository using `installUtility`. Run:
1821

19-
Edit `server/gradle.properties` to point to your mongodb and liberty installation directories.
22+
bin/installUtility install larsServer
2023

21-
Have a look at `test-utils/src/main/resources/config.properties` and check that you are happy with the
22-
specified test ports
23-
24-
Launch gradle to build the code, run the tests and produce the distribution archives.
25-
26-
gradle build dist
27-
28-
You should now have two files in the build/distributions directory, `larsServer.zip` and `larsClient.zip`
29-
30-
# Installing
31-
32-
Unzip larsServer.zip into the install directory of your liberty server. (The one which contains the `usr` directory)
33-
34-
Open `usr/servers/larsServer/server.xml` and follow the directions in the comments to create users and assign them to User and Administrator roles in the larsServer application
35-
36-
Find the JNDI entry named `lars/URLBase` and edit the value to point to the external URL of the server.
37-
38-
If your mongodb server is not running on the same machine as your liberty server or uses authentication, you must also edit the mongodb configuration in the server.xml
24+
You need to customize `server.xml`. See [Installing LARS]
25+
(doc/INSTALL.md) for more details.
3926

4027
Start mongodb
4128

4229
Now start the server
4330

4431
bin/server start larsServer
4532

46-
The server should now be running. Unless you've changed the default config, you should be able to visit http://localhost:9080/ma/v1/assets and see an empty list.
33+
The server should now be running. Unless you've changed the default
34+
config, you should be able to visit http://localhost:9080/ma/v1/assets
35+
and see an empty list.
4736

4837
[]
4938

50-
# Adding assets
39+
## Adding assets
5140

5241
Unzip `larsClient.zip` and then run `larsClient` to upload an asset.
5342

5443
bin/larsClient upload --url=http://localhost:9080/ma/v1 --username=admin --password userFeature.esa
5544

56-
Enter your password when prompted. You should see a message saying that the feature has been uploaded
45+
Enter your password when prompted. You should see a message saying
46+
that the feature has been uploaded
5747

58-
# Listing assets
48+
## Listing assets
5949

6050
bin/larsClient listAll --url=http://localhost:9080/ma/v1
6151

62-
If you changed the config to require authentication for the user role, you'll need to provide your username and password as you did when adding an asset. You should see some output like this:
52+
If you changed the config to require authentication for the user role,
53+
you'll need to provide your username and password as you did when
54+
adding an asset. You should see some output like this:
6355

6456
Listing all assets in the repository:
6557
Asset ID | Asset Type | Liberty Version | Asset Name
6658
54da04d8735612bfdb13bf56 | Feature | | com.ibm.ws.test.userFeature
6759

68-
# Deleting assets
60+
## Deleting assets
6961

70-
The list command shows the asset id. You can use this to delete the asset from the repository
62+
The list command shows the asset id. You can use this to delete the
63+
asset from the repository
7164

7265
bin/larsClient delete --url=http://localhost:9080/ma/v1 --username=adminUser --password 123456789103456789
66+

‎doc/BUILDING.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Building LARS
2+
3+
Make sure you have the following prerequisites installed: (older or
4+
newer versions may work but this is what we've tested with)
5+
6+
* [gradle v2.0](http://gradle.org/downloads)
7+
* [mongoDB v2.6](https://www.mongodb.org/downloads#previous)
8+
* [WAS Liberty Profile 8.5.5.6](https://developer.ibm.com/wasdev/downloads/#asset/runtimes-8.5.5-wlp-runtime).
9+
* Your Liberty runtime must contain the following features several features, which can be installed using `installUtility` as follows:
10+
bin/installUtility install cdi-1.0 servlet-3.0 mongodb-2.0 jaxrs-1.1 cdi-1.0 servlet-3.0 mongodb-2.0 jaxrs-1.1
11+
12+
* [Liberty MongoDB Integration 2.0 Feature](https://developer.ibm.com/assets/wasdev/#asset/features-com.ibm.websphere.appserver.mongodb-2.0)
13+
* A Java 7 JDK
14+
15+
Either clone the repository or download and extract a snapshot
16+
17+
Edit `server/gradle.properties` to point to your mongodb and liberty
18+
installation directories.
19+
20+
Have a look at `test-utils/src/main/resources/config.properties` and
21+
check that you are happy with the specified test ports
22+
23+
Launch gradle to build the code, run the tests and produce the
24+
distribution archives.
25+
26+
gradle build dist
27+
28+
You should now have three files in the build/distributions directory,
29+
`larsServer.zip`, `larsClient.zip` and `larsServerPackage.jar`.
30+

‎doc/INSTALL.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Installing and configuring LARS
2+
3+
There are three ways that you can install LARS:
4+
5+
* Directly from the Liberty Repository using installUtility
6+
* Using the self-extracting jar installer from the Liberty Repository
7+
* By building and then unzipping larsServer.zip
8+
9+
Whichever installation method you use, you will also need to configure
10+
LARS.
11+
12+
## Installing LARS directly from the Liberty Repository using `installUtility`
13+
14+
This is the simplest method of installing LARS. From the `wlp`
15+
directory of your Liberty 8.5.5.6 runtime, run the following command:
16+
17+
bin/installUtility install larsServer
18+
19+
`installUtility` downloads LARS together with the application server
20+
features upon which it depends.
21+
22+
## Using the self-extracting jar installer from the Liberty Repository
23+
24+
Visit [this
25+
page](https://developer.ibm.com/wasdev/downloads/#asset/opensource-Liberty_Asset_Repository_Service)
26+
and click Download to download `larsServerPackage.jar`. Once the
27+
download is complete, run `larsServerPackage.jar`. For example, on the
28+
command line, run the following:
29+
30+
java -jar larsServerPackage.jar
31+
32+
You must specify the installation directory of an existing Liberty
33+
runtime. If that Libety runtime does not contain any of LARS's
34+
prerequiste features then you can install them using `installUtility`:
35+
36+
bin/installUtility install cdi-1.0 servlet-3.0 mongodb-2.0 jaxrs-1.1 cdi-1.0 servlet-3.0 mongodb-2.0 jaxrs-1.1
37+
38+
## By building and then unzipping larsServer.zip
39+
40+
If you have built LARS yourself then you can find larsServer.zip in
41+
the `build/distributions` directory. Unzip larsServer.zip into the
42+
`wlp` directory of an existing Liberty runtime.
43+
44+
Note that your Liberty runtime must contain LARS's pre-requising features, which you can install using `installUtility` as above.
45+
46+
47+
## Configuring LARS
48+
49+
LARS is a Java EE application running on top of Liberty and can be
50+
configured like any other Liberty application. When LARS is installed,
51+
it creates a new Liberty server called `larsServer`. To configure
52+
LARS, edit the file `wlp/usr/servers/larsServer/server.xml`. For a
53+
basic LARS server, you will need to configure the following:
54+
55+
### User registry
56+
57+
In order to secure LARS (and it is not recommended to run LARS without
58+
security), you need a user registry. The default `server.xml` that is
59+
created when LARS is installed contains a `<basicRegistry>`, commented
60+
out, that can be uncommented and used as a starting point. For more
61+
information on configuring a user registry for Liberty, see [Configuring a user registry for the Liberty profile](http://www-01.ibm.com/support/knowledgecenter/SSAW57_8.5.5/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_sec_registries.html?cp=SSAW57_8.5.5%2F3-12-1-2-0).
62+
63+
### HTTP endpoint
64+
65+
The `<httpEndpoint>` element determines upon which ports the LARS
66+
server will listen. You can changed these ports to suit your
67+
requirements. In the default configuration, the LARS server only
68+
listens for connections from localhost (ie connections from the same
69+
host that LARS is running on). You can also add a `host=` attribute to
70+
cause LARS to listen for requests from other hosts. For more
71+
information on configuring Liberty's HTTP endpoint properties, see
72+
[Liberty profile: Configuration elements in the server.xml
73+
file](http://www-01.ibm.com/support/knowledgecenter/SSAW57_8.5.5/com.ibm.websphere.wlp.nd.multiplatform.doc/autodita/rwlp_metatype_4ic.html?cp=SSAW57_8.5.5%2F3-0-2-1-0).
74+
75+
### User to role mappings
76+
77+
The default `server.xml` configuration contains a commented-out
78+
`<application-bnd>` element. You can uncomment this and then customize
79+
it to your requirements. For more information on configuring
80+
authorization for applications on Liberty, see [Configuring authorization for applications on the Liberty profile](http://www-01.ibm.com/support/knowledgecenter/SSAW57_8.5.5/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_sec_rolebased.html?cp=SSAW57_8.5.5%2F3-12-1-3-0).
81+
82+
### MongoDB configuration
83+
84+
If your MongoDB instance uses authentication or if other parameters, such as the MongoDB port, are non-default then you may need to customize the `<mongo>` and `<mongoDB>` elements in server.xml. For more information on configuring Liberty's MongoDB feature, see [Creating Liberty applications that use MongoDB] (http://www-01.ibm.com/support/knowledgecenter/SSAW57_8.5.5/com.ibm.websphere.wlp.nd.multiplatform.doc/ae/twlp_mongodb_create.html?cp=SSAW57_8.5.5%2F3-8-1-2-17-0-1).

‎doc/LARSCLIENT.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Using larsClient
2+
3+
`larsClient` allows you to add assets to LARS, to list assets and to
4+
delete assets. Like Liberty itself, `larsClient` requires Java. You
5+
must either set JAVA_HOME to point to a Java 7 runtime environment or
6+
you must add a Java 7 executable to your PATH.
7+
8+
For full details of command line parameters, run
9+
10+
bin/larsClient help
11+
12+
and
13+
14+
bin/larsClient help <command-name>
15+
16+
## Adding assets
17+
18+
You can add one asset by specifying the file containing that asset:
19+
20+
bin/larsClient upload --url=http://localhost:9080/ma/v1 --username=admin --password userFeature.esa
21+
22+
You can also add multiple assets by specifying the name of a directory
23+
that directly contains those assets. Note that larsClient does not
24+
search subdirectories for assets when you do this.
25+
26+
bin/larsClient upload --url=http://localhost:9080/ma/v1 --username=admin --password /home/liberty/javaee7Bundle/features/8.5.5.6/
27+
28+
## Listing assets
29+
30+
You can list all assets in LARS as follows:
31+
32+
bin/larsClient listAll --url=http://localhost:9080/ma/v1
33+
34+
## Deleting assets
35+
36+
You can delete an asset from LARS using the delete command by specifying the id of the asset. For example:
37+
38+
bin/larsClient delete --url=http://localhost:9080/ma/v1 --username=adminUser --password 123456789103456789
39+
40+

0 commit comments

Comments
 (0)