piku/README.md

117 wiersze
6.5 KiB
Markdown
Czysty Zwykły widok Historia

2016-03-26 12:52:54 +00:00
# piku
2016-03-28 22:28:38 +00:00
The tiniest Heroku/CloudFoundry-like PaaS you've ever seen, inspired by [dokku][dokku].
2016-03-26 12:52:54 +00:00
## Motivation
2019-04-17 12:13:08 +00:00
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] didn't work on ARM at the time and even `docker` can be overkill sometimes, I decided to roll my own.
2016-03-26 12:52:54 +00:00
2017-04-05 20:26:36 +00:00
## Project Status/To Do:
2016-03-26 12:52:54 +00:00
2019-05-22 17:52:42 +00:00
This is currently being used for production deployments of [my website](https://taoofmac.com) and a few other projects of mine that run on Azure and other IaaS providers. Regardless, there is still room for improvement:
2016-05-03 22:29:33 +00:00
2016-03-26 12:52:54 +00:00
From the bottom up:
2016-04-03 16:33:38 +00:00
- [ ] Prebuilt Raspbian image with everything baked in
- [ ] `chroot`/namespace isolation (tentative)
2016-05-03 22:29:33 +00:00
- [ ] Relay commands to other nodes
2016-03-28 22:28:38 +00:00
- [ ] Proxy deployments to other nodes (build on one box, deploy to many)
2016-05-03 22:29:33 +00:00
- [ ] Support Clojure/Java deployments through `boot` or `lein`
2016-04-03 16:33:38 +00:00
- [ ] Support Node deployments
2016-04-03 10:35:39 +00:00
- [ ] Sample Go app
2016-04-25 10:50:37 +00:00
- [ ] Support Go deployments (in progress)
2016-05-03 22:29:33 +00:00
- [ ] nginx SSL optimization/cypher suites, own certificates
2017-04-05 20:26:36 +00:00
- [ ] Let's Encrypt support
2018-08-23 12:46:52 +00:00
- [ ] Review deployment messages
2019-05-22 12:29:06 +00:00
- [ ] WIP: Review docs/CLI command documentation (short descriptions done, need `help <cmd>` and better descriptions)
2018-12-23 15:19:43 +00:00
- [x] Allow setting `nginx` IP bindings in `ENV` file (`NGINX_IPV4_ADDRESS` and `NGINX_IPV6_ADDRESS`)
2018-12-23 15:19:32 +00:00
- [x] Cleanups to remove 2.7 syntax internally
2018-08-23 12:46:52 +00:00
- [x] Change to Python 3 runtime as default, with `PYTHON_VERSION = 2` as fallback
2018-06-14 21:05:43 +00:00
- [x] Run in Python 3 only
2017-05-15 20:52:19 +00:00
- [x] (experimental) REPL in `feature/repl`
2017-04-05 20:26:36 +00:00
- [x] Python 3 support through `PYTHON_VERSION = 3`
2016-11-20 10:07:48 +00:00
- [x] static URL mapping to arbitrary paths (hat tip to @carlosefr for `nginx` tuning)
2016-09-10 09:47:29 +00:00
- [x] remote CLI (requires `ssh -t`)
2016-05-14 17:56:30 +00:00
- [x] saner uWSGI logging
2016-05-14 17:31:02 +00:00
- [x] `gevent` activated when `UWSGI_GEVENT = <integer>`
- [x] enable CloudFlare ACL when `NGINX_CLOUDFLARE_ACL = True`
2016-05-03 22:29:33 +00:00
- [x] Autodetect SPDY/HTTPv2 support and activate it
2016-04-25 12:32:52 +00:00
- [x] Basic nginx SSL config with self-signed certificates and UNIX domain socket connection
2016-05-14 17:31:02 +00:00
- [x] nginx support - creates an nginx config file if `NGINX_SERVER_NAME` is defined
2016-04-03 22:58:11 +00:00
- [x] Testing with pre-packaged [uWSGI][uwsgi] versions on Debian Jessie (yes, it was painful)
2016-04-03 16:33:38 +00:00
- [x] Support barebones binary deployments
- [x] Complete installation instructions (see `INSTALL.md`, which also has a draft of Go installation steps)
- [x] Installation helper/SSH key setup
- [x] Worker scaling
2016-04-02 15:46:03 +00:00
- [x] Remote CLI commands for changing/viewing applied/live settings
2016-04-02 00:05:19 +00:00
- [x] Remote tailing of all logfiles for a single application
- [x] HTTP port selection (and per-app environment variables)
2016-03-29 21:06:53 +00:00
- [x] Sample Python app
2016-03-31 22:44:36 +00:00
- [X] `Procfile` support (`wsgi` and `worker` processes for now, `web` processes being tested)
2016-03-26 23:38:20 +00:00
- [x] Basic CLI commands to manage apps
2016-03-28 22:28:38 +00:00
- [x] `virtualenv` isolation
2016-04-03 10:35:39 +00:00
- [x] Support Python deployments
2016-03-26 12:52:54 +00:00
- [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)
2016-04-03 16:35:32 +00:00
## Using `piku`
2016-04-03 10:49:42 +00:00
2016-04-03 16:33:38 +00:00
`piku` supports a Heroku-like workflow, like so:
2016-03-26 12:52:54 +00:00
2016-04-03 16:33:38 +00:00
* Create a `git` SSH remote pointing to `piku` with the app name as repo name (`git remote add paas piku@server:app1`)
2016-03-26 17:30:45 +00:00
* `git push paas master` your code
2016-03-28 22:28:38 +00:00
* `piku` determines the runtime and installs the dependencies for your app (building whatever's required)
2016-04-02 00:05:19 +00:00
* For Python, it segregates each app's dependencies into a `virtualenv`
2016-04-03 10:35:39 +00:00
* For Go, it defines a separate `GOPATH` for each app
2016-04-03 10:49:42 +00:00
* It then looks at a `Procfile` and starts the relevant workers using [uWSGI][uwsgi] as a generic process manager
* You can then remotely change application settings (`config:set`) or scale up/down worker processes (`ps:scale`) at will.
2016-03-26 12:52:54 +00:00
2016-11-26 23:13:46 +00:00
## Internals
This is an illustrated example of how `piku` works for a Python deployment:
2016-11-26 23:11:31 +00:00
![](img/piku.png)
2016-03-26 12:52:54 +00:00
2016-04-03 10:49:42 +00:00
## Supported Platforms
2016-03-26 13:05:52 +00:00
2016-04-03 10:49:42 +00:00
`piku` is intended to work in any POSIX-like environment where you have Python, [uWSGI][uwsgi] and SSH, i.e.:
Linux, FreeBSD, [Cygwin][cygwin] and the [Windows Subsystem for Linux][wsl].
2016-03-26 13:05:52 +00:00
2019-05-22 17:52:42 +00:00
As a baseline, it began its development on an original, 256MB Rasbperry Pi Model B, and still runs reliably on it.
2016-03-26 13:05:52 +00:00
2019-05-22 17:52:42 +00:00
Since I have an ODROID-U2, [a bunch of Pi 2s][raspi-cluster] and a few more ARM boards on the way, it is often tested on a number of places where running `x64` binaries is unfeasible.
2016-03-26 13:05:52 +00:00
2016-04-03 16:38:05 +00:00
But there are already a few folk using `piku` on vanilla `x64` Linux without any issues whatsoever, so yes, you can use it as a micro-PaaS for 'real' stuff. Your mileage may vary.
2016-04-03 10:49:42 +00:00
## Supported Runtimes
2016-03-26 12:52:54 +00:00
2019-05-22 17:52:42 +00:00
`piku` currently supports deploying apps (and dependencies) written in Python, with Go, Clojure (Java) and Node (see [above](#project-statustodo)) in the works. But if it can be invoked from a shell, it can be run inside `piku`.
2016-03-26 12:52:54 +00:00
## FAQ
**Q:** Why `piku`?
2016-03-26 13:05:52 +00:00
**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.
2016-03-26 12:52:54 +00:00
2016-04-03 10:35:39 +00:00
**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.
2019-05-22 17:52:42 +00:00
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.
2016-03-28 23:00:23 +00:00
**Q:** Does it run under Python 3?
2019-05-22 17:52:42 +00:00
**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.
2016-03-28 23:00:23 +00:00
2016-03-26 12:52:54 +00:00
**Q:** Why not just use `dokku`?
2019-05-22 17:52:42 +00:00
**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.
2016-03-26 12:52:54 +00:00
[click]: http://click.pocoo.org
2016-03-26 12:52:54 +00:00
[pi]: http://www.raspberrypi.org
[dokku]: https://github.com/dokku/dokku
2016-03-26 13:05:52 +00:00
[raspi-cluster]: https://github.com/rcarmo/raspi-cluster
2016-03-26 23:38:20 +00:00
[cygwin]: http://www.cygwin.com
2016-03-31 22:44:36 +00:00
[uwsgi]: https://github.com/unbit/uwsgi
2016-04-03 10:49:42 +00:00
[wsl]: https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux