Documentation

DESIGN.md

@@ -2,14 +2,33 @@
 
 The idea behind `piku` is that it provides the simplest possible way to deploy web apps or services. Simplicity comes at the expense of features, of course, and this document tries to capture the trade-offs.
 
-## uWSGI
+## Why uWSGI
 
 Using [uWSGI][uwsgi] in [emperor mode][emperor] gives us the following features for free:
 
-* Python WSGI integration
+* Painless Python WSGI and `virtualenv` integration
 * Process monitoring, restarting, basic resource limiting, etc.
 * Basic security scaffolding, beginning with the ability to define `uid´/`gid` on a per-app basis (if necessary)
 
+## Application packaging
+
+An app is simply a `git` repository with some additional files on the top level, the most important of which is the `Procfile`.
+
+### `Procfile` format
+
+_TODO: Describe how to detect a single binary or a WSGI entry point, standalone workers, etc._
+
+## Runtime detection
+
+`piku` follows a very simple set of rules to determine what kind of runtime is required:
+
+1. If there's a `requirements.txt` file at the top level, then the app is assumed to require Python.
+2. _TODO: Go_
+3. _TODO: Node_
+4. _TODO: Java_
+2. For all the rest, a `Procfile` is required to determine the application entry points. 
+
+
 ## Application isolation
 
 Application isolation can be tackled at several levels, the most relevant of which being:
@@ -19,7 +38,7 @@ Application isolation can be tackled at several levels, the most relevant of whi
 
 For 1.0, all applications run under the same `uid`, under separate branches of the same filesystem, and without any resource limiting.
 
-Ways to improve upon that (short of full containerisation) typically entail the use of a `chroot` environment (which is available under most POSIX systems in one form or another) or Linux kernel namespaces - both of which are supported by [uWSGI][uwsgi] (which can also handle resource limiting to a degree). 
+Ways to improve upon that (short of full containerisation) typically entail the use of a `chroot` jail environment (which is available under most POSIX systems in one form or another) or Linux kernel namespaces - both of which are supported by [uWSGI][uwsgi] (which can also handle resource limiting to a degree).
 
 As to runtime isolation, `piku` only provides `virtualenv` support until 1.0, and all Python apps will use the default interpreter (Go, Node and Java support will share these limitations in each major version).
 

INSTALL.md

@@ -0,0 +1,37 @@
+# Installation
+
+_TODO: describe the system requirements and installation process._
+
+## Setting up the `piku` user
+
+_TODO: describe the need for a separate user and why it's configured this way._
+
+If you're impatient, you need to make sure you have a `~/.ssh/authorized_keys` file that looks like this:
+
+```bash
+command="FINGERPRINT=<your SSH fingerprint, not used right now> NAME=default /home/piku/piku.py $SSH_ORIGINAL_COMMAND",no-agent-forwarding,no-user-rc,no-X11-forwarding,no-port-forwarding <your ssh key>
+```
+
+## uWSGI Installation 
+
+[uWSGI][uwsgi] can be installed in a variety of fashions. However, these instructions assume you're installing it from source, and as such may vary from system to system.
+
+### Raspbian
+
+Since Raspbian's a fairly old distribution by now, its `uwsgi-*` packages are outdated (and depend on Python 2.6), so we have to compile and install our own version, as well as using an old-style `init` script to have it start automatically upon boot.
+
+```bash
+sudo apt-get install build-essential python-dev libpcre3-dev
+# at the time of this writing, this installs 2.0.12
+sudo pip install uwsgi
+# refer to our executable using a link, in case there are more versions installed
+ln -s `which uwsgi` /usr/local/bin/uwsgi-piku
+
+# set up our init script
+sudo cp uwsgi-piku.dist /etc/init.d/uwsgi-piku
+sudo chmod +x /etc/init.d/uwsgi-piku
+sudo update-rc.d uwsgi-piku defaults
+sudo service uwsgi-piku start
+```
+
+[uwsgi]: https://github.com/unbit/uwsgi

README.md

@@ -1,24 +1,30 @@
 # piku
 
-The tiniest Heroku-like PaaS you've ever seen, inspired by [dokku][dokku].
+The tiniest Heroku/CloudFoundry-like PaaS you've ever seen, inspired by [dokku][dokku].
 
 ## Motivation
 
-I kept finding myself wanting an Heroku-like way to deploy stuff on a few remote ARM boards and [my Raspberry Pi cluster][raspi-cluster], but since [dokku][dokku] still doesn't work on ARM and even `docker` can be overkill sometimes, I decided to roll my own.
+I kept finding myself wanting an Heroku/CloudFoundry-like way to deploy stuff on a few remote ARM boards and [my Raspberry Pi cluster][raspi-cluster], but since [dokku][dokku] still doesn't work on ARM and even `docker` can be overkill sometimes, I decided to roll my own.
 
 ## Project Status/ToDo:
 
 From the bottom up:
 
 - [ ] Support Node deployments (if at all possible in a sane fashion)
+- [ ] `chroot`/namespace isolation
+- [ ] Proxy deployments to other nodes (build on one box, deploy to many) 
 - [ ] Support Java deployments
 - [ ] Support Go deployments
-- [ ] `chroot` isolation
 - [ ] Support barebones binary deployments
+- [ ] CLI command documentation
 - [ ] Installation instructions
+- [ ] Sample apps
+- [ ] Worker scaling
+- [ ] Port selection (and per-app environment variables)
+- [ ] `Procfile` support
 - [x] Basic CLI commands to manage apps
-- [ ] `virtualenv` isolation
-- [ ] Support Python deployments
+- [x] `virtualenv` isolation
+- [x] Support Python deployments (currently hardcoded)
 - [x] Repo creation upon first push
 - [x] Basic understanding of [how `dokku` works](http://off-the-stack.moorman.nu/2013-11-23-how-dokku-works.html)
 
@@ -26,7 +32,7 @@ From the bottom up:
 
 * Set up an SSH `git` remote pointing to `piku` with the app name as repo name (`git remote add paas piku@server:app1`) 
 * `git push paas master` your code
-* `piku` determines the runtime and installs dependencies
+* `piku` determines the runtime and installs the dependencies for your app (building whatever's required)
 *  It then looks at a `Procfile` and starts the relevant workers using [uWSGI][uwsgi] as a generic process manager
 
 Later on, I intend to do fancier `dokku`-like stuff like reconfiguring `nginx`, but a twist I'm planning on doing is having one `piku` machine act as a build box and deploy the finished product to another.
@@ -43,7 +49,7 @@ In general, it will likely work in any POSIX-like environment where you have Pyt
 
 ## Target Runtimes
 
-I intend to support Python, Go and Java, but will be focusing on Python first, moving from shared runtime to `virtualenv` (and later, if feasible, `pyenv` support).
+I intend to support Python, Go, Node and Java, but will be focusing on Python first, moving from shared runtime to `virtualenv` (and later, if feasible, `pyenv`) support.
 
 ## FAQ
 

requirements.txt

@@ -1,4 +1,3 @@
 click
-tabulate
 uwsgi
 virtualenv

uwsgi/INSTALL.md

@@ -1,17 +0,0 @@
-# uWSGI Installation in Raspbian
-
-Since Raspbian's a fairly old distribution by now, its `uwsgi` packages are outdated (and depend on Python 2.6), so we have to compile and install our own version, and use an `init` script:
-
-```bash
-sudo apt-get install build-essential python-dev libpcre3-dev
-# at the time of this writing, this installs 2.0.12
-sudo pip install uwsgi
-# refer to our executable using a link, in case there are more versions installed
-ln -s `which uwsgi` /usr/local/bin/uwsgi-piku
-
-# set up our init script
-sudo cp uwsgi-piku.sh /etc/init.d/uwsgi-piku
-sudo chmod +x /etc/init.d/uwsgi-piku
-sudo update-rc.d uwsgi-piku defaults
-service uwsgi-piku start
-```