From f5dbbbeedc87c0a3f65ea1e893cc3b8377f68ff5 Mon Sep 17 00:00:00 2001 From: Micah Anderson Date: Thu, 3 Apr 2014 12:57:29 -0400 Subject: clarify that you should not run any commands as a privileged user, unless it has 'sudo' indicated (#4473) --- docs/platform/development.md | 1 + docs/platform/quick-start.md | 1 + 2 files changed, 2 insertions(+) (limited to 'docs/platform') diff --git a/docs/platform/development.md b/docs/platform/development.md index 386b703..129404d 100644 --- a/docs/platform/development.md +++ b/docs/platform/development.md @@ -11,6 +11,7 @@ Requirements * Be 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. Install prerequisites -------------------------------- diff --git a/docs/platform/quick-start.md b/docs/platform/quick-start.md index 3171674..80a6c46 100644 --- a/docs/platform/quick-start.md +++ b/docs/platform/quick-start.md @@ -34,6 +34,7 @@ In order to complete this Quick Start, you will need a few things: * You need to be aware that this process will make changes to your systems, so please be sure that these machines are a basic install with nothing configured or running for other purposes * Your machines will need to be connected to the internet, and not behind a restrictive firewall. * You should work locally on your laptop/workstation (one that you trust and that is ideally full-disk encrypted) while going through this guide. This is important because the provider configurations you are creating contain sensitive data that should not reside on a remote machine. The leap cli utility will login to your servers and configure the services. +* 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. All the commands in this tutorial are run on your sysadmin machine. In order to complete the tutorial, the sysadmin will do the following: -- cgit v1.2.3 From e95229e1a27f16c3efc1252caf5708954ca139a1 Mon Sep 17 00:00:00 2001 From: guido Date: Wed, 23 Apr 2014 12:26:01 -0300 Subject: Mac OS X 10.9 Requeriments section --- docs/platform/development.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) (limited to 'docs/platform') diff --git a/docs/platform/development.md b/docs/platform/development.md index 129404d..1036b8d 100644 --- a/docs/platform/development.md +++ b/docs/platform/development.md @@ -34,12 +34,29 @@ Install Vagrant in order to be able to test with local virtual machines (typical sudo apt-get install vagrant virtualbox - +*Mac OS X 10.9 (Mavericks)* + +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 + + brew tap homebrew/dupes + +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. + + brew install openssh --with-brewed-openssl --with-keychain-support + +The certtool provided by Apple it's really old, install the one provided by GnuTLS and shadow the system's default. + + sudo brew install gnutls + ln -sf /usr/local/bin/gnutls-certtool /usr/local/bin/certool + +Install the Vagrant and VirtualBox packages for OS X from their respective Download pages. + +* http://www.vagrantup.com/downloads.html +* https://www.virtualbox.org/wiki/Downloads + + +2. Install Adding development nodes to your provider -- cgit v1.2.3 From fc340491965c6fcc2d5c6654a5e19ddc1b2fd639 Mon Sep 17 00:00:00 2001 From: guido Date: Wed, 23 Apr 2014 12:30:03 -0300 Subject: Added OX 10.9 to working combinations. --- docs/platform/development.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'docs/platform') diff --git a/docs/platform/development.md b/docs/platform/development.md index 1036b8d..ecbe022 100644 --- a/docs/platform/development.md +++ b/docs/platform/development.md @@ -236,6 +236,11 @@ 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 ============================== -- cgit v1.2.3 From 7d954d1720c85af8e531471c21beb486ec9a8dd7 Mon Sep 17 00:00:00 2001 From: guido Date: Wed, 23 Apr 2014 12:31:14 -0300 Subject: Fix typo? The node created was named web1. --- docs/platform/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/platform') diff --git a/docs/platform/development.md b/docs/platform/development.md index ecbe022..e433b6b 100644 --- a/docs/platform/development.md +++ b/docs/platform/development.md @@ -89,7 +89,7 @@ In order to test the node "web1" we need to start it. Starting a node for the fi 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 web + $ leap local start web1 = created test/ = created test/Vagrantfile = installing vagrant plugin 'sahara' -- cgit v1.2.3 From 7aba4766802ea13c063f546a51861d7ebf6533d5 Mon Sep 17 00:00:00 2001 From: elijah Date: Sun, 27 Apr 2014 15:39:46 -0700 Subject: added services <> node type table. --- docs/platform/guide.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 52 insertions(+), 4 deletions(-) (limited to 'docs/platform') diff --git a/docs/platform/guide.md b/docs/platform/guide.md index 99147a8..4b3086e 100644 --- a/docs/platform/guide.md +++ b/docs/platform/guide.md @@ -16,15 +16,15 @@ When adding a new node to your provider, you should ask yourself four questions: Brief overview of the services: * **webapp**: The web application. Runs both webapp control panel for users and admins as well as the REST API that the client uses. Needs to communicate heavily with `couchdb` nodes. You need at least one, good to have two for redundancy. The webapp does not get a lot of traffic, so you will not need many. -* **couchdb**: The database for users and user data. You can get away with just one, but for proper redundancy you should have at least three. Communicates heavily with `webapp` and `mx` nodes. -* **soledad**: Handles the data syncing with clients. Typically combined with `couchdb` service, since it communicates heavily with couchdb. (not currently in stable release) -* **mx**: Incoming and outgoing MX servers. Communicates with the public internet, clients, and `couchdb` nodes. (not currently in stable release) +* **couchdb**: The database for users and user data. You can get away with just one, but for proper redundancy you should have at least three. Communicates heavily with `webapp`, `mx`, and `soledad` nodes. +* **soledad**: Handles the data syncing with clients. Typically combined with `couchdb` service, since it communicates heavily with couchdb. +* **mx**: Incoming and outgoing MX servers. Communicates with the public internet, clients, and `couchdb` nodes. * **openvpn**: OpenVPN gateway for clients. You need at least one, but want as many as needed to support the bandwidth your users are doing. The `openvpn` nodes are autonomous and don't need to communicate with any other nodes. Often combined with `tor` service. * **monitor**: Internal service to monitor all the other nodes. Currently, you can have zero or one `monitor` nodes. * **tor**: Sets up a tor exit node, unconnected to any other service. * **dns**: Not yet implemented. -webapp +Webapp ----------------------------------- The webapp node is responsible for both the user face web application and the API that the client interacts with. @@ -45,6 +45,54 @@ And then redeploy to all webapp nodes: By putting this in `services/webapp.json`, you will ensure that all webapp nodes inherit the value for `webapp.admins`. +Services +================================ + +What nodes do you need for a provider that offers particular services? + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Node TypeVPN ServiceEmail Service
webapprequiredrequired
couchdbrequiredrequired
soledadnot usedrequired
mxnot usedrequired
openvpnrequirednot used
monitoroptionaloptional
toroptionaloptional
+ Locations ================================ -- cgit v1.2.3 From c48f250df89b961c7a962be0a4dfeac1b42d37f7 Mon Sep 17 00:00:00 2001 From: guido Date: Mon, 5 May 2014 12:26:03 -0400 Subject: Updated docs to reflect issues of bug #5601 The docs reflect the problem when adding new couchdb nodes after one o more have been deployed. --- docs/platform/known-issues.md | 7 +++++++ docs/platform/quick-start.md | 4 ++-- 2 files changed, 9 insertions(+), 2 deletions(-) (limited to 'docs/platform') diff --git a/docs/platform/known-issues.md b/docs/platform/known-issues.md index 46a77de..5bf41a6 100644 --- a/docs/platform/known-issues.md +++ b/docs/platform/known-issues.md @@ -5,6 +5,13 @@ Here you can find documentation about known issues and potential work-arounds in the current Leap Platform release. +0.5.1 +===== +CouchDB Sync +------------ +You can't deploy new couchdb nodes after one or more have been deployed. Make *sure* that you configure and deploy all your couchdb nodes when starting the provider. The problem is that we dont not have a clean way of adding couch nodes after initial creation of the databases, so any nodes added after result in improperly synchronized data. See Bug [#5601](https://leap.se/code/issues/5601) for more information. + + 0.5.0rc1 ======== diff --git a/docs/platform/quick-start.md b/docs/platform/quick-start.md index 80a6c46..e70dca5 100644 --- a/docs/platform/quick-start.md +++ b/docs/platform/quick-start.md @@ -273,8 +273,8 @@ If you prefer, you can initalize each node, one at a time: Deploy the LEAP platform to the nodes -------------------- -Now you should deploy the platform recipes to the nodes. Deployment can take a while to run, especially on the first run, as it needs to update the packages on the new machine. -Note that currently, nodes must be deployed in a certain order. The underlying couch database node(s) must be deployed first, and then all other nodes. +Now you should deploy the platform recipes to the nodes. [Deployment can take a while to run](http://xkcd.com/303/), especially on the first run, as it needs to update the packages on the new machine. +*Important notes:* currently nodes must be deployed in a certain order. The underlying couch database node(s) must be deployed first, and then all other nodes. Also you need to configure and deploy all of the couchdb nodes that you plan to use at this time, as currently you cannot add more of them later later ([See](https://leap.se/es/docs/platform/known-issues#CouchDB.Sync)). $ leap deploy couch1 -- cgit v1.2.3 From 77a278fa2df2fecb46f0c723cb1f1078c6cfcb7f Mon Sep 17 00:00:00 2001 From: Micah Anderson Date: Thu, 8 May 2014 14:22:16 -0400 Subject: add some additional information about resource requirements (#5088) --- docs/platform/quick-start.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/platform') diff --git a/docs/platform/quick-start.md b/docs/platform/quick-start.md index e70dca5..9bebe3e 100644 --- a/docs/platform/quick-start.md +++ b/docs/platform/quick-start.md @@ -10,7 +10,7 @@ If you are curious how this will look like without trying it out yourself, you c Our goal ------------------ -We are going to create a minimal LEAP provider offering OpenVPN service. This basic setup can be expanded by adding more OpenVPN nodes to increase capacity, or more webapp and couchdb nodes to increase availability (performance wise, a single couchdb and a single webapp are more than enough for most usage, since they are only lightly used, but you might want redundancy). +We are going to create a minimal LEAP provider offering OpenVPN service. This basic setup can be expanded by adding more OpenVPN nodes to increase capacity, or more webapp and couchdb nodes to increase availability (performance wise, a single couchdb and a single webapp are more than enough for most usage, since they are only lightly used, but you might want redundancy). Please note: currently it is not possible to safely add additional couchdb nodes at a later point. They should all be added in the beginning, so please consider carefully if you would like more before proceeding. Our goal is something like this: @@ -27,8 +27,8 @@ Requirements In order to complete this Quick Start, you will need a few things: -* You will need three real or paravirtualized virtual machines (KVM, Xen, Openstack, Amazon, but not Vagrant - sorry) that have a basic Debian Stable installed. If you allocate 10G to each node, that should be plenty. -* You should be able to SSH into them remotely, and know their IP addresses and their SSH host keys +* You will need three real or paravirtualized virtual machines (KVM, Xen, Openstack, Amazon, but not Vagrant - sorry) that have a basic Debian Stable installed. If you allocate 20G of disk space to each node for the system, after this process is completed, you will have used less than 10% of that disk space. If you allocate 2 CPUs and 8G of memory to each node, that should be more than enough to begin with. +* You should be able to SSH into them remotely, and know their root password, IP addresses and their SSH host keys * You will need four different IPs, one for each node, and a second one for the VPN gateway * The ability to create/modify DNS entries for your domain is preferable, but not needed. If you don't have access to DNS, you can workaround this by modifying your local resolver, i.e. editing `/etc/hosts`. * You need to be aware that this process will make changes to your systems, so please be sure that these machines are a basic install with nothing configured or running for other purposes -- cgit v1.2.3 From e04fa7799c7062477b163d49cfb4a83f318e5198 Mon Sep 17 00:00:00 2001 From: kwadronaut Date: Mon, 12 May 2014 18:37:17 +0200 Subject: update vagrant version: usually too old in distributions, get it from vagrantup --- docs/platform/development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/platform') diff --git a/docs/platform/development.md b/docs/platform/development.md index e433b6b..9c30859 100644 --- a/docs/platform/development.md +++ b/docs/platform/development.md @@ -30,7 +30,7 @@ Install core prerequisites: sudo apt-get install git ruby ruby-dev rsync openssh-client openssl rake make -Install Vagrant in order to be able to test with local virtual machines (typically optional, but required for this tutorial): +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) sudo apt-get install vagrant virtualbox -- cgit v1.2.3