kopia lustrzana https://github.com/piku/piku
Documentation and readme updates (#59)
* Updated README with first-timers in mind. This patch adds information about how to use the script. It also re-orders the information in the README so that the most pertinent information for somebody using it for the first time is at the top. * Logo proposition. * Possibly punchier tag line. * Tagline spacing tweak. * README fixes. * Added a note about the examples folder. * Incorporated @dwightmulcahy suggestion.pull/67/head
Chris McCormick
Rui Carmo
rodzic
dce587c053
commit
6556706e4a
94
README.md
94
README.md
|
|
@ -1,9 +1,73 @@
|
|||
# piku
|
||||
|
||||
|
||||
The tiniest Heroku/CloudFoundry-like PaaS you've ever seen, inspired by [dokku][dokku].
|
||||
The tiniest Heroku/CloudFoundry-like PaaS you've ever seen.
|
||||
|
||||
`piku`, inspired by [dokku][dokku], allows you do `git push` deployments to your own servers.
|
||||
|
||||
[](https://asciinema.org/a/Ar31IoTkzsZmWWvlJll6p7haS)
|
||||
|
||||
## Install
|
||||
|
||||
To use `piku` you need a VPS, Raspberry Pi, or other server bootstrapped with `piku`'s requirements. You can use a single server to run multiple `piku` apps.
|
||||
|
||||
**Warning**: You should use a fresh server or VPS instance without anything important running on it already, as `piku` will make changes to configuration files, running services, etc.
|
||||
|
||||
Once you've got a fresh server, download the [piku-bootstrap](./piku-bootstrap) shell script onto your local machine and run it:
|
||||
|
||||
```shell
|
||||
curl https://raw.githubusercontent.com/rcarmo/piku/master/piku-bootstrap > piku-bootstrap && chmod 755 piku-bootstrap
|
||||
./piku-bootstrap
|
||||
```
|
||||
|
||||
The first time it is run `piku-bootstrap` will install itself into `~/.piku-bootstrap` on your local machine and set up a virtualenv there with the dependencies it requires. It will only need to do this once.
|
||||
|
||||
The script will display a usage message and you can then bootstrap your server:
|
||||
|
||||
```shell
|
||||
./piku-bootstrap yourserver.net
|
||||
```
|
||||
|
||||
If you put the `piku-bootstrap` script on your `PATH` somewhere, you can use it again to provision other servers in the future.
|
||||
|
||||
## Using `piku`
|
||||
|
||||
`piku` supports a Heroku-like workflow, like so:
|
||||
|
||||
* Create a `git` SSH remote pointing to `piku` with the app name as repo name (e.g. `git remote add piku piku@yourserver:appname`).
|
||||
* `git push piku master` your code.
|
||||
* `piku` determines the runtime and installs the dependencies for your app (building whatever's required).
|
||||
* For Python, it segregates each app's dependencies into a `virtualenv`.
|
||||
* For Go, it defines a separate `GOPATH` for each app.
|
||||
* For Node, it installs whatever is in `package.json` into `node_modules`.
|
||||
* 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.
|
||||
* You can also bake application settings into a file called [`ENV` which is documented here](./docs/ENV.md).
|
||||
|
||||
### `piku` client
|
||||
|
||||
To make life easier you can also download the [piku](./piku) helper shell script and install it on your local.
|
||||
|
||||
```shell
|
||||
curl https://raw.githubusercontent.com/rcarmo/piku/master/piku > piku && chmod 755 piku
|
||||
```
|
||||
|
||||
This shell script makes working with `piku` remotes a bit simpler. If you have a git remote called `piku` in the current folder it will infer the remote server and app name and insert those into the remote piku commands. This allows you do execute commands like the following on your running remote app:
|
||||
|
||||
```shell
|
||||
$ piku logs
|
||||
$ piku config:set MYVAR=12
|
||||
$ piku stop
|
||||
$ piku deploy
|
||||
$ piku destroy
|
||||
$ piku # <- will show help for the remote app
|
||||
```
|
||||
|
||||
If you put this `piku` script on your `PATH` you can use the `piku` command across multiple apps on your local.
|
||||
|
||||
### Examples
|
||||
|
||||
You can find examples for deploying various kinds of apps into a `piku` server in the [Examples folder](./examples).
|
||||
|
||||
## Motivation
|
||||
|
||||
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.
|
||||
|
|
@ -17,15 +81,15 @@ From the bottom up:
|
|||
- [ ] Prebuilt Raspbian image with everything baked in
|
||||
- [ ] `chroot`/namespace isolation (tentative)
|
||||
- [ ] Relay commands to other nodes
|
||||
- [ ] Proxy deployments to other nodes (build on one box, deploy to many)
|
||||
- [ ] Support Clojure/Java deployments through `boot` or `lein`
|
||||
- [ ] Support Node deployments
|
||||
- [ ] Proxy deployments to other nodes (build on one box, deploy to many)
|
||||
- [ ] Support Clojure/Java deployments through `boot` or `lein`
|
||||
- [ ] Sample Go app
|
||||
- [ ] Support Go deployments (in progress)
|
||||
- [ ] nginx SSL optimization/cypher suites, own certificates
|
||||
- [ ] Let's Encrypt support
|
||||
- [ ] Review deployment messages
|
||||
- [ ] WIP: Review docs/CLI command documentation (short descriptions done, need `help <cmd>` and better descriptions)
|
||||
- [x] Support Node deployments
|
||||
- [x] Let's Encrypt support
|
||||
- [x] Allow setting `nginx` IP bindings in `ENV` file (`NGINX_IPV4_ADDRESS` and `NGINX_IPV6_ADDRESS`)
|
||||
- [x] Cleanups to remove 2.7 syntax internally
|
||||
- [x] Change to Python 3 runtime as default, with `PYTHON_VERSION = 2` as fallback
|
||||
|
|
@ -35,8 +99,8 @@ From the bottom up:
|
|||
- [x] static URL mapping to arbitrary paths (hat tip to @carlosefr for `nginx` tuning)
|
||||
- [x] remote CLI (requires `ssh -t`)
|
||||
- [x] saner uWSGI logging
|
||||
- [x] `gevent` activated when `UWSGI_GEVENT = <integer>`
|
||||
- [x] enable CloudFlare ACL when `NGINX_CLOUDFLARE_ACL = True`
|
||||
- [x] `gevent` activated when `UWSGI_GEVENT = <integer>`
|
||||
- [x] enable CloudFlare ACL when `NGINX_CLOUDFLARE_ACL = True`
|
||||
- [x] Autodetect SPDY/HTTPv2 support and activate it
|
||||
- [x] Basic nginx SSL config with self-signed certificates and UNIX domain socket connection
|
||||
- [x] nginx support - creates an nginx config file if `NGINX_SERVER_NAME` is defined
|
||||
|
|
@ -44,7 +108,7 @@ From the bottom up:
|
|||
- [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
|
||||
- [x] Worker scaling
|
||||
- [x] Remote CLI commands for changing/viewing applied/live settings
|
||||
- [x] Remote tailing of all logfiles for a single application
|
||||
- [x] HTTP port selection (and per-app environment variables)
|
||||
|
|
@ -56,18 +120,6 @@ From the bottom up:
|
|||
- [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)
|
||||
|
||||
## Using `piku`
|
||||
|
||||
`piku` supports a Heroku-like workflow, like so:
|
||||
|
||||
* Create a `git` SSH 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 the dependencies for your app (building whatever's required)
|
||||
* For Python, it segregates each app's dependencies into a `virtualenv`
|
||||
* For Go, it defines a separate `GOPATH` for each app
|
||||
* 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.
|
||||
|
||||
## Internals
|
||||
|
||||
This is an illustrated example of how `piku` works for a Python deployment:
|
||||
|
|
|
|||
Plik binarny nie jest wyświetlany.
|
Po Szerokość: | Wysokość: | Rozmiar: 10 KiB |
|
|
@ -0,0 +1,105 @@
|
|||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!-- Created with Inkscape (http://www.inkscape.org/) -->
|
||||
|
||||
<svg
|
||||
xmlns:dc="http://purl.org/dc/elements/1.1/"
|
||||
xmlns:cc="http://creativecommons.org/ns#"
|
||||
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
|
||||
xmlns:svg="http://www.w3.org/2000/svg"
|
||||
xmlns="http://www.w3.org/2000/svg"
|
||||
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||
width="918.87872"
|
||||
height="351.30438"
|
||||
id="svg2"
|
||||
version="1.1"
|
||||
inkscape:version="0.48.4 r9939"
|
||||
sodipodi:docname="logo.svg"
|
||||
inkscape:export-filename="logo.png"
|
||||
inkscape:export-xdpi="89.987946"
|
||||
inkscape:export-ydpi="89.987946">
|
||||
<defs
|
||||
id="defs4" />
|
||||
<sodipodi:namedview
|
||||
id="base"
|
||||
pagecolor="#ffffff"
|
||||
bordercolor="#666666"
|
||||
borderopacity="1.0"
|
||||
inkscape:pageopacity="0.0"
|
||||
inkscape:pageshadow="2"
|
||||
inkscape:zoom="1"
|
||||
inkscape:cx="597.41434"
|
||||
inkscape:cy="183.56805"
|
||||
inkscape:document-units="px"
|
||||
inkscape:current-layer="layer1"
|
||||
showgrid="false"
|
||||
inkscape:window-width="1920"
|
||||
inkscape:window-height="1080"
|
||||
inkscape:window-x="0"
|
||||
inkscape:window-y="0"
|
||||
inkscape:window-maximized="0"
|
||||
fit-margin-top="100"
|
||||
fit-margin-left="250"
|
||||
fit-margin-right="250"
|
||||
fit-margin-bottom="100"
|
||||
borderlayer="true"
|
||||
inkscape:showpageshadow="false" />
|
||||
<metadata
|
||||
id="metadata7">
|
||||
<rdf:RDF>
|
||||
<cc:Work
|
||||
rdf:about="">
|
||||
<dc:format>image/svg+xml</dc:format>
|
||||
<dc:type
|
||||
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
|
||||
<dc:title></dc:title>
|
||||
</cc:Work>
|
||||
</rdf:RDF>
|
||||
</metadata>
|
||||
<g
|
||||
inkscape:label="Layer 1"
|
||||
inkscape:groupmode="layer"
|
||||
id="layer1"
|
||||
transform="translate(86.057324,-725.14078)">
|
||||
<g
|
||||
id="g2989"
|
||||
transform="translate(0,6)">
|
||||
<path
|
||||
inkscape:connector-curvature="0"
|
||||
id="path3007"
|
||||
d="m 236.88417,872.36809 -10.55515,7.37544 -1.63689,16.42538 4.64728,8.22211 19.84969,5.51276 6.77336,-15.25887 c 1.24085,-2.80702 0.38264,-6.39365 -1.99438,-8.33499 l -17.08391,-13.94183 z"
|
||||
style="font-size:medium;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-indent:0;text-align:start;text-decoration:none;line-height:normal;letter-spacing:normal;word-spacing:normal;text-transform:none;direction:ltr;block-progression:tb;writing-mode:lr-tb;text-anchor:start;baseline-shift:baseline;color:#000000;fill:#ff2a2a;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:23.48500252;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate;font-family:Sans;-inkscape-font-specification:Sans" />
|
||||
<path
|
||||
inkscape:connector-curvature="0"
|
||||
id="path3054"
|
||||
d="m 240.21441,840.0065 c -0.98948,-0.0481 -2.03206,0.21869 -2.87868,0.73378 -0.005,0.003 -0.0141,-0.003 -0.0188,0 l -37.51686,23.08586 c -1.07299,0.66115 -1.90104,1.80987 -2.22016,3.02919 l -12.86939,49.16328 a 2.0201676,2.0201676 0 0 1 -0.43273,0.82786 l -19.0783,21.52422 c -0.70826,0.80101 -1.15586,1.86938 -1.24178,2.93512 -0.0821,1.0189 0.17515,2.08979 0.69616,2.97275 l 21.01622,23.55626 a 2.0201676,2.0201676 0 0 1 0.20696,0.26341 c 0.81247,1.28681 2.34,2.21251 3.85705,2.33304 1.51714,0.12042 3.19032,-0.55089 4.19572,-1.69334 a 2.0201676,2.0201676 0 0 1 0.1317,-0.11289 l 18.36333,-17.59194 a 2.0201676,2.0201676 0 0 1 0.84667,-0.48919 l 42.05125,-11.90981 c 0.006,-0.002 0.0133,0.002 0.0187,0 0.35703,-0.10402 0.70942,-0.25301 1.03483,-0.43274 l 35.07093,-19.19118 c 1.1869,-0.65116 2.13294,-1.86726 2.46475,-3.17971 0.33185,-1.31249 0.0951,-2.85172 -0.63971,-3.98876 L 286.7059,901.7193 c -0.66937,-1.03355 -1.78021,-1.83825 -2.97275,-2.14489 -1.1925,-0.30667 -2.56514,-0.13091 -3.65008,0.45156 l -27.09344,14.54389 a 2.0201676,2.0201676 0 0 1 -1.48637,0.16934 l -24.04541,-6.67928 a 2.0201676,2.0201676 0 0 1 -1.22297,-0.94075 l -5.38106,-9.55795 a 2.0201676,2.0201676 0 0 1 -0.24459,-1.18534 l 1.78741,-17.96821 a 2.0201676,2.0201676 0 0 1 0.86549,-1.44875 l 16.85813,-11.77811 a 2.0201676,2.0201676 0 0 1 1.31704,-0.35748 l 42.16414,3.44312 c 1.14187,0.0924 2.35376,-0.24673 3.29261,-0.90312 0.93888,-0.65644 1.67034,-1.68046 1.97556,-2.7846 l 3.57483,-13.00108 c 0.37655,-1.37144 0.10311,-3.00057 -0.69615,-4.1769 -0.79603,-1.17158 -2.20453,-2.02242 -3.61246,-2.18253 l -0.0188,0 -47.56401,-5.21172 0,0.0188 c -0.10036,-0.009 -0.19677,-0.0158 -0.30104,-0.0188 a 2.0201676,2.0201676 0 0 1 -0.0376,0 z"
|
||||
style="font-size:medium;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-indent:0;text-align:start;text-decoration:none;line-height:normal;letter-spacing:normal;word-spacing:normal;text-transform:none;direction:ltr;block-progression:tb;writing-mode:lr-tb;text-anchor:start;baseline-shift:baseline;color:#000000;fill:#ff2a2a;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:6.71000051;marker:none;visibility:visible;display:inline;overflow:visible;enable-background:accumulate;font-family:Sans;-inkscape-font-specification:Sans" />
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:135.58976746px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#ff2a2a;fill-opacity:1;stroke:none;font-family:Varela Round;-inkscape-font-specification:Varela Round"
|
||||
x="454.81302"
|
||||
y="918.79926"
|
||||
id="text3056"
|
||||
sodipodi:linespacing="125%"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3058"
|
||||
x="454.81302"
|
||||
y="918.79926">piku</tspan></text>
|
||||
</g>
|
||||
<text
|
||||
xml:space="preserve"
|
||||
style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Varela Round;-inkscape-font-specification:Varela Round"
|
||||
x="-74.99691"
|
||||
y="605.91644"
|
||||
id="text3224"
|
||||
sodipodi:linespacing="125%"><tspan
|
||||
sodipodi:role="line"
|
||||
id="tspan3226"
|
||||
x="-74.99691"
|
||||
y="605.91644">typeface: Varela Round</tspan><tspan
|
||||
sodipodi:role="line"
|
||||
x="-74.99691"
|
||||
y="655.91644"
|
||||
id="tspan3228">color: #ff2a2a </tspan></text>
|
||||
</g>
|
||||
</svg>
|
||||
|
Po Szerokość: | Wysokość: | Rozmiar: 6.4 KiB |
Ładowanie…
Reference in New Issue