jmm/kiwi-scp
2
0
Fork 0
Code Projects Wiki Activity
kiwi - simple, consistent, powerful
221 commits 4 branches 11 tags 518 KiB
Python 98.1%
HTML 1.4%
Dockerfile 0.5%
Find a file
ldericher 5b9ed4259e KiwiCTX -> Instance, "kiwi init -o"
2021-10-25 13:29:12 +02:00
.idea "kiwi show" -> "kiwi list" 2021-10-22 17:52:13 +02:00
dist errata 2021-10-13 02:39:04 +02:00
example remove need for kiwi_default.yml 2021-10-12 19:25:51 +02:00
kiwi_scp KiwiCTX -> Instance, "kiwi init -o" 2021-10-25 13:29:12 +02:00
tests pytest Instance 2021-10-25 13:00:11 +02:00
.dockerignore dist scripts, search upwards for kiwi instance 2021-10-11 02:58:20 +02:00
.drone.yml install-poetry script 2021-10-14 19:51:52 +02:00
.gitignore switch to pipenv 2020-08-06 11:10:23 +02:00
Dockerfile CI pytests 2021-10-14 19:37:41 +02:00
LICENSE Format, license, distribution script 2020-08-21 00:04:26 +02:00
poetry.lock more well-defined CLI with custom mutable context 2021-10-20 10:54:41 +02:00
pyproject.toml more well-defined CLI with custom mutable context 2021-10-20 10:54:41 +02:00
README.md README changes 2021-09-30 17:51:35 +02:00

README.md

kiwi-scp

Build Status

kiwi - simple, consistent, powerful

The simple tool for managing container servers

Quick start

  • Learn to use docker with docker-compose
  • Install kiwi-scp
  • Look at the example instance
  • Look at the output of kiwi --help
  • Start building your own instances

Installation

A convenience installer is available as install.sh in this directory. You can curl | sh it using the following one-liner.

curl --proto '=https' --tlsv1.2 -sSf 'https://raw.githubusercontent.com/ldericher/kiwi-scp/master/install.sh' | sh

The installer downloads the kiwi launcher script and installs it to a location of your choice. Please consider installing into a directory inside your $PATH. Run in a root shell or use sudo sh instead for system-wide installation.

You should now be able to run kiwi init --show and see the default configuration file. This downloads the latest version of the main kiwi-scp executable and sets it up for you.

Adjusting environment for kiwi

The kiwi executable depends on Python 3.6 (or later) and less being in your $PATH.

In some cases, notably when using a multi-version system such as CentOS SCL, not all of these are in your $PATH at login time.

In those cases, you can simply create a .kiwi_profile file in your home directory. It will be sourced every time you use the kiwi command. For the aforementioned case where you installed centos-release-scl and rh-python36, your ~/.kiwi_profile should contain:

#!/bin/sh

. /opt/rh/rh-python36/enable

Get started

Create a kiwi-scp instance

Any directory is implicitly a valid kiwi-scp instance using the default configuration. To prevent surprises however, you should run kiwi init in an empty directory and follow its directions to create a kiwi.yml before using kiwi more.

Concept

A kiwi-scp instance is a directory containing a bunch of static configuration files. "Static" there as in "those don't change during normal service operation". These files could be anything from actual .conf files to entire html-web-roots.

Non-static, but persistent files are to be kept in a "service data directory", by default /var/kiwi. In your docker-compose.yml files, you can refer to that directory as ${TARGETROOT}.

Start the current directory as a kiwi-scp instance using kiwi up, or stop it using kiwi down. This also creates kiwi's internal hub network, which you can use as kiwi_hub in your docker-compose.yml files.

Projects

A kiwi-scp instance usually contains several projects. A project is a collection of dependent or at least logically connected services, described by a docker-compose.yml. A well-known example would be webserver + php + database.

To create a project, use the kiwi new <project-name> command. By default, this creates a new disabled project. Before enabling or starting, consider editing the new project's docker-compose.yml file to your liking. Finally, enable it with kiwi enable <project-name>. You can also create, enable or (analogously) disable multiple projects in a single command.

Each project will have its own place in the service data directory, which you can refer to as ${TARGETDIR}.

Finally, start a project using kiwi up <project-name>.

Advanced kiwi usage

kiwi-scp extends the logical bounds of docker-compose to handling multiple projects.

The kiwi_hub

With kiwi-scp, you get the internal kiwi_hub network for free. It allows for network communication between services in different projects. Be aware, services only connected to the kiwi_hub can't use a port mapping! In most cases, you will want to use this:

networks:
  - default
  - kiwi_hub

The CONFDIR

Sometimes, it's convenient to re-use configuration files across projects. For this use case, create a directory named conf in a project. Those will all be combined into a directory available as ${CONFDIR} in your docker-compose.yml files.

kiwi.yml options

version

Version of kiwi-scp to use for this instance.
Default: Latest version.

runtime:storage

Path of the service data directory, available as ${TARGETROOT} in projects.
Default: /var/kiwi

runtime:shells

List of additionally preferable shell executables when entering service containers.
Default: - /bin/bash
Example:

runtime:
  shells:
    - /bin/zsh
    - /bin/fish
runtime:env

Associative array of custom variables available in projects' docker-compose.yml files.
Default: null
Example:

runtime:
  env:
    HELLO: "World"
    FOO: "Bar"

For everything else, look at kiwi --help

Happy kiwi-ing!