piku: Open Source Build & Deployment

piku is a free, open source build & deployment project written in Python and released under MIT. It has 6,605 GitHub stars, 157 forks and 6 open issues, and was last pushed 14 days ago. On this registry it ranks #22 of 59 tracked projects in Build & Deployment, with 5 head-to-head comparisons available.

What is piku?

piku is a small, MIT-licensed platform-as-a-service tool written in Python that lets developers deploy applications to their own servers with a git push, and it is aimed at people who want a Heroku-like workflow on hardware as modest as a Raspberry Pi.

What it is

piku is a deployment tool that turns a plain Linux host into a small PaaS. It is inspired by dokku and lives in the Python, nginx and uwsgi ecosystem: it runs on Debian and Ubuntu LTS hosts, on both ARM and Intel architectures, on any cloud provider or bare metal machine that can run Python, nginx and uwsgi. It deploys, manages and independently scales multiple applications on a single host, and its configuration is carried in familiar Heroku-style files such as Procfile and an ENV file.

The concrete problem it solves is that container platforms and existing PaaS tools are often too heavy for small machines. The project's stated motivation was wanting a Heroku/CloudFoundry-like way to deploy onto a few ARM boards, at a time when dokku did not work on ARM and even docker could be overkill. piku replaces that heavier deployment path with a workflow built only on git, ssh, nginx and uwsgi, so a single VPS or Raspberry Pi can host several applications reached through different hostnames.

Key capabilities

Heroku-style git push deployment: add a remote with git remote add piku piku@yourserver:appname and deploy with git push piku master, with the app name as the repository name.
Runtime detection and per-app dependency isolation: Python dependencies go into a virtualenv, Go gets a separate GOPATH per app, Node installs what is in package.json into node_modules, Java builds from pom.xml or build.gradle, Clojure uses leiningen or the Clojure CLI with deps.edn, and Ruby runs bundle install into an isolated folder.
Procfile-driven process management, using uwsgi as a generic process manager, including an optional release worker that runs once on deployment.
Runtime control through config:set for application settings and ps:scale to scale worker processes up and down.
An ENV file for baking application and nginx settings into a deployment.
A static worker type that deploys a gh-pages-style static site, taking the root path as its argument.
Full virtual host support, so multiple apps can share one VPS and be reached through DNS aliases, with certificate setup also covered in the documentation.

Who uses it and how

Developers running Raspberry Pi, Raspbian and other ARM boards, who need a deployment path that works on hardware where container tooling is impractical.
Individuals and small teams hosting several apps on one VPS, using virtual hosts and DNS aliases to separate them and ps:scale to size each one independently.
Polyglot projects that mix Python, Node.js, Go, Java, Clojure or Ruby, deployed through one Procfile-based workflow rather than per-language tooling.
Operators on bare metal or any cloud provider willing to run Python, nginx and uwsgi directly instead of a container runtime.

Getting started

The documented quick install is curl https://piku.github.io/get | sh. Other installation methods are also provided, including a cloud-init configuration and manual installation.

How it compares

The README names dokku as the direct inspiration, and names Heroku, CloudFoundry and docker as the models and alternatives it responds to: dokku did not work on ARM at the time, and docker was seen as overkill for the target hardware. Unlike Heroku and CloudFoundry, which are hosted platforms, piku runs on servers the user owns and controls, and it requires only Python, nginx and uwsgi rather than a container runtime.

When to use it — and when not to

A self-hoster must operate the host stack itself: Python 3.10 or above, nginx, uwsgi, git over SSH, plus the Procfile and ENV configuration for each application. It is a poor fit for anyone who wants a managed service, or who expects rapid feature growth: the project is considered STABLE, meaning the feature set is close to finished and updates arrive mainly for new language runtimes and reproducible bugs.

project readme (upstream, from github) — read inline

piku, inspired by dokku, allows you do git push deployments to your own servers, no matter how small they are.

Demo

Documentation: Install | Using | Procfile | ENV | Examples | Roadmap | Contributing | LinuxConf Talk | Fast Web App Tutorial | Discussion Forum

