summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md74
1 files changed, 52 insertions, 22 deletions
diff --git a/README.md b/README.md
index ec1ea69..a999802 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
LEAP Web
---------------------
-"LEAP Web" is the web-based component of the LEAP Platform, providing the following services:
+"LEAP Web" is the web-based component of the LEAP Platform, providing
+the following services:
* REST API for user registration.
* Admin interface to manage users.
@@ -9,9 +10,12 @@ LEAP Web
* User support help tickets.
* Billing
-This web application is written in Ruby on Rails 3, using CouchDB as the backend data store.
+This web application is written in Ruby on Rails 3, using CouchDB as the
+backend data store.
-Original code specific to this web application is licensed under the GNU Affero General Public License (version 3.0 or higher). See http://www.gnu.org/licenses/agpl-3.0.html for more information.
+Original code specific to this web application is licensed under the GNU
+Affero General Public License (version 3.0 or higher). See
+http://www.gnu.org/licenses/agpl-3.0.html for more information.
Documentation
---------------------------
@@ -25,26 +29,31 @@ For more information, see these files in the ``doc`` directory:
Known problems
---------------------------
-* Client certificates are generated without a CSR. The problem is that this makes the web
- application extremely vulnerable to denial of service attacks. This was not an issue until we
- started to allow the possibility of anonymously fetching a client certificate without
+* Client certificates are generated without a CSR. The problem is that
+ this makes the web application extremely vulnerable to denial of
+ service attacks. This is not an issue unless the provider enables the
+ possibility of anonymously fetching a client certificate without
authenticating first.
-* By its very nature, the user database is vulnerable to enumeration attacks. These are
- very hard to prevent, because our protocol is designed to allow query of a user database via
- proxy in order to provide network perspective.
+* By its very nature, the user database is vulnerable to enumeration
+ attacks. These are very hard to prevent, because our protocol is
+ designed to allow query of a user database via proxy in order to
+ provide network perspective.
Installation
---------------------------
-Typically, this application is installed automatically as part of the LEAP Platform. To install it manually for testing or development, follow these instructions:
+Typically, this application is installed automatically as part of the
+LEAP Platform. To install it manually for testing or development, follow
+these instructions:
### Install system requirements
sudo apt-get install git ruby1.9.3 rubygems couchdb
sudo gem install bundler
-On Debian Wheezy or later, there is a Debian package for bundler, so you can alternately run ``sudo apt-get install bundler``.
+On Debian Wheezy or later, there is a Debian package for bundler, so you
+can alternately run ``sudo apt-get install bundler``.
### Download source
@@ -55,15 +64,18 @@ On Debian Wheezy or later, there is a Debian package for bundler, so you can alt
### Install required ruby libraries
cd leap_web
- bundle
+ bundle --binstubs
-Typically, you run ``bundle`` as a normal user and it will ask you for a sudo password when it is time to install the required gems. If you don't have sudo, run ``bundle`` as root.
+Typically, you run ``bundle`` as a normal user and it will ask you for a
+sudo password when it is time to install the required gems. If you don't
+have sudo, run ``bundle`` as root.
Configuration
----------------------------
-The configuration file `config/defaults.yml` providers good defaults for most
-values. You can override these defaults by creating a file `config/config.yml`.
+The configuration file `config/defaults.yml` providers good defaults for
+most values. You can override these defaults by creating a file
+`config/config.yml`.
There are a few values you should make sure to modify:
@@ -76,22 +88,39 @@ There are a few values you should make sure to modify:
client_ca_cert: "/etc/ssl/ca.crt"
ca_key_password: nil
-* `admins` is an array of usernames that are granted special admin privilege.
+* `admins` is an array of usernames that are granted special admin
+ privilege.
+
* `domain` is your fully qualified domain name.
-* `force_ssl`, if set to true, will require secure cookies and turn on HSTS. Don't do this if you are using a self-signed server certificate.
-* `secret_token`, used for cookie security, you can create one with `rake secret`. Should be at least 30 characters.
-* `client_ca_key`, the private key of the CA used to generate client certificates.
-* `client_ca_cert`, the public certificate the CA used to generate client certificates.
+
+* `force_ssl`, if set to true, will require secure cookies and turn on
+ HSTS. Don't do this if you are using a self-signed server certificate.
+
+* `secret_token`, used for cookie security, you can create one with
+ `rake secret`. Should be at least 30 characters.
+
+* `client_ca_key`, the private key of the CA used to generate client
+ certificates.
+
+* `client_ca_cert`, the public certificate the CA used to generate client
+ certificates.
+
* `ca_key_password`, used to unlock the client_ca_key, if needed.
Running
-----------------------------
+To run leap_web:
+
cd leap_web
- rails server
+ bin/rails server
Then open http://localhost:3000 in your web browser.
+When running in development mode, you can login with administrative
+powers by creating an account with username 'staff', 'blue', or 'red'
+(configured in config/default.yml).
+
To peruse the database, visit http://localhost:5984/_utils/
Testing
@@ -105,4 +134,5 @@ To run an individual test:
rake test TEST=certs/test/unit/client_certificate_test.rb
or
- ruby -Itest certs/test/unit/client_certificate_test.rb \ No newline at end of file
+ ruby -Itest certs/test/unit/client_certificate_test.rb
+