Permalink
Browse files

Minor documentation and help text fixes.

Added a git clone step to GETTING-STARTED.

Made clear that copy and paste of grendel.properties won't work
unless you update the jdbc url (and other settings).

Fixed a doc bug (my own) in the database setup script args.

Fixed a doc bug in API for linked-documents.

Updated the copyright notice for the new year.

Added two examples of why you might want to use linked-documents.

Made the help text for example scripts use <document name> instead of
<document> to match the documents/store.sh script (which you'd probably
use first).

Signed-off-by: Coda Hale <coda.hale@gmail.com>
  • Loading branch information...
1 parent df439ee commit 7eba0643515b951473d960d731a812a9c335b771 Marc Hedlund committed with codahale Jan 3, 2010
View
@@ -22,10 +22,9 @@ Examples
All of the operations documented below are demonstrated with shell scripts that
you can find in the
[examples directory](http://github.com/wesabe/grendel/tree/master/examples/).
-These assume that Grendel is running on localhost, port 8080. Run them with
-arguments as shown in the source; for instance:
-
- ./examples/users/create.sh codahale seekritpass
+These assume that Grendel is running on localhost, port 8080. If you run them
+without arguments and they require arguments, a help line will appear showing you
+how to use them.
The full request and response will be shown as output. All the example scripts
use `curl`, a command-line HTTP client.
@@ -395,8 +394,8 @@ Deleting A Linked Document
Sending a `DELETE` request to
`/users/codahale/linked-documents/precipice/document1.txt` will remove the user
-`precipice`'s access to the document named `document1.txt` belonging to user
-`codahale`:
+`codahale`'s access to the document named `document1.txt` belonging to user
+`precipice`:
> DELETE /users/codahale/linked-documents/precipice/document1.txt HTTP/1.1
> Authorization: Basic Y29kYWhhbGU6d29vd29v
View
@@ -43,6 +43,8 @@ For more information, please refer to the
3. Build Grendel
----------------
+Check out the Grendel source with `git clone git://github.com/wesabe/grendel.git`.
+
Run `mvn clean package`. This will download all of Grendel's dependencies,
compile it, run all of its units tests, and create a composite JAR file with all
dependencies included.
@@ -57,13 +59,16 @@ Grendel requires a single configuration file, usually named
`grendel.properties`. It should look something like this:
hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
- hibernate.connection.username=grendel
- hibernate.connection.password=magicsecretsauce
- hibernate.connection.url=jdbc:mysql://grendel.db:3306/grendel?zeroDateTimeBehavior=convertToNull
+ hibernate.connection.username=${DBUSER}
+ hibernate.connection.password=${DBPASSWORD}
+ hibernate.connection.url=jdbc:mysql://${DBHOST}:3306/grendel?zeroDateTimeBehavior=convertToNull
hibernate.c3p0.min_size=10
hibernate.c3p0.max_size=50
hibernate.generate_statistics=true
+Replace ${DBUSER}, ${DBPASSWORD}, and ${DBHOST} with values appropriate for
+your system.
+
The `zeroDateTimeBehavior=convertToNull` option may be required to compensate
for MySQL's storage of null `DATETIME` values as all-zero strings.
@@ -74,15 +79,15 @@ Once you have the properties file in place, create a database and a database
user for Grendel. Create the tables Grendel needs by generating a full database
schema script (see _Run Grendel_, below) and running it. For instance:
- java -jar target/grendel-${VERSION}.jar schema --migration -c grendel.properties > setup-grendel.sql
+ java -jar target/grendel-${VERSION}.jar schema -c grendel.properties > setup-grendel.sql
mysql -u grendel -p grendel < setup-grendel.sql
Grendel should work with relational databases other than MySQL. Simply use an
appropriate JDBC connection URL and Hibernate dialect in the configuration file:
hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
...
- hibernation.connection.url=jdbc:postgres://grendel.db/grendel
+ hibernation.connection.url=jdbc:postgres://${DBHOST}/grendel
You'll also need to place the JDBC drivers for your database on Grendel's
classpath when running Grendel:
View
@@ -3,7 +3,7 @@ Copying Grendel
Grendel is MIT licensed.
-Copyright © 2009 Wesabe, Inc.
+Copyright © 2009, 2010 Wesabe, Inc.
-----------------------------
Permission is hereby granted, free of charge, to any person obtaining
View
@@ -9,7 +9,10 @@ signing/verifying and a sub key for encrypting/decrypting) is generated. When
the user stores a document, the document is signed with the user's master key
and encrypted with their sub key.
-Other users can be granted read-only access to these documents.
+Other users can be granted read-only access to these documents. For instance,
+if a web service stores documents securely for users, a user might grant the
+service administrators temporary shared access to their documents for support
+purposes, or may grant permanent access to another user for sharing purposes.
**To get started using Grendel, read [GETTING-STARTED.md](http://github.com/wesabe/grendel/blob/master/GETTING-STARTED.md).**
@@ -1,7 +1,7 @@
#!/bin/bash
if [ $# -ne 2 ]; then
echo "Delete a document:"
- echo " $0 <id> <document>"
+ echo " $0 <id> <document name>"
exit -1
fi
curl -v -u $1 -X DELETE "http://0.0.0.0:8080/users/$1/documents/$2" && echo
@@ -1,7 +1,7 @@
#!/bin/bash
if [ $# -ne 2 ]; then
echo "Show a document:"
- echo " $0 <id> <document>"
+ echo " $0 <id> <document name>"
exit -1
fi
curl -v -u $1 "http://0.0.0.0:8080/users/$1/documents/$2" && echo
@@ -1,7 +1,7 @@
#!/bin/bash
if [ $# -ne 3 ]; then
echo "Delete a linked document:"
- echo " $0 <id> <other id> <document>"
+ echo " $0 <id> <other id> <document name>"
exit -1
fi
curl -v -u $1 -X DELETE "http://0.0.0.0:8080/users/$1/linked-documents/$2/$3" && echo
@@ -1,7 +1,7 @@
#!/bin/bash
if [ $# -ne 3 ]; then
echo "View a linked document:"
- echo " $0 <id> <other id> <document>"
+ echo " $0 <id> <other id> <document name>"
exit -1
fi
curl -v -u $1 "http://0.0.0.0:8080/users/$1/linked-documents/$2/$3" && echo
@@ -1,7 +1,7 @@
#!/bin/bash
if [ $# -ne 3 ]; then
echo "Add a user to a document's links:"
- echo " $0 <id> <document> <other id>"
+ echo " $0 <id> <document name> <other id>"
exit -1
fi
curl -v -u $1 -X PUT "http://0.0.0.0:8080/users/$1/documents/$2/links/$3" && echo
@@ -1,7 +1,7 @@
#!/bin/bash
if [ $# -ne 3 ]; then
echo "Remove a user from a document's links:"
- echo " $0 <id> <document> <other id>"
+ echo " $0 <id> <document name> <other id>"
exit -1
fi
curl -v -u $1 -X DELETE "http://0.0.0.0:8080/users/$1/documents/$2/links/$3" && echo
@@ -1,7 +1,7 @@
#!/bin/bash
if [ $# -ne 2 ]; then
echo "Show all links for a document:"
- echo " $0 <id> <document>"
+ echo " $0 <id> <document name>"
exit -1
fi
curl -v -u $1 "http://0.0.0.0:8080/users/$1/documents/$2/links/" && echo

0 comments on commit 7eba064

Please sign in to comment.