Note to security “researchers” - please stop submitting fake, AI generated SSH ”vulnerabilities” and begging for CVEs to boost your credibility. We know piku allows you to run arbitrary commands (it is actually a CLI feature), and you are just wasting our time. Use AI to improve this instead.

Install

TL;DR:

curl https://piku.github.io/get | sh

There are also other installation methods available, including cloud-init and manual installation.

Project Activity

piku is considered STABLE. It is actively maintained, but "actively" here means the feature set is pretty much done, so it is only updated when new language runtimes are added or reproducible bugs crop up.

It currently requires Python 3.10 or above (which is what we test against). We currently aim to support the latest two Debian and Ubuntu LTS major versions.

Motivation

We wanted an Heroku/CloudFoundry-like way to deploy stuff on a few ARM boards, but since dokku didn't work on ARM at the time and even docker can be overkill sometimes, a simpler solution was needed.

piku is currently able to deploy, manage and independently scale multiple applications per host on both ARM and Intel architectures, and works on any cloud provider (as well as bare metal) that can run Python, nginx and uwsgi.

Workflow

piku supports a Heroku-like workflow:

Create a git SSH remote pointing to your piku server with the app name as repo name: git remote add piku piku@yourserver:appname.
Push your code: git push piku master (or if you want to push a different branch than the current one use git push piku release-branch-name).
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.
- For Java, it builds your app depending on either pom.xml or build.gradle file.
- For Clojure, it can use either leiningen or the Clojure CLI and a deps.edn file.
- For Ruby, it does bundle install of your gems in an isolated folder.
It then looks at a Procfile and starts the relevant workers using uwsgi as a generic process manager.
You can optionally also specify a release worker which is run once when the app is deployed.
You can then remotely change application settings (config:set) or scale up/down worker processes (ps:scale).
You can also bake application and nginx settings into an ENV file. You can also deploy a gh-pages style static site using a static worker type, with the root path as the argument, and run a release task to do some processing on the server after git push.

Virtual Hosts and SSL

piku has full virtual host support - i.e., you can host multiple apps on the same VPS and use DNS aliases to access them via different hostnames.

piku will also set up either a private certificate or obtain one via Let's Encrypt to enable SSL.

If you are on a LAN and are accessing piku from macOS/iOS/Linux clients, you can try using piku/avahi-aliases to announce different hosts for the same IP address via Avahi/mDNS/Bonjour.

Caching and Static Paths

Besides static sites, piku also supports directly mapping specific URL prefixes to filesystem paths (to serve static assets) or caching back-end responses (to remove load from applications).

These features are configured by setting appropriate values in the ENV file.

Supported Platforms

piku is intended to work in any POSIX-like environment where you have Python, nginx, uwsgi and SSH: it has been deployed on Linux, FreeBSD, Cygwin and the Windows Subsystem for Linux.

As a baseline, it began its development on an original 256MB Raspberry Pi Model B, and still runs reliably on it.

But its main use is as a micro-PaaS to run applications on cloud servers with both Intel and ARM CPUs, with Debian and Ubuntu Linux as target platforms.

Supported Runtimes

piku currently supports apps written in Python, Node, Clojure, Java and a few other languages (like Go) in the works.

But as a general rule, if it can be invoked from a shell, it can be run inside piku.

Core values

Run on low end devices.
Accessible to hobbyists and K-12 schools.
~1500 lines readable code.
Functional code style.
Few (single?) dependencies
12 factor app.
Simplify user experience.
Cover 80% of common use cases.
Sensible defaults for all features.
Leverage distro packages in Raspbian/Debian/Ubuntu (Alpine and RHEL support is WIP)
Leverage standard tooling (git, ssh, uwsgi, nginx).
Preserve backwards compatibility where possible

Frequently asked questions

Is piku free to use?

piku is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does piku do?

The tiniest PaaS you've ever seen. Piku allows you to do git push deployments to your own servers.

What is piku written in?

piku is primarily written in Python. Its source is publicly available at https://github.com/piku/piku, and it has 6,605 GitHub stars.