9.8 KiB
Installation
These installation notes should cover most Debian Linux variants (on any architecture). Very minor changes should be required to deploy on RHEL variants like CentOS, and there is specific emphasis on Raspbian because that's the typical deployment target.
You can, however, run piku
on any POSIX-like environment where you have Python, uWSGI and SSH.
For installation, you only require root
/sudo
access and the following three files:
piku.py
uwsgi-piku.service
(this one is forsystemd
systems such as Raspbian Jessie/Debian 8)uwsgi-piku.dist
(this one should only be necessary on older systems)
Copy them across to the machine you'll be using as a server before you get started with the rest.
Setting up the piku
user (Debian Linux, any architecture)
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:
sudo adduser --disabled-password --gecos 'PaaS access' --ingroup www-data piku
This user is not supposed to login to your system. Instead, you'll interact with piku
via SSH, and set things up by using su
:
sudo su - piku
mkdir ~/.ssh
chmod 700 ~/.ssh
# now copy the piku script to this user account
cp /tmp/piku.py ~/piku.py
Dependencies
Before running piku
for the first time, you need to install the following Python packages at the system level:
Raspbian Jessie, Debian 8, Ubuntu
sudo apt-get install git python-virtualenv python-pip
sudo pip install -U click
Raspbian Wheezy
sudo apt-get install git python2.7
sudo easy_install -U pip
sudo pip install -U click virtualenv
These may or may not be installed already (click
usually isn't). For Raspbian Wheezy this is the preferred approach, since current apt
packages are fairly outdated.
Intialization
To set everthing up, type python piku.py setup
:
sudo su - piku
python piku.py setup
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.
Setting 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 installed).
On your own machine, issue the ssh-keygen
command and follow the prompts:
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]----+
<...>
+-----------------+
Adding the key to piku
Copy the resulting id_rsa.pub
(or equivalent, just make sure it's the public file) to your piku
server and do the following:
sudo su - piku
python 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:
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.
Testing
From your machine, do:
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
git-hook INTERNAL: Post-receive git hook
git-receive-pack INTERNAL: Handle git pushes for an app
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.
And that's it, you're set. Now to configure uWSGI, which is what piku
relies upon to manage your apps at runtime.
uWSGI Installation (Debian Linux variants, any architecture)
uWSGI can be installed in a variety of fashions. These instructions cover both pre-packaged and source installs depending on your system.
Raspbian Jessie, Debian 8
In Raspbian Jessie, Debian 8 and other systemd
distributions where uWSGI is already available pre-compiled (but split into a number of plugins), do the following:
# At the time of this writing, this installs uwsgi 2.0.7 on Raspbian Jessie.
# You can also install uwsgi-plugins-all if you want to get runtime support for other languages
sudo apt-get install uwsgi uwsgi-plugin-python
# refer to our executable using a link, in case there are more versions installed
sudo ln -s `which uwsgi` /usr/local/bin/uwsgi-piku
# disable the standard uwsgi startup script
sudo systemctl disable uwsgi
# add our own startup script
sudo cp /tmp/uwsgi-piku.service /etc/systemd/system/
sudo systemctl enable uwsgi-piku
sudo systemctl start uwsgi-piku
# check it's running
sudo systemctl status uwsgi-piku.service
Important Note: Make sure you run piku.py setup
as outlined above before starting the service.
Raspbian Wheezy
Since Raspbian Wheezy is a fairly old distribution by now, its uwsgi-*
packages are completely 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.
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
sudo ln -s `which uwsgi` /usr/local/bin/uwsgi-piku
# set up our init script
sudo cp /tmp/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
Important Note: Make sure you run piku.py setup
as outlined above before starting the service.
Ubuntu 14.04 LTS
This is a mix of both the above, and should change soon when we get 16.04. If you have trouble, install uWSGI via pip
instead.
# At the time of this writing, this installs uwsgi 1.9.17 on Ubuntu 14.04 LTS.
# You can also install uwsgi-plugins-all if you want to get runtime support for other languages
sudo apt-get install uwsgi uwsgi-plugin-python
# refer to our executable using a link, in case there are more versions installed
sudo ln -s `which uwsgi` /usr/local/bin/uwsgi-piku
# set up our init script
sudo cp /tmp/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
nginx Installation (Raspbian 8, Ubuntu 16.04)
PLEASE NOTE: There is a bug in nginx
1.6.2 under Raspbian 8 that causes it to try to allocate around a gigabyte of RAM when using SSL with SPDY. I seriously recommend using Ubuntu instead, if you can, or disabling SSL altogether.
sudo apt-get install nginx incron
# Set up nginx to pick up our config files
sudo cp /tmp/nginx.default.dist /etc/nginx/sites-available/default
# Set up incron to reload nginx upon config changes
sudo cp /tmp/incron.dist /etc/incron.d/piku
sudo systemctl restart incron
sudo systemctl restart nginx
Go Installation (All Debian Linux variants, on Raspberry Pi)
This is EXPERIMENTAL and may not work at all.
Raspbian Wheezy/Jessie
Since Raspbian's Go compiler is version 1.0.2, we need something more up-to-date.
- Get an ARM 6 binary tarball
- Unpack it under the
piku
user like such:
sudo su - piku
tar -zxvf /tmp/go1.5.3.linux-arm.tar.gz
# remove unnecessary files
rm -rf go/api go/blog go/doc go/misc go/test
- Give it a temporary
GOPATH
and installgodep
:
sudo su - piku
GOROOT=$HOME/go GOPATH=$HOME/gopath PATH=$PATH:$HOME/go/bin go get github.com/tools/godep
# temporary workaround until this is fixed in godep or Go 1.7(?)
GOROOT=$HOME/go GOPATH=$HOME/gopath PATH=$PATH:$HOME/go/bin go get golang.org/x/sys/unix
TODO: complete this.