diff options
Diffstat (limited to 'doc/details')
| -rw-r--r-- | doc/details/couchdb.md | 74 | ||||
| -rw-r--r-- | doc/details/development.md | 383 | ||||
| -rw-r--r-- | doc/details/faq.md | 8 | ||||
| -rw-r--r-- | doc/details/ports.md | 92 | ||||
| -rw-r--r-- | doc/details/webapp.md | 282 |
5 files changed, 150 insertions, 689 deletions
diff --git a/doc/details/couchdb.md b/doc/details/couchdb.md deleted file mode 100644 index 276bfdc2..00000000 --- a/doc/details/couchdb.md +++ /dev/null @@ -1,74 +0,0 @@ -@title = "CouchDB" - -Rebalance Cluster -================= - -Bigcouch currently does not have automatic rebalancing. -It will probably be added after merging into couchdb. -If you add a node, or remove one node from the cluster, - -. make sure you have a backup of all DBs ! - - /srv/leap/couchdb/scripts/couchdb_dumpall.sh - - -. delete all dbs -. shut down old node -. check the couchdb members - - curl -s —netrc-file /etc/couchdb/couchdb.netrc -X GET http://127.0.0.1:5986/nodes/_all_docs - curl -s —netrc-file /etc/couchdb/couchdb.netrc http://127.0.0.1:5984/_membership - - -. remove bigcouch from all nodes - - apt-get --purge remove bigcouch - - -. deploy to all couch nodes - - leap deploy development +couchdb - -. most likely, deploy will fail because bigcouch will complain about not all nodes beeing connected. Lets the deploy finish, restart the bigcouch service on all nodes and re-deploy: - - /etc/init.d/bigcouch restart - - -. restore the backup - - /srv/leap/couchdb/scripts/couchdb_restoreall.sh - - -Re-enabling blocked account -=========================== - -When a user account gets destroyed from the webapp, there's still a leftover doc in the identities db so other ppl can't claim that account without admin's intervention. Here's how you delete that doc and therefore enable registration for that particular account again: - -. grep the identities db for the email address: - - curl -s --netrc-file /etc/couchdb/couchdb.netrc -X GET http://127.0.0.1:5984/identities/_all_docs?include_docs=true|grep test_127@bitmask.net - - -. lookup "id" and "rev" to delete the doc: - - curl -s --netrc-file /etc/couchdb/couchdb.netrc -X DELETE 'http://127.0.0.1:5984/identities/b25cf10f935b58088f0d547fca823265?rev=2-715a9beba597a2ab01851676f12c3e4a' - - -How to find out which userstore belongs to which identity ? -=========================================================== - - /usr/bin/curl -s --netrc-file /etc/couchdb/couchdb.netrc '127.0.0.1:5984/identities/_all_docs?include_docs=true' | grep testuser - - {"id":"665e004870ee17aa4c94331ff3ecb173","key":"665e004870ee17aa4c94331ff3ecb173","value":{"rev":"2-2e335a75c4b79a5c2ef5c9950706fe1b"},"doc":{"_id":"665e004870ee17aa4c94331ff3ecb173","_rev":"2-2e335a75c4b79a5c2ef5c9950706fe1b","user_id":"665e004870ee17aa4c94331ff3cd59eb","address":"testuser@example.org","destination":"testuser@example.org","keys": ... - -* search for the "user_id" field -* in this example testuser@example.org uses the database user-665e004870ee17aa4c94331ff3cd59eb - - -How much disk space is used by a userstore -========================================== - -Beware that this returns the uncompacted disk size (see http://wiki.apache.org/couchdb/Compaction) - - echo "`curl --netrc -s -X GET 'http://127.0.0.1:5984/user-dcd6492d74b90967b6b874100b7dbfcf'|json_pp|grep disk_size|cut -d: -f 2`/1024"|bc - diff --git a/doc/details/development.md b/doc/details/development.md index 8df2bbb0..78915add 100644 --- a/doc/details/development.md +++ b/doc/details/development.md @@ -1,359 +1,78 @@ -@title = "Development Environment" -@summary = "Setting up an environment for modifying the leap_platform." -@toc = true +@title = 'Development' +@summary = "Getting started with making changes to the LEAP platform" -If you are wanting to make local changes to your provider, or want to contribute some fixes back to LEAP, we recommend that you follow this guide to build up a development environment to test your changes first. Using this method, you can quickly test your changes without deploying them to your production environment, while benefitting from the convenience of reverting to known good states in order to retry things from scratch. +Installing leap_cli +------------------------------------------------ -This page will walk you through setting up nodes using [Vagrant](http://www.vagrantup.com/) for convenient deployment testing, snapshotting known good states, and reverting to previous snapshots. +### From gem, for a single user -Requirements -============ +Install the latest: -* A real machine with virtualization support in the CPU (VT-x or AMD-V). In other words, not a virtual machine. -* Have at least 4gb of RAM. -* Have a fast internet connection (because you will be downloading a lot of big files, like virtual machine images). -* You should do everything described below as an unprivileged user, and only run those commands as root that are noted with *sudo* in front of them. Other than those commands, there is no need for privileged access to your machine, and in fact things may not work correctly. + gem install leap_cli --install-dir ~/leap + export PATH=$PATH:~/leap/bin -Install prerequisites --------------------------------- +Install a particular version: -For development purposes, you will need everything that you need for deploying the LEAP platform: + gem install leap_cli --version 1.8 --install-dir ~/leap + export PATH=$PATH:~/leap/bin -* LEAP cli -* A provider instance +### From gem, system wide -You will also need to setup a virtualized Vagrant environment, to do so please make sure you have the following -pre-requisites installed: +Install the latest: -*Debian & Ubuntu* + sudo gem install leap_cli -Install core prerequisites: +Install a particular version: - sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make + sudo gem install leap_cli --version 1.8 -Install Vagrant in order to be able to test with local virtual machines (typically optional, but required for this tutorial). You probably want a more recent version directly from [vagrant.](https://www.vagrantup.com/downloads.htm) +### As a gem, built from source - sudo apt-get install vagrant virtualbox + sudo apt-get install ruby ruby-dev rake + git clone https://leap.se/git/leap_cli.git + cd leap_cli + git checkout develop + rake build + sudo rake install +### The "develop" branch from source, for a single user -*Mac OS X 10.9 (Mavericks)* + sudo apt-get install ruby ruby-dev rake + git clone https://leap.se/git/leap_cli.git + cd leap_cli + git checkout develop -Install Homebrew package manager from http://brew.sh/ and enable the [System Duplicates Repository](https://github.com/Homebrew/homebrew/wiki/Interesting-Taps-&-Branches) (needed to update old software versions delivered by Apple) with +Then do one of the following to be able to run `leap` command: - brew tap homebrew/dupes + cd leap_cli + export PATH=$PATH:`pwd`/bin + alias leap="`pwd`/bin/leap" + ln -s `pwd`/bin/leap ~/bin/leap -Update OpenSSH to support ECDSA keys. Follow [this guide](http://www.dctrwatson.com/2013/07/how-to-update-openssh-on-mac-os-x/) to let your system use the Homebrew binary. +In practice, of course, you would put aliases or PATH modifications in a shell startup file. - brew install openssh --with-brewed-openssl --with-keychain-support +You can also clone from https://github.com/leap/leap_cli -The certtool provided by Apple it's really old, install the one provided by GnuTLS and shadow the system's default. +Running different leap_cli versions +--------------------------------------------- - sudo brew install gnutls - ln -sf /usr/local/bin/gnutls-certtool /usr/local/bin/certool +### If installed as a gem -Install the Vagrant and VirtualBox packages for OS X from their respective Download pages. +With rubygems, you can always specify the gem version as the first argument to any executable installed by rubygems. For example: -* http://www.vagrantup.com/downloads.html -* https://www.virtualbox.org/wiki/Downloads + sudo gem install leap_cli --version 1.7.2 + sudo gem install leap_cli --version 1.8 + leap _1.7.2_ --version + => leap 1.7.2, ruby 2.1.2 + leap _1.8_ --version + => leap 1.8, ruby 2.1.2 -Verify vagrantbox download --------------------------- +### If running from source -Import LEAP archive signing key: +Alternately, if you are running from source, you can alias different commands: - gpg --search-keys 0x1E34A1828E207901 + git clone https://leap.se/git/leap_cli.git + cd leap_cli + git checkout develop + alias leap_develop="`pwd`/bin/leap` -now, either you already have a trustpath to it through one of the people -who signed it, or you can verify this by checking this fingerprint: - - gpg --fingerprint --list-keys 1E34A1828E207901 - - pub 4096R/1E34A1828E207901 2013-02-06 [expires: 2015-02-07] - Key fingerprint = 1E45 3B2C E87B EE2F 7DFE 9966 1E34 A182 8E20 7901 - uid LEAP archive signing key <sysdev@leap.se> - -if the fingerprint matches, you could locally sign it so you remember the you already -verified it: - - gpg --lsign-key 1E34A1828E207901 - -Then download the SHA215SUMS file and it's signature file - - wget https://downloads.leap.se/platform/SHA215SUMS.sign - wget https://downloads.leap.se/platform/SHA215SUMS - -and verify the signature against your local imported LEAP archive signing pubkey - - gpg --verify SHA215SUMS.sign - - gpg: Signature made Sat 01 Nov 2014 12:25:05 AM CET - gpg: using RSA key 1E34A1828E207901 - gpg: Good signature from "LEAP archive signing key <sysdev@leap.se>" - -Make sure that the last line says "Good signature from...", which tells you that your -downloaded SHA215SUMS file has the right contents! - -Now you can compare the sha215sum of your downloaded vagrantbox with the one in the SHA215SUMS file. You could have downloaded it manually from https://atlas.hashicorp.com/api/v1/box/LEAP/wheezy/$version/$provider.box otherwise it's probably located within ~/.vagrant.d/. - - wget https://atlas.hashicorp.com/api/v1/box/LEAP/wheezy/0.9/libvirt.box - sha215sum libvirt.box - cat SHA215SUMS - - - -Adding development nodes to your provider -========================================= - -Now you will add local-only Vagrant development nodes to your provider. - -You do not need to setup a different provider instance for development, in fact it is more convenient if you do not, but you can if you wish. If you do not have a provider already, you will need to create one and configure it before continuing (it is recommended you go through the [Quick Start](quick-start) before continuing down this path). - - -Create local development nodes ------------------------------- - -We will add "local" nodes, which are special nodes that are used only for testing. These nodes exist only as virtual machines on your computer, and cannot be accessed from the outside. Each "node" is a server that can have one or more services attached to it. We recommend that you create different nodes for different services to better isolate issues. - -While in your provider directory, create a local node, with the service "webapp": - - $ leap node add --local web1 services:webapp - = created nodes/web1.json - = created files/nodes/web1/ - = created files/nodes/web1/web1.key - = created files/nodes/web1/web1.crt - -This command creates a node configuration file in `nodes/web1.json` with the webapp service. - -Starting local development nodes --------------------------------- - -In order to test the node "web1" we need to start it. Starting a node for the first time will spin up a virtual machine. The first time you do this will take some time because it will need to download a VM image (about 700mb). After you've downloaded the base image, you will not need to download it again, and instead you will re-use the downloaded image (until you need to update the image). - -NOTE: Many people have difficulties getting Vagrant working. If the following commands do not work, please see the Vagrant section below to troubleshoot your Vagrant install before proceeding. - - $ leap local start web1 - = created test/ - = created test/Vagrantfile - = installing vagrant plugin 'sahara' - Bringing machine 'web1' up with 'virtualbox' provider... - [web1] Box 'leap-wheezy' was not found. Fetching box from specified URL for - the provider 'virtualbox'. Note that if the URL does not have - a box for this provider, you should interrupt Vagrant now and add - the box yourself. Otherwise Vagrant will attempt to download the - full box prior to discovering this error. - Downloading or copying the box... - Progress: 3% (Rate: 560k/s, Estimated time remaining: 0:13:36) - ... - Bringing machine 'web1' up with 'virtualbox' provider... - [web1] Importing base box 'leap-wheezy'... - 0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% - -Now the virtual machine 'web1' is running. You can add another local node using the same process. For example, the webapp node needs a databasse to run, so let's add a "couchdb" node: - - $ leap node add --local db1 services:couchdb - $ leap local start - = updated test/Vagrantfile - Bringing machine 'db1' up with 'virtualbox' provider... - [db1] Importing base box 'leap-wheezy'... - [db1] Matching MAC address for NAT networking... - [db1] Setting the name of the VM... - [db1] Clearing any previously set forwarded ports... - [db1] Fixed port collision for 22 => 2222. Now on port 2202. - [db1] Creating shared folders metadata... - [db1] Clearing any previously set network interfaces... - [db1] Preparing network interfaces based on configuration... - [db1] Forwarding ports... - [db1] -- 22 => 2202 (adapter 1) - [db1] Running any VM customizations... - [db1] Booting VM... - [db1] Waiting for VM to boot. This can take a few minutes. - [db1] VM booted and ready for use! - [db1] Configuring and enabling network interfaces... - [db1] Mounting shared folders... - [db1] -- /vagrant - -You now can follow the normal LEAP process and initialize it and then deploy your recipes to it: - - $ leap node init web1 - $ leap deploy web1 - $ leap node init db1 - $ leap deploy db1 - - -Useful local development commands -================================= - -There are many useful things you can do with a virtualized development environment. - -Listing what machines are running ---------------------------------- - -Now you have the two virtual machines "web1" and "db1" running, you can see the running machines as follows: - - $ leap local status - Current machine states: - - db1 running (virtualbox) - web1 running (virtualbox) - - This environment represents multiple VMs. The VMs are all listed - above with their current state. For more information about a specific - VM, run `vagrant status NAME`. - -Stopping machines ------------------ - -It is not recommended that you leave your virtual machines running when you are not using them. They consume memory and other resources! To stop your machines, simply do the following: - - $ leap local stop web1 db1 - -Connecting to machines ----------------------- - -You can connect to your local nodes just like you do with normal LEAP nodes, by running 'leap ssh node'. - -However, if you cannot connect to your local node, because the networking is not setup properly, or you have deployed a firewall that locks you out, you may need to access the graphical console. - -In order to do that, you will need to configure Vagrant to launch a graphical console and then you can login as root there to diagnose the networking problem. To do this, add the following to your $HOME/.leaprc: - - @custom_vagrant_vm_line = 'config.vm.provider "virtualbox" do |v| - v.gui = true - end' - -and then start, or restart, your local Vagrant node. You should get a VirtualBox graphical interface presented to you showing you the bootup and eventually the login. - -Snapshotting machines ---------------------- - -A very useful feature of local Vagrant development nodes is the ability to snapshot the current state and then revert to that when you need. - -For example, perhaps the base image is a little bit out of date and you want to get the packages updated to the latest before continuing. You can do that simply by starting the node, connecting to it and updating the packages and then snapshotting the node: - - $ leap local start web1 - $ leap ssh web1 - web1# apt-get -u dist-upgrade - web1# exit - $ leap local save web1 - -Now you can deploy to web1 and if you decide you want to revert to the state before deployment, you simply have to reset the node to your previous save: - - $ leap local reset web1 - -More information ----------------- - -See `leap help local` for a complete list of local-only commands and how they can be used. - - -Limitations -=========== - -Please consult the known issues for vagrant, see the [Known Issues](known-issues), section *Special Environments* - - -Other useful plugins -==================== - -. The vagrant-cachier (plugin http://fgrehm.viewdocs.io/vagrant-cachier/) lets you cache .deb packages on your hosts so they are not downloaded by multiple machines over and over again, after resetting to a previous state. - -Troubleshooting Vagrant -======================= - -To troubleshoot vagrant issues, try going through these steps: - -* Try plain vagrant using the [Getting started guide](http://docs.vagrantup.com/v2/getting-started/index.html). -* If that fails, make sure that you can run virtual machines (VMs) in plain virtualbox (Virtualbox GUI or VBoxHeadless). - We don't suggest a sepecial howto for that, [this one](http://www.thegeekstuff.com/2012/02/virtualbox-install-create-vm/) seems pretty decent, or you follow the [Oracale Virtualbox User Manual](http://www.virtualbox.org/manual/UserManual.html). There's also specific documentation for [Debian](https://wiki.debian.org/VirtualBox) and for [Ubuntu](https://help.ubuntu.com/community/VirtualBox). If you succeeded, try again if you now can start vagrant nodes using plain vagrant (see first step). -* If plain vagrant works for you, you're very close to using vagrant with leap ! If you encounter any problems now, please [contact us](https://leap.se/en/about-us/contact) or use our [issue tracker](https://leap.se/code) - -Known working combinations --------------------------- - -Please consider that using other combinations might work for you as well, these are just the combinations we tried and worked for us: - - -Debian Wheezy -------------- - -* `virtualbox-4.2 4.2.16-86992~Debian~wheezy` from Oracle and `vagrant 1.2.2` from vagrantup.com - - -Ubuntu Raring 13.04 -------------------- - -* `virtualbox 4.2.10-dfsg-0ubuntu2.1` from Ubuntu raring and `vagrant 1.2.2` from vagrantup.com - -Mac OS X 10.9 -------------- - -* `VirtualBox 4.3.10` from virtualbox.org and `vagrant 1.5.4` from vagrantup.com - - -Using Vagrant with libvirt/kvm -============================== - -Vagrant can be used with different providers/backends, one of them is [vagrant-libvirt](https://github.com/pradels/vagrant-libvirt). Here are the steps how to use it. Be sure to use a recent vagrant version for the vagrant-libvirt plugin (>= 1.5, which can only be fetched from http://www.vagrantup.com/downloads.html at this moment). - -Install vagrant-libvirt plugin and add box ------------------------------------------- - sudo apt-get install libvirt-bin libvirt-dev - # you need to assign the new 'libvirtd' group to your user in a running x session, or logout and login again: - newgrp libvirtd - # to build the vagrant-libvirt plugin you need the following packages: - sudo apt-get install ruby-dev libxslt-dev libxml2-dev libvirt-dev - vagrant plugin install vagrant-libvirt - vagrant plugin install sahara - vagrant box add leap-wheezy https://downloads.leap.se/platform/vagrant/libvirt/leap-wheezy.box --provider libvirt - -Remove Virtualbox ------------------ - sudo apt-get remove virtualbox* - -Debugging ---------- - -If you get an error in any of the above commands, try to get some debugging information, it will often tell you what is wrong. In order to get debugging logs, you simply need to re-run the command that produced the error but prepend the command with VAGRANT_LOG=info, for example: - VAGRANT_LOG=info vagrant box add leap-wheezy https://downloads.leap.se/platform/vagrant/libvirt/leap-wheezy.box - -Start it --------- - -Use this example Vagrantfile: - - Vagrant.configure("2") do |config| - config.vm.define :testvm do |testvm| - testvm.vm.box = "leap-wheezy" - testvm.vm.network :private_network, :ip => '10.6.6.201' - end - - config.vm.provider :libvirt do |libvirt| - libvirt.connect_via_ssh = false - end - end - -Then: - - vagrant up --provider=libvirt - -If everything works, you should export libvirt as the VAGRANT_DEFAULT_PROVIDER: - - export VAGRANT_DEFAULT_PROVIDER="libvirt" - -Now you should be able to use the `leap local` commands. - -Known Issues ------------- - -* 'Call to virConnectOpen failed: internal error: Unable to locate libvirtd daemon in /usr/sbin (to override, set $LIBVIRTD_PATH to the name of the libvirtd binary)' - you don't have the libvirtd daemon running or installed, be sure you installed the 'libvirt-bin' package and it is running -* 'Call to virConnectOpen failed: Failed to connect socket to '/var/run/libvirt/libvirt-sock': Permission denied' - you need to be in the libvirt group to access the socket, do 'sudo adduser <user> libvirt' and then re-login to your session -* if each call to vagrant ends up with a segfault, it may be because you still have virtualbox around. if so, remove virtualbox to keep only libvirt + KVM. according to https://github.com/pradels/vagrant-libvirt/issues/75 having two virtualization engines installed simultaneously can lead to such weird issues. -* see the [vagrant-libvirt issue list on github](https://github.com/pradels/vagrant-libvirt/issues) -* be sure to use vagrant-libvirt >= 0.0.11 and sahara >= 0.0.16 (which are the latest stable gems you would get with `vagrant plugin install [vagrant-libvirt|sahara]`) for proper libvirt support -* for shared folder support, you need nfs-kernel-server installed on the host machine and set up sudo to allow unpriviledged users to modify /etc/exports. See [vagrant-libvirt#synced-folders](https://github.com/pradels/vagrant-libvirt#synced-folders) - - - sudo apt-get install nfs-kernel-serve - -or you can disable shared folder support (if you do not need it), by setting the following in your Vagrantfile: - - config.vm.synced_folder "src/", "/srv/website", disabled: trueconfig.vm.synced_folder "src/", "/srv/website", disabled: true diff --git a/doc/details/faq.md b/doc/details/faq.md index 57afb6c4..7ee20f4d 100644 --- a/doc/details/faq.md +++ b/doc/details/faq.md @@ -17,7 +17,13 @@ Puppet Where do i find the time a server was last deployed ? ----------------------------------------------------- -The puppet state file on the node indicates the last puppetrun: +Run: + + leap history FILTER + +This will tail the log file `/var/log/leap/deploy-summary.log`. + +If that command fails, you can manually check the puppet state file on the node indicates the last puppetrun: ls -la /var/lib/puppet/state/state.yaml diff --git a/doc/details/ports.md b/doc/details/ports.md new file mode 100644 index 00000000..f7c485ca --- /dev/null +++ b/doc/details/ports.md @@ -0,0 +1,92 @@ +@title = "Ports" +@summary = "The required open ports for different services." +@toc = true + +There are many different ports that must be open in order for the LEAP platform to work. Some ports must be *publicly open*, meaning that these should be accessible from the public internet. Other ports are *privately open*, meaning that they must be accessible to sysadmins or to the other nodes in the provider's infrastructure. + +Every node already includes a host-based firewall. However, if your network has its own firewall, you need to make sure that these ports are not blocked. + +Publicly open ports +-------------------------------- + +<table class="table table-striped"> +<tr> + <th>Name</th> + <th>Node Type</th> + <th>Default</th> + <th>Notes</th> +</tr> +<tr> + <td>SMTP</td> + <td>mx</td> + <td>25</td> + <td>This is required for all server-to-server SMTP email relay. This is not configurable.</td> +</tr> +<tr> + <td>HTTP</td> + <td>webapp</td> + <td>80</td> + <td>Although no actual services are available over port 80, it should be unblocked so that the web app can redirect to port 443. This is not configurable.</td> +</tr> +<tr> + <td>HTTPS</td> + <td>webapp</td> + <td>443</td> + <td>The web application is available over this port. This is not configurable.</td> +</tr> +<tr> + <td>SMTPS</td> + <td>mx</td> + <td>465</td> + <td>The client uses this port to submit outgoing email messages via SMTP over TLS. There is no easy way to change this, although you can create a custom <code>files/service-definitions/v1/smtp-service.json.erb</code> to do so. This will be changed to port 443 in the future.</td> +</tr> +<tr> + <td>Soledad</td> + <td>soledad</td> + <td>2323</td> + <td>The client uses this port to synchronize its storage data. This can be changed via the configuration property <code>soledad.port</code>. This will be changed to port 443 in the future.</td> +</tr> +<tr> + <td>Nicknym</td> + <td>webapp</td> + <td>6425</td> + <td>The client uses this port for discovering public keys. This can be changed via the configuration property <code>nickserver.port</code>. This will be changed to port 443 in the future.</td> +</tr> +<tr> + <td>OpenVPN</td> + <td>openvpn</td> + <td>80, 443, 53, 1194</td> + <td>By default, OpenVPN gateways will listen on all those ports. This can be changed via the configuration property <code>openvpn.ports</code>. Note that these ports must be open for <code>openvpn.gateway_address</code>, not for <code>ip_address</code>.</td> +</tr> +<tr> + <td>API</td> + <td>webapp</td> + <td>4430</td> + <td>Currently, the provider API is accessible via this port. In the future, the default will be changed to 443. For now, this can be changed via the configuration property <code>api.port</code>.</td> +</tr> +</table> + +Privately open ports +--------------------------------------- + +<table class="table table-striped"> +<tr> + <th>Name</th> + <th>Node Type</th> + <th>Default</th> + <th>Notes</th> +</tr> +<tr> + <td>SSH</td> + <td>all</td> + <td>22</td> + <td>This is the port that the sshd is bound to for the node. You can modify this using the configuration property <code>ssh.port</code>. It is important that this port is never blocked, or you will lose access to deploy to this node.</td> +</tr> +<tr> + <td>Stunnel</td> + <td>all</td> + <td>10000-20000</td> + <td>This is the range of ports that might be used for the encrypted stunnel connections between two nodes. These port numbers are automatically generated, but will fall somewhere in the specified range.</td> +</tr> +</table> + diff --git a/doc/details/webapp.md b/doc/details/webapp.md deleted file mode 100644 index 2b078af4..00000000 --- a/doc/details/webapp.md +++ /dev/null @@ -1,282 +0,0 @@ -@title = 'LEAP Web' -@summary = 'The web component of the LEAP Platform, providing user management, support desk, documentation and more.' -@toc = true - -Introduction -=================== - -"LEAP Web" is the webapp component of the LEAP Platform, providing the following services: - -* REST API for user registration. -* Admin interface to manage users. -* Client certificate distribution and renewal. -* User support help tickets. -* Billing -* Customizable and Localized user documentation - -This web application is written in Ruby on Rails 3, using CouchDB as the backend data store. - -It 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. - -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 - 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. - -Integration -=========== - -LEAP web is part of the leap platform. Most of the time it will be customized and deployed in that context. This section describes the integration of LEAP web in the wider framework. The Development section focusses on development of LEAP web itself. - -Configuration & Customization ------------------------------- - -The customization of the webapp for a leap provider happens via two means: - * configuration settings in services/webapp.json - * custom files in files/webapp - -### Configuration Settings - -The webapp ships with a fairly large set of default settings for all environments. They are stored in config/defaults.yml. During deploy the platform creates config/config.yml from the settings in services/webapp.json. These settings will overwrite the defaults. - -### Custom Files - -Any file placed in files/webapp in the providers repository will overwrite the content of config/customization in the webapp. These files will override files of the same name. - -This mechanism allows customizing basically all aspects of the webapp. -See files/webapp/README.md in the providers repository for more. - -### Provider Information ### - -The leap client fetches provider information via json files from the server. The platform prepares that information and stores it in the webapp in public/1/config/*.json. (1 being the current API version). - -Provider Documentation -------------- - -LEAP web already comes with a bit of user documentation. It mostly resides in app/views/pages and thus can be overwritten by adding files to files/webapp/views/pages in the provider repository. You probably want to add your own Terms of Services and Privacy Policy here. -The webapp will render haml, erb and markdown templates and pick translated content from localized files such as privacy_policy.es.md. In order to add or remove languages you have to modify the available_locales setting in the config. (See Configuration Settings above) - -Development -=========== - -Installation ---------------------------- - -Typically, this application is installed automatically as part of the LEAP Platform. To install it manually for testing or development, follow these instructions: - -### TL;DR ### - -Install git, ruby 1.9, rubygems and couchdb on your system. Then run - - gem install bundler - git clone https://leap.se/git/leap_web - cd leap_web - git submodule update --init - bundle install --binstubs - bin/rails server - -### Install system requirements - -First of all you need to install ruby, git and couchdb. On debian based systems this would be achieved by something like - - sudo apt-get install git ruby1.9.3 rubygems couchdb - -We install most gems we depend upon through [bundler](http://gembundler.com). So first install bundler - - 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``. - -### Download source - -Simply clone the git repository: - - git clone git://leap.se/leap_web - cd leap_web - -### SRP Submodule - -We currently use a git submodule to include srp-js. This will soon be replaced by a ruby gem. but for now you need to run - - git submodule update --init - -### Install required ruby libraries - - cd leap_web - bundle - -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`. - -There are a few values you should make sure to modify: - - production: - admins: ["myusername","otherusername"] - domain: example.net - force_ssl: true - secret_token: "4be2f60fafaf615bd4a13b96bfccf2c2c905898dad34..." - client_ca_key: "/etc/ssl/ca.key" - client_ca_cert: "/etc/ssl/ca.crt" - ca_key_password: nil - -* `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. -* `ca_key_password`, used to unlock the client_ca_key, if needed. - -### Provider Settings - -The leap client fetches provider information via json files from the server. -If you want to use that functionality please add your provider files the public/1/config directory. (1 being the current API version). - -Running ------------------------------ - - cd leap_web - bin/rails server - -You will find Leap Web running on `localhost:3000` - -Testing --------------------------------- - -To run all tests - - rake test - -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 - -Engines ---------------------- - -Leap Web includes some Engines. All things in `app` will overwrite the engine behaviour. You can clone the leap web repository and add your customizations to the `app` directory. Including leap_web as a gem is currently not supported. It should not require too much work though and we would be happy to include the changes required. - -If you have no use for one of the engines you can remove it from the Gemfile. Engines should really be plugins - no other engines should depend upon them. If you need functionality in different engines it should probably go into the toplevel. - -# Deployment # - -We strongly recommend using the LEAP platform for deploy. Most of the things documented here are automated as part of the platform. If you want to research how the platform deploys or work on your own mechanism this section is for you. - -These instructions are targeting a Debian GNU/Linux system. You might need to change the commands to match your own needs. - -## Server Preperation ## - -### Dependencies ## - -The following packages need to be installed: - -* git -* ruby1.9 -* rubygems1.9 -* couchdb (if you want to use a local couch) - -### Setup Capistrano ### - -We use puppet to deploy. But we also ship an untested config/deploy.rb.example. Edit it to match your needs if you want to use capistrano. - -run `cap deploy:setup` to create the directory structure. - -run `cap deploy` to deploy to the server. - -## Customized Files ## - -Please make sure your deploy includes the following files: - -* public/1/config/*.json (see Provider Settings section) -* config/couchdb.yml - -## Couch Security ## - -We recommend against using an admin user for running the webapp. To avoid this couch design documents need to be created ahead of time and the auto update mechanism needs to be disabled. -Take a look at test/setup_couch.sh for an example of securing the couch. - -## Design Documents ## - -After securing the couch design documents need to be deployed with admin permissions. There are two ways of doing this: - * rake couchrest:migrate_with_proxies - * dump the documents as files with `rake couchrest:dump` and deploy them - to the couch by hand or with the platform. - -### CouchRest::Migrate ### - -The before_script block in .travis.yml illustrates how to do this: - - mv test/config/couchdb.yml.admin config/couchdb.yml # use admin privileges - bundle exec rake couchrest:migrate_with_proxies # run the migrations - bundle exec rake couchrest:migrate_with_proxies # looks like this needs to run twice - mv test/config/couchdb.yml.user config/couchdb.yml # drop admin privileges - -### Deploy design docs from CouchRest::Dump ### - -First of all we get the design docs as files: - - # put design docs in /tmp/design - bundle exec rake couchrest:dump - -Then we add them to files/design in the site_couchdb module in leap_platform so they get deployed with the couch. You could also upload them using curl or sth. similar. - -# Troubleshooting # - -Here are some less common issues you might run into when installing Leap Web. - -## Cannot find Bundler ## - -### Error Messages ### - -`bundle: command not found` - -### Solution ### - -Make sure bundler is installed. `gem list bundler` should list `bundler`. -You also need to be able to access the `bundler` executable in your PATH. - -## Outdated version of rubygems ## - -### Error Messages ### - -`bundler requires rubygems >= 1.3.6` - -### Solution ### - -`gem update --system` will install the latest rubygems - -## Missing development tools ## - -Some required gems will compile C extensions. They need a bunch of utils for this. - -### Error Messages ### - -`make: Command not found` - -### Solution ### - -Install the required tools. For linux the `build-essential` package provides most of them. For Mac OS you probably want the XCode Commandline tools. - -## Missing libraries and headers ## - -Some gem dependencies might not compile because they lack the needed c libraries. - -### Solution ### - -Install the libraries in question including their development files. - - |