Skip to content

Latest commit

 

History

History
306 lines (223 loc) · 11.3 KB

INSTALL.md

File metadata and controls

306 lines (223 loc) · 11.3 KB
Raw

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 for systemd 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 16.04

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.

Also, please note that uwsgi-piku.service, as provided, creates a /run/uwsgi-piku directory for it to place socket files and sundry. This is not actually used at the moment, since the uwsgi socket file is placed inside the piku user directory for consistency across OS distributions. This will be cleaned up in a later release.

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

Java 8 Installation (All Debian Linux variants, on Raspberry Pi)

To be able to deploy Java apps, we're going to need to install Java (and, since we're going to be doing so on ARM, it's best to use Oracle's runtime). To do that, we're going to use the webupd8team PPA, which has a (cross-platform) Java installer.

First, get rid of OpenJDK and import the PPA key:

sudo apt-get remove openjdk*
sudo apt-key adv --recv-key --keyserver keyserver.ubuntu.com EEA14886

Raspbian Jessie

For Jessie, we're going to use the trusty version of the installer:

sudo tee /etc/apt/sources.list.d/webupd8team.list
deb http://ppa.launchpad.net/webupd8team/java/ubuntu trusty main 
deb-src http://ppa.launchpad.net/webupd8team/java/ubuntu trusty main
^D

Ubuntu 16.04 for ARM

For Xenial, we're going to use its own version:

sudo tee /etc/apt/sources.list.d/webupd8team.list
deb http://ppa.launchpad.net/webupd8team/java/ubuntu xenial main 
deb-src http://ppa.launchpad.net/webupd8team/java/ubuntu xenial main
^D

Now perform the actual install:

sudo apt-get update
sudo apt-get install oracle-java8-installer oracle-java8-set-default

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.

  1. Get an ARM 6 binary tarball
  2. 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
  1. Give it a temporary GOPATH and install godep:
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.