piku: git push deployments to your own small servers

The problem piku solves: Heroku-style deploys without Docker

The README is explicit about the origin: the authors wanted a Heroku or CloudFoundry-like way to deploy on a few ARM boards, and dokku did not work on ARM at the time, while Docker was sometimes overkill. That is the gap piku fills. It gives you the push-to-deploy loop on hardware that would struggle to run a container runtime, and it does so using tools that a Debian or Ubuntu box almost certainly already has: git, ssh, nginx and uwsgi.

The target user is not a platform team running a Kubernetes cluster. It is someone with a Raspberry Pi, a small VPS, or a rack of ARM boards who wants several apps on one host with separate dependencies and separate process counts. The README states piku can deploy, manage and scale multiple applications per host on both ARM and Intel, on any provider or bare metal that can run Python, nginx and uwsgi. It also lists K-12 schools and hobbyists in its core values, which sets the tone for the documentation: it assumes you can read a config file and an SSH error, not that you have an on-call rotation.

How a git push becomes a running process

The mechanism is a git remote over SSH. You add a remote whose path is the app name, push a branch, and the server-side hook does the rest. The README describes the server determining the runtime, installing dependencies, then reading a Procfile and starting workers with uwsgi as a generic process manager.

Dependency isolation is per language and per app, and the README is specific about each: Python apps get their own virtualenv, Go apps get a separate GOPATH, Node installs package.json contents 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. There is no shared dependency layer and no image build step. The Procfile is where process types are declared, and an optional release worker runs once per deploy, which is the hook for migrations or asset processing.

Two things sit outside the app process. nginx handles virtual hosts and SSL, and the README says piku will set up either a private certificate or obtain one via Let's Encrypt. Static serving and response caching are also configured through the ENV file rather than through the app, which means some performance work happens at the proxy layer instead of in your code. The whole thing is roughly 1500 lines of Python according to the README's core values, and requirements.txt notes that click, uwsgi and virtualenv are only there for automated tests, not because piku pip-installs them.

Installing piku and pushing a first app

The README's TL;DR is a single command that fetches and runs an install script. It also points to cloud-init and manual installation methods on the install page.

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

After that, you deploy the way you would to Heroku: add a remote whose host is your server and whose path is the app name, then push. The README gives this exact form.

git remote add piku piku@yourserver:appname
git push piku master

If you want to push a branch other than the current one, the README says to name it in the push, for example git push piku release-branch-name. The server picks the branch you pushed and builds from it.

What the server needs from your repository is a Procfile describing the process types. The examples directory in the repository contains examples/Procfile and examples/ENV, which are the two files worth copying first. Once the app is up, settings and process counts are changed remotely with config:set and ps:scale, both named in the README's workflow section. A static site is a special case: the README says you deploy it with a static worker type and the root path as the argument.

Where piku stops being the right tool

The most important limitation is stated by the project itself: piku is considered stable, and "actively maintained" means the feature set is pretty much done, with updates only when new language runtimes are added or reproducible bugs crop up. If your roadmap depends on the deployment tool growing features, this is the wrong bet. The last push was on 2026-09-04, and the release history shows v1.0.0 in April 2024 and a legacy edition in March 2023, so the cadence is slow by design rather than by neglect.

Isolation is the second boundary. piku installs dependencies into per-app virtualenvs, GOPATHs, node_modules and bundle folders, but the README does not describe containers, namespaces or resource limits between apps on the same host. A runaway process in one app is a host problem. If you need hard multi-tenant isolation, or you are deploying untrusted code from other people, a container-based platform is the safer choice and piku is not trying to be one.

There is also a platform constraint. The README states Python 3.10 or above is required and that the project aims to support the latest two Debian and Ubuntu LTS major versions. Alpine and RHEL support is listed as work in progress. So a Fedora or Alpine host is outside the tested path, even though the README says piku has run on FreeBSD, Cygwin and WSL. Finally, the README carries a pointed note asking security researchers to stop filing AI-generated SSH vulnerability reports, observing that running arbitrary commands is a CLI feature. Read that as a statement of the trust model: anyone with push access to a piku remote can run commands on the host.

piku compared with dokku

The README names dokku as the inspiration, and the difference is in what each one is built on. dokku is a Docker-based PaaS: it builds an image per app and runs containers. piku does not use containers at all; it uses uwsgi as a process manager and nginx as the front end, with per-app dependency directories on the host filesystem.

That difference decides the hardware. The README says dokku did not work on ARM at the time piku was written, and that Docker can be overkill, which is why piku began on a 256MB Raspberry Pi Model B and still runs there. If your host is a small ARM board or a cheap VPS, piku's approach removes the container runtime from the equation entirely. The cost is the isolation and the image portability you would get from dokku. You cannot promote the same artifact from staging to production, because there is no artifact: the build happens on the target host at push time.

A second practical difference is configuration surface. piku keeps app and nginx settings in an ENV file in the repository, and virtual hosts, SSL, static paths and response caching are all driven from there. That is a smaller surface than a full Dockerfile plus a platform config, and it is easier to review in a pull request. It is also less flexible when an app needs something the ENV keys do not express.

Maintenance cost, licence and what to check before adopting

The upgrade path is the operating system, not the tool. piku tracks the latest two Debian and Ubuntu LTS releases and needs Python 3.10 or above, so your maintenance work is mostly keeping the host current and confirming that the language runtimes your apps use are still covered. Because dependencies live on the host in per-app directories, a host rebuild means redeploying each app from its git remote rather than restoring an image. Plan for that.

The repository is MIT licensed, which is permissive and places few obligations on how you use or redistribute it. That is a statement about the licence text, not legal advice; if you are embedding piku in a product you ship, have someone qualified read the LICENSE file in the repository root.

Before you commit, verify three things. That your host is a supported Debian or Ubuntu LTS with Python 3.10 or above. That your app's runtime appears in the README's list of supported languages, or that it can be invoked from a shell, which the README gives as the general rule. And that you are comfortable with the trust model, since piku grants command execution to anyone who can push. The install page at piku.github.io/install is where the manual and cloud-init routes are documented if the curl script is not acceptable in your environment.

Editorial conclusion

piku fits hobbyists, K-12 schools and small teams who already run nginx and SSH and want Heroku-style deploys on hardware as small as a 256MB Raspberry Pi Model B. It is the wrong tool if you need container isolation, a web dashboard, or a managed control plane, because the README describes a CLI and a git remote, not a scheduler or an orchestrator. Before adopting it, check that your host runs a supported Debian or Ubuntu LTS release with Python 3.10 or above, and read the ENV and Procfile pages at piku.github.io to confirm your app's runtime is covered. The repository's last push was on 2026-09-04, and the README states the feature set is "pretty much done", so evaluate it as a stable, slow-moving tool rather than one that will absorb new requirements.

Frequently asked questions

Official sources

1. License: MIT
2. piku/piku on GitHub
3. Project website
4. README
5. Releases