https://github.com/shiwaforce/poco
Poco will help you to organise and manage Docker, Docker-Compose, Kubernetes, Openshift projects of any complexity using simple YAML config files to shorten the route from finding your project to initialising it in your local environment.
https://github.com/shiwaforce/poco
catalog docker docker-compose docker-container docker-image project-catalog project-compose python
Last synced: 11 days ago
JSON representation
Poco will help you to organise and manage Docker, Docker-Compose, Kubernetes, Openshift projects of any complexity using simple YAML config files to shorten the route from finding your project to initialising it in your local environment.
- Host: GitHub
- URL: https://github.com/shiwaforce/poco
- Owner: shiwaforce
- License: mit
- Created: 2017-07-10T13:58:08.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2024-01-19T08:14:07.000Z (about 2 years ago)
- Last Synced: 2024-07-31T21:56:15.206Z (over 1 year ago)
- Topics: catalog, docker, docker-compose, docker-container, docker-image, project-catalog, project-compose, python
- Language: Python
- Homepage: https://getpoco.io
- Size: 610 KB
- Stars: 103
- Watchers: 8
- Forks: 6
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-docker - proco - Proco will help you to organise and manage Docker, Docker-Compose, Kubernetes projects of any complexity using simple YAML config files to shorten the route from finding your project to initialising it in your local environment. by [@shiwaforce](https://github.com/shiwaforce) (Container Operations / User Interface)
- awesome-docker - proco - Proco will help you to organise and manage Docker, Docker-Compose, Kubernetes projects of any complexity using simple YAML config files to shorten the route from finding your project to initialising it in your local environment. by [@shiwaforce](https://github.com/shiwaforce) (Container Operations / User Interface)
- fucking-awesome-docker - proco - Proco will help you to organise and manage Docker, Docker-Compose, Kubernetes projects of any complexity using simple YAML config files to shorten the route from finding your project to initialising it in your local environment. by [@shiwaforce](https://github.com/shiwaforce) (Container Operations / User Interface)
- awesome-docker - proco - Proco will help you to organise and manage Docker, Docker-Compose, Kubernetes projects of any complexity using simple YAML config files to shorten the route from finding your project to initialising it in your local environment. (Container Operations / User Interface)
README
# POCO
[](https://github.com/shiwaforce/poco/actions/workflows/test.yaml)
[](https://pypi.python.org/pypi/poco)
[](https://pypi.python.org/pypi/poco)
[](https://codeclimate.com/github/shiwaforce/poco/test_coverage)
[](https://codeclimate.com/github/shiwaforce/poco/maintainability)
**Poco** is one CLI for **Docker**, **Kubernetes** and **Helm**: catalogue and run compose projects, switch kubectl context and namespace, and list Helm repos and releases — without leaving your terminal or remembering three different tools.
- **Docker** — `poco up`, `poco down`, `poco ps`, `poco status` (overview), compose config, build, pull; YAML catalog and plans.
- **Kubernetes** — `poco kubectx`, `poco kubens` (list/switch context and namespace); `poco kube-get pods|ns|svc|...`; presets (context+namespace in one command).
- **Helm** — `poco helm-repos`, `poco helm-list` (releases; optional `--all-namespaces`, `-i` to pick and show status).
- **Simple**. Configure, run and switch between projects with a very simple command line interface.
- **Flexibility**. Manage, scale, maintain projects of any complexity with ease.
- **Configure Once, Use Everywhere**. Configure project once so the rest of your team will feel the value of zero configuration.
## Features
- **Docker, Kubernetes, Helm in one place** — Compose projects, kubectl context/namespace, Helm repos and releases.
- **Git, SVN** support out of the box.
- **Project Catalog, Multiple Catalogues**. Create your own project catalog. Organise your projects without additional tools.
- **Multiple Plans**. Create multiple plans for different environments or even environments for demo purposes. Switch between plans (environments) with ease.
- **Simple Config Files**. Poco helps to split config files, so it is easy to maintain and scale them any time.
- **Script Support (Hooks)**. Add additional scripts any time.
## Global options
- `-i`, `--interactive` — Interactive menu: choose actions step by step without typing commands (`poco -i`).
- `-V`, `--verbose` — Print more (e.g. merged docker compose config for `up`/`down`).
- `-VV` or `--no-matrix` — No matrix effect, show full output (for `up`/`down`). Implies verbose.
- `-q`, `--quiet` — Print less.
- `--offline` — Offline mode.
- `--always-update` — Project repository handle by user.
For `poco up` / `poco down`, a matrix-style effect runs by default; only the final result is shown. Set `POCO_MATRIX=0` to disable the effect, or use `-VV` / `--no-matrix` to disable it and see the full log.
## Documentation
All documentation is available on [getpoco.io](https://getpoco.io/)
- [Documentation](https://getpoco.io/documentation/)
- [Install](https://getpoco.io/documentation/install/)
- [Tutorials](https://getpoco.io/tutorials/hello-world/)
- [Github, Gitlab Integration](https://getpoco.io/documentation/third-party-integrations/)
## Requirements
- **Python 3.12.3** or newer (supported version: **3.14.3**)
- Git or SVN
- SSH
- Docker (17.0.0 or higher version is recommended)
- Docker Compose V2 (plugin: `docker compose`), for compose support
- kubectl, for Kubernetes support
- helm, for helm functionality support
## Quick start
Install `poco`:
```
$:~ pip install poco
```
**Or use the install script (curl one-liner):**
```bash
bash -c "$(curl -fsSL https://raw.githubusercontent.com/shiwaforce/poco/master/install.sh)"
```
**Install script options:**
| Option | Description |
|--------|-------------|
| **Full reset** | Remove previous install, then install fresh: `bash -c "$(curl -fsSL https://raw.githubusercontent.com/shiwaforce/poco/master/install.sh)" -- --reset` |
| **Self-update** | Update the install script itself: `bash -c "$(curl -fsSL https://raw.githubusercontent.com/shiwaforce/poco/master/install.sh)" -- --update` |
| **Dev branch** | Install from `dev` branch: `bash -c "$(curl -fsSL https://raw.githubusercontent.com/shiwaforce/poco/master/install.sh)" -- dev` |
Init project:
```
$:~ mkdir my-project
$:~ cd my-project
$:~ poco init
```
`poco.yml` and `docker-compose.yml` example files will be created.
Start project:
```
$:~ poco up
```
Before adding your project to Poco Repo create new empty git repository,
add repository to your local Poco Repo config:
```
$:~ poco repo add
```
Now you can add your project to repo:
```
$:~ poco project add [] []
```
Publish your changes:
```
$:~ poco repo push
```
Stop your project:
```
$:~ poco stop
```
## One CLI: Docker, kubectl, Helm
| Stack | Poco commands | What you get |
|----------|----------------|--------------|
| **Docker** | `poco up`, `poco down`, `poco ps`, `poco config`, … | Compose projects from a YAML catalog; matrix-style run; verbose merged config. |
| **Kubernetes** | `poco kubectx`, `poco kubens` | List/switch context and namespace (kubectx/kubens-style). |
| **Helm** | `poco helm-repos`, `poco helm-list` | List repos and releases; `helm-list --all-namespaces` for all. |
Requires Docker and/or `kubectl`/`helm` installed. Poco checks availability and works with different kubectl/helm versions.
### Presets (workflow)
Save and switch context + namespace in one step:
- `poco preset list` — List saved presets.
- `poco preset use ` — Switch to a preset (context and namespace).
- `poco preset save ` — Save current context and namespace as a preset.
Presets are stored in `~/.poco/presets.yml`.
### Kube-get
Shortcut for common `kubectl get` usage:
- `poco kube-get [name]` — e.g. `poco kube-get pods`, `poco kube-get ns`, `poco kube-get svc`.
- Use `-n ` or `-A` (all namespaces) when needed.
### Interactive mode (`-i` / `--choose`)
When a command can show a list, use `-i` to pick from a menu (or fzf if installed):
- `poco kubectx -i` — Choose context from list.
- `poco kubens -i` — Choose namespace from list.
- `poco preset use -i` — Choose preset from list.
- `poco helm-list -i` — Choose release, then show `helm status`.
## Security
- **Dependencies:** We track known vulnerabilities and bump affected packages (e.g. GitPython ≥3.1.41 for CVE fixes). To audit your install: `pip install pip-audit && pip-audit` (or `pip-audit -r requirements.txt`).
- **Build tools:** Keep setuptools and wheel up to date: `pip install -U setuptools wheel` to address CVEs in the toolchain.
## Agent Skills
Use Poco with AI coding agents (Cursor, Claude Code, etc.): install [Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) so the agent knows when and how to run poco. Add the **poco-skills** repo as a Remote Rule: **Settings > Rules > Add Rule > Remote Rule (Github)** with `shiwaforce/poco-skills`. Optionally, run `poco init --with-cursor-skill` in a project to generate a project-specific skill (`.cursor/skills/poco-project/SKILL.md`).
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for release history. **1.0** — Docker + Kubernetes + Helm in one CLI; presets; kube-get; interactive menu (`poco -i`); `poco status`; matrix effect; before_docker_script; security (GitPython, pip-audit).
## Licence
[MIT](http://opensource.org/licenses/MIT)
Copyright (c) 2017-present, [Shiwaforce.com](https://www.shiwaforce.com/en/)