summaryrefslogtreecommitdiff
path: root/doc/details
diff options
context:
space:
mode:
authorelijah <elijah@riseup.net>2016-08-29 22:55:41 -0700
committerelijah <elijah@riseup.net>2016-08-29 22:55:41 -0700
commit0a09a6e6f247729457d15480f8d2b9bb0b89ae5e (patch)
treeaec1e88cb9d8a4942068fb46333d5719ed5af79f /doc/details
parent568688b5a7d17de26a275a2f6dde8bbd3054cdc6 (diff)
Updated (very out of date) docs and README.md
Diffstat (limited to 'doc/details')
-rw-r--r--doc/details/development.md78
-rw-r--r--doc/details/en.haml4
-rw-r--r--doc/details/faq.md71
-rw-r--r--doc/details/ports.md92
-rw-r--r--doc/details/under-the-hood.md40
5 files changed, 0 insertions, 285 deletions
diff --git a/doc/details/development.md b/doc/details/development.md
deleted file mode 100644
index 78915add..00000000
--- a/doc/details/development.md
+++ /dev/null
@@ -1,78 +0,0 @@
-@title = 'Development'
-@summary = "Getting started with making changes to the LEAP platform"
-
-Installing leap_cli
-------------------------------------------------
-
-### From gem, for a single user
-
-Install the latest:
-
- gem install leap_cli --install-dir ~/leap
- export PATH=$PATH:~/leap/bin
-
-Install a particular version:
-
- gem install leap_cli --version 1.8 --install-dir ~/leap
- export PATH=$PATH:~/leap/bin
-
-### From gem, system wide
-
-Install the latest:
-
- sudo gem install leap_cli
-
-Install a particular version:
-
- sudo gem install leap_cli --version 1.8
-
-### As a gem, built from source
-
- 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
-
- sudo apt-get install ruby ruby-dev rake
- git clone https://leap.se/git/leap_cli.git
- cd leap_cli
- git checkout develop
-
-Then do one of the following to be able to run `leap` command:
-
- cd leap_cli
- export PATH=$PATH:`pwd`/bin
- alias leap="`pwd`/bin/leap"
- ln -s `pwd`/bin/leap ~/bin/leap
-
-In practice, of course, you would put aliases or PATH modifications in a shell startup file.
-
-You can also clone from https://github.com/leap/leap_cli
-
-Running different leap_cli versions
----------------------------------------------
-
-### If installed as a gem
-
-With rubygems, you can always specify the gem version as the first argument to any executable installed by rubygems. For example:
-
- 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
-
-### If running from source
-
-Alternately, if you are running from source, you can alias different commands:
-
- git clone https://leap.se/git/leap_cli.git
- cd leap_cli
- git checkout develop
- alias leap_develop="`pwd`/bin/leap`
-
diff --git a/doc/details/en.haml b/doc/details/en.haml
deleted file mode 100644
index fe7a4c84..00000000
--- a/doc/details/en.haml
+++ /dev/null
@@ -1,4 +0,0 @@
-- @nav_title = "Details"
-- @title = 'Platform Details'
-
-= child_summaries \ No newline at end of file
diff --git a/doc/details/faq.md b/doc/details/faq.md
deleted file mode 100644
index 7ee20f4d..00000000
--- a/doc/details/faq.md
+++ /dev/null
@@ -1,71 +0,0 @@
-@title = 'Frequently asked questions'
-@nav_title = 'FAQ'
-@summary = "Frequently Asked Questions"
-@toc = true
-
-APT
-===============
-
-What do I do when unattended upgrades fail?
---------------------------------------------------
-
-When you receive notification e-mails with a subject of 'unattended-upgrades result for $machinename', that means that some package couldn't be automatically upgraded and needs manual interaction. The reasons vary, so you have to be careful. Most often you can simply login to the affected machine and run `apt-get dist-upgrade`.
-
-Puppet
-======
-
-Where do i find the time a server was last deployed ?
------------------------------------------------------
-
-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
-
-What resources are touched by puppet/leap_platform (services/packages/files etc.) ?
------------------------------------------------------------------------------------
-
-Log into your server and issue:
-
- grep -v '!ruby/sym' /var/lib/puppet/state/state.yaml | sed 's/\"//' | sort
-
-
-How can i customize the leap_platform puppet manifests ?
---------------------------------------------------------
-
-You can create custom puppet modules under `files/puppet`.
-The custom puppet entry point is in class 'custom' which can be put into
-`files/puppet/modules/custom/manifests/init.pp`. This class gets automatically included
-by site_config::default, which is applied to all nodes.
-
-Of cause you can also create a different git branch and change whatever you want, if you are
-familiar wit git.
-
-Facter
-======
-
-How can i see custom facts distributed by leap_platform on a node ?
--------------------------------------------------------------------
-
-On the server, export the FACTERLIB env. variable to include the path of the custom fact in question:
-
- export FACTERLIB=/var/lib/puppet/lib/facter:/srv/leap/puppet/modules/stdlib/lib/facter/
- facter
-
-
-Etc
-===
-
-How do i change the domain of my provider ?
--------------------------------------------
-
-* First of all, you need to have access to the nameserver config of your new domain.
-* Update domain in provider.json
-* remove all ca and cert files: `rm files/cert/* files/ca/*`
-* create ca, csr and certs : `leap cert ca; leap cert csr; leap cert dh; leap cert update`
-* deploy
diff --git a/doc/details/ports.md b/doc/details/ports.md
deleted file mode 100644
index f7c485ca..00000000
--- a/doc/details/ports.md
+++ /dev/null
@@ -1,92 +0,0 @@
-@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/under-the-hood.md b/doc/details/under-the-hood.md
deleted file mode 100644
index 0bc4fe77..00000000
--- a/doc/details/under-the-hood.md
+++ /dev/null
@@ -1,40 +0,0 @@
-@title = "Under the hood"
-@summary = "Various implementation details."
-
-This page contains various details on the how the platform is implemented. You can safely ignore this page, although it may be useful if you plan to make modifications to the platform.
-
-Puppet Details
-======================================
-
-Tags
-----
-
-Tags are beeing used to deploy different classes.
-
-* leap_base: site_config::default (configure hostname + resolver, sshd, )
-* leap_slow: site_config::slow (slow: apt-get update, apt-get dist-upgrade)
-* leap_service: cofigure platform service (openvpn, couchdb, etc.)
-
-You can pass any combination of tags, i.e. use
-
-* "--tags leap_base,leap_slow,leap_service" (DEFAULT): Deploy all
-* "--tags leap_service": Only deploy service(s) (useful for debugging/development)
-* "--tags leap_base": Only deploy basic configuration (again, useful for debugging/development)
-
-
-### Doing faster partial deploys
-
-If you only change a tiny bit on the platform puppet recipes, you could achieve a
-*much* faster deploy specifying the resource tag you changed.
-i.e. you changed the way rsyslog config snippets for LEAP logfiles are created
-in `puppet/modules/leap/manifests/logfile.pp`. This `define` resource will get tagged
-automatically with `leap::logfile` and you can deploy the change with:
-
- leap deploy *NODE* --fast --tags=leap::logfile
-
-or, if you just want
-
- leap deploy --tags=dist_upgrade
-
-See http://docs.puppetlabs.com/puppet/2.7/reference/lang_tags.html for puppet tag usage.
-