cleanup docs

docs/CONTRIBUTING.md

@@ -1,9 +0,0 @@
-We welcome contributions!
-
-### Guidelines
-
- * Small and focused PRs. Please don't include changes that don't address the subject of your PR.
- * Follow the style of importing functions directly e.g. `from os.path import abspath`.
- * Check out the [core values of Piku](../README.md#core-values).
- * PEP8.
-

docs/FAQ.md

@@ -2,23 +2,21 @@
 
 **Q:** Why `piku`?
 
-**A:** Partly because it's supposed to run on a [Pi][pi], because it's Japanese onomatopeia for 'twitch' or 'jolt', and because I know the name will annoy some of my friends.
+**A:** Partly because it's started out on the [Raspberry Pi][pi], because it's Japanese onomatopeia for 'twitch' or 'jolt', and because we knew the name would be cute and amusing.
 
 **Q:** Why Python/why not Go?
 
-**A:** I actually thought about doing this in Go right off the bat, but [click][click] is so cool and I needed to have [uWSGI][uwsgi] running anyway, so I caved in. But I'm very likely to take something like [suture](https://github.com/thejerf/suture) and port this across, doing away with [uWSGI][uwsgi] altogether.
+**A:** We actually thought about doing this in Go right off the bat, but [click][click] is so cool and we needed to have `uwsgi` running anyway, so we caved in. But possible future directions are likely to take something like [suture](https://github.com/thejerf/suture) and port this across (or just use [Caddy](http://caddyserver.com)), doing away with `uwsgi` altogether.
 
-Go also (at the time) did not have a way to vendor dependencies that I was comfortable with, and that is also why Go support fell behind. Hopefully that will change soon.
+Go also (at the time) did not have a way to vendor dependencies that we were comfortable with, and that is also why Go support fell behind. Hopefully that will change soon.
 
 **Q:** Does it run under Python 3?
 
-**A:** Right now, it _only_ runs on Python 3, even though it can deploy apps written in both major versions. It began its development using 2.7 and using`click` for abstracting the simpler stuff, and I eventually switched over to 3.5 once it was supported in Debian Stretch and Raspbian since I wanted to make installing it on the Raspberry Pi as simple as possible.
+**A:** Right now, it _only_ runs on Python 3, even though it can deploy apps written in both major versions. It began its development using 2.7 and using`click` for abstracting the simpler stuff, and we eventually switched over to 3.5 once it was supported in Debian Stretch and Raspbian since we wanted to make installing it on the Raspberry Pi as simple as possible.
 
 **Q:** Why not just use `dokku`?
 
-**A:** I used `dokku` daily for most of my personal stuff for a good while. But it relied on a number of `x64` containers that needed to be completely rebuilt for ARM, and when I decided I needed something like this (March 2016) that was barely possible - `docker` itself was not fully baked for ARM yet, and people were at the time trying to get `herokuish` and `buildstep` to build on ARM.
-
-
+**A:** We used `dokku` daily for many projects. But it relied on a number of `x64` containers that needed to be completely rebuilt for `ARM`, and when we decided we needed something like this (March 2016) that was barely possible - `docker` itself was not fully baked for `ARM` yet, and people were at the time just starting to get `herokuish` and `buildstep` to build on `ARM`.
 
 [click]: http://click.pocoo.org
 [pi]: http://www.raspberrypi.org

docs/INSTALL.md

@@ -1,18 +1,33 @@
 # Installation
 
-`piku` requires `Python 3`, [uWSGI][uwsgi], SSH, and a Linux distribution that runs `systemd`, such as Raspbian Jessie/Debian 8+/Ubuntu/Fedora/CentOS.
+## TL;DR:
 
-There are 3 ways to install piku on a server:
+To install it on your server, `ssh` in as `root` and run this:
 
-1. Manually: Follow INSTALL-x.md for which ever platform. If you are running `piku` on specific Linux versions, feel free to contribute your own instructions.
+```bash
+curl https://piku.github.io/get | sh
+```
 
-2. Use cloud-init to do it automatically at VPS build time: https://github.com/piku/cloud-init
+## Installation Methods
 
-3. Use piku-bootstrap to do it once your box is already provisioned: https://github.com/piku/piku-bootstrap
+`piku` requires `Python 3`, [uWSGI][uwsgi], `ssh`, and a Linux distribution that runs `systemd`, such as Raspbian Jessie/Debian 8+/Ubuntu/Fedora/CentOS.
 
-# Generic steps (referenced from INSTALL-x)
+There are 3 main ways to install `piku` on a server:
 
-## Set up the `piku` user
+1. Use [piku-bootstrap](https://github.com/piku/piku-bootstrap) to do it if your server is already provisioned (that is what the TL;DR command does)
+
+2. Use `cloud-init` to do it automatically at VPS build time (see the [`cloud-init`](https://github.com/piku/cloud-init) repository, which has examples for most common cloud providers)
+
+3. Manually: Follow the guide below or one of the platform-specfic guides. 
+
+There is also an [Ansible playbook](https://github.com/piku/ansible-setup).
+
+!!! Contributing
+    If you are running `piku` on specific Linux versions, feel free to contribute your own instructions.
+
+## Generic Installation Steps
+
+### Set up the `piku` user
 
 `piku` requires a separate user account to run. To create a new user with the right group membership (we're using the built-in `www-data` group because it's generally thought of as a less-privileged group), enter the following command:
 
@@ -38,10 +53,9 @@ Creating '/home/piku/.piku/logs'.
 Setting '/home/piku/piku.py' as executable.
 ```
 
+### Set up `ssh` access
 
-## Set up SSH access
-
-If you don't have an SSH public key (or never used one before), you need to create one. The following instructions assume you're running some form of UNIX on your own machine (Windows users should check the documentation for their SSH client, unless you have [Cygwin][cygwin] installed).
+If you don't have an `ssh` public key (or never used one before), you need to create one. The following instructions assume you're running some form of UNIX on your own machine (Windows users should check the documentation for their `ssh` client, unless you have [Cygwin][cygwin] installed).
 
 **On your own machine**, issue the `ssh-keygen` command and follow the prompts:
 
@@ -81,9 +95,9 @@ cat .ssh/authorized_keys
 command="FINGERPRINT=85:29:07:cb:de:ad:be:ef:42:65:00:c8:d2:6b:9e:ff NAME=default /home/piku/piku.py $SSH_ORIGINAL_COMMAND",no-agent-forwarding,no-user-rc,no-X11-forwarding,no-port-forwarding ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDhTYZi/qeJBKgU3naI8FNjQgeMYnMsEtqrOmUc4lJoPNH2qBUTNkzwThGqsBm2HNLPURWMiEifBqF+kRixMud67Co7Zs9ys7pwFXkJB9bbZasd2JCGfVZ4UYXHnvgejSWkLAV/4bObhsbP2vWOmbbm91Cwn+PGJgoiW08yrd45lsDmgv9cUAJS3e8LkgVELvIDg49yM5ArB88oxwMEoUgWU2OniHmH0o1zw5I8WXHRhHOjb8cGsdTYfXEizRKKRTM2Mu6dKRt1GNL0UbWi8iS3uJHGD3AcQ4ApdMl5X0gTixKHponStOrSMy19/ltuIy8Sjr7KKPxz07ikMYr7Vpcp youruser@yourlaptop.lan
 ```
 
-This line is what enables you to SSH (and perform `git` over SSH operations) to the `piku` user without a password, verifying your identity via your public key, restricting what can be done remotely and passing on to `piku` itself the commands you'll be issuing.
+This line is what enables you to `ssh` (and perform `git` over `ssh` operations) to the `piku` user without a password, verifying your identity via your public key, restricting what can be done remotely and passing on to `piku` itself the commands you'll be issuing.
 
-## Test
+### Test
 
 From your machine, do:
 
@@ -116,7 +130,5 @@ Commands:
 Connection to pi.lan closed.
 ```
 
-
 [uwsgi]: https://github.com/unbit/uwsgi
-[cygwin]: http://www.cygwin.com
-
+[cygwin]: http://www.cygwin.com

docs/README.md

@@ -0,0 +1,3 @@
+# Documentation
+
+There is now a [documentation site](https://piku.github.io) available, which is built from the `piku.github.io` repository. This directory holds only a small subset of the documentation.

docs/old/INSTALL.md

@@ -0,0 +1,134 @@
+# Installation
+
+## TL;DR:
+
+To install it on your server, `ssh` in as `root` and run this:
+
+```bash
+curl https://piku.github.io/get | sh
+```
+
+## Installation Methods
+
+`piku` requires `Python 3`, [uWSGI][uwsgi], `ssh`, and a Linux distribution that runs `systemd`, such as Raspbian Jessie/Debian 8+/Ubuntu/Fedora/CentOS.
+
+There are 3 main ways to install `piku` on a server:
+
+1. Use [piku-bootstrap](https://github.com/piku/piku-bootstrap) to do it if your server is already provisioned (that is what the TL;DR command does)
+
+2. Use `cloud-init` to do it automatically at VPS build time (see the [`cloud-init`](https://github.com/piku/cloud-init) repository, which has examples for most common cloud providers)
+
+3. Manually: Follow the guide below or one of the platform-specfic guides. 
+
+There is also an [Ansible playbook](https://github.com/piku/ansible-setup).
+
+!!! Contributing
+    If you are running `piku` on specific Linux versions, feel free to contribute your own instructions.
+
+## Generic Installation Steps
+
+### Set up the `piku` user
+
+`piku` requires a separate user account to run. To create a new user with the right group membership (we're using the built-in `www-data` group because it's generally thought of as a less-privileged group), enter the following command:
+
+```bash
+# pick a username
+export PAAS_USERNAME=piku
+# create it
+sudo adduser --disabled-password --gecos 'PaaS access' --ingroup www-data $PAAS_USERNAME
+# copy & setup piku.py
+sudo su - $PAAS_USERNAME -c "wget https://raw.githubusercontent.com/piku/piku/master/piku.py && python3 ~/piku.py setup"
+```
+
+The `setup` output should be something like this:
+
+```
+Creating '/home/piku/.piku/apps'.
+Creating '/home/piku/.piku/repos'.
+Creating '/home/piku/.piku/envs'.
+Creating '/home/piku/.piku/uwsgi'.
+Creating '/home/piku/.piku/uwsgi-available'.
+Creating '/home/piku/.piku/uwsgi-enabled'.
+Creating '/home/piku/.piku/logs'.
+Setting '/home/piku/piku.py' as executable.
+```
+
+### Set up `ssh` access
+
+If you don't have an `ssh` public key (or never used one before), you need to create one. The following instructions assume you're running some form of UNIX on your own machine (Windows users should check the documentation for their `ssh` client, unless you have [Cygwin][cygwin] installed).
+
+**On your own machine**, issue the `ssh-keygen` command and follow the prompts:
+
+```bash
+ssh-keygen 
+
+Generating public/private rsa key pair.
+Enter file in which to save the key (/home/youruser/.ssh/id_rsa): 
+Created directory '/home/youruser/.ssh'.
+Enter passphrase (empty for no passphrase): 
+Enter same passphrase again: 
+Your identification has been saved in /home/youruser/.ssh/id_rsa.
+Your public key has been saved in /home/youruser/.ssh/id_rsa.pub.
+The key fingerprint is:
+85:29:07:cb:de:ad:be:ef:42:65:00:c8:d2:6b:9e:ff youruser@yourlaptop.lan
+The key's randomart image is:
++--[ RSA 2048]----+
+<...>
++-----------------+
+```
+
+Copy the resulting `id_rsa.pub` (or equivalent, just make sure it's the _public_ file) to your `piku` server and do the following:
+
+```bash
+sudo su - piku
+python3 piku.py setup:ssh /tmp/id_rsa.pub
+
+Adding key '85:29:07:cb:de:ad:be:ef:42:65:00:c8:d2:6b:9e:ff'.
+```
+
+Now if you look at `.ssh/authorized_keys`, you should see something like this:
+
+```bash
+sudo su - piku
+cat .ssh/authorized_keys
+ 
+command="FINGERPRINT=85:29:07:cb:de:ad:be:ef:42:65:00:c8:d2:6b:9e:ff NAME=default /home/piku/piku.py $SSH_ORIGINAL_COMMAND",no-agent-forwarding,no-user-rc,no-X11-forwarding,no-port-forwarding ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDhTYZi/qeJBKgU3naI8FNjQgeMYnMsEtqrOmUc4lJoPNH2qBUTNkzwThGqsBm2HNLPURWMiEifBqF+kRixMud67Co7Zs9ys7pwFXkJB9bbZasd2JCGfVZ4UYXHnvgejSWkLAV/4bObhsbP2vWOmbbm91Cwn+PGJgoiW08yrd45lsDmgv9cUAJS3e8LkgVELvIDg49yM5ArB88oxwMEoUgWU2OniHmH0o1zw5I8WXHRhHOjb8cGsdTYfXEizRKKRTM2Mu6dKRt1GNL0UbWi8iS3uJHGD3AcQ4ApdMl5X0gTixKHponStOrSMy19/ltuIy8Sjr7KKPxz07ikMYr7Vpcp youruser@yourlaptop.lan
+```
+
+This line is what enables you to `ssh` (and perform `git` over `ssh` operations) to the `piku` user without a password, verifying your identity via your public key, restricting what can be done remotely and passing on to `piku` itself the commands you'll be issuing.
+
+### Test
+
+From your machine, do:
+
+```bash
+ssh piku@pi.lan
+
+Usage: piku.py [OPTIONS] COMMAND [ARGS]...
+
+  The smallest PaaS you've ever seen
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  apps              List applications
+  config            Show application configuration
+  config:get        Retrieve a configuration setting
+  config:live       Show live configuration settings
+  config:set        Set a configuration setting
+  deploy            Deploy an application
+  destroy           Destroy an application
+  disable           Disable an application
+  enable            Enable an application
+  logs              Tail an application log
+  ps                Show application worker count
+  ps:scale          Show application configuration
+  restart           Restart an application
+  setup             Initialize paths
+  setup:ssh         Set up a new SSH key
+Connection to pi.lan closed.
+```
+
+[uwsgi]: https://github.com/unbit/uwsgi
+[cygwin]: http://www.cygwin.com