1
0
Fork 0
mirror of https://github.com/yavook/kiwi-scp.git synced 2024-11-23 21:23:00 +00:00
kiwi-scp/README.md
2022-02-22 11:19:12 +01:00

210 lines
6.4 KiB
Markdown

# kiwi-scp
[![Build Status](https://github.drone.yavook.de/api/badges/ldericher/kiwi-scp/status.svg)](https://github.drone.yavook.de/ldericher/kiwi-scp)
> `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](./example)
- Look at the output of `kiwi --help`
- Start building your own instances
## Installation
A convenience installer is available as [install.sh](./dist/install.sh) in the `dist` directory.
You can `curl | sh` it using the following one-liner.
```shell script
curl --proto '=https' --tlsv1.2 -sSf 'https://raw.githubusercontent.com/ldericher/kiwi-scp/master/dist/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` at the end instead for system-wide installation.
You should then be able to run `kiwi list --show` and see the default configuration file.
This installs the latest version of the kiwi-scp package and sets it up for you.
### Adjusting environment for `kiwi`
The `kiwi` executable depends on [Python](https://www.python.org/) 3.6.1 (or later) and
[less](http://www.greenwoodsoftware.com/less/) being in your `$PATH`.
In some cases, notably when using a multi-version system such as
[CentOS SCL](https://wiki.centos.org/AdditionalResources/Repositories/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:
```shell script
#!/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` and follow its directions to create a `kiwi.yml` for your instance 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, persistent files are to be kept in a "service data storage", by default the directory `/var/local/kiwi`.
In your `docker-compose.yml` files, you can refer to that directory as **${KIWI_INSTANCE}**.
Start the current kiwi-scp instance using `kiwi up`, or stop it using `kiwi down`.
This also manages 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 **${KIWI_PROJECT}**.
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:
```yaml
networks:
- default
- kiwi_hub
```
#### The `KIWI_CONFIG`
Sometimes, it's convenient to re-use configuration files across projects.
For this use case, create a directory named `config` in your instance.
In your `docker-compose.yml` files, you can refer to that directory as **${KIWI_CONFIG}**.
#### `kiwi.yml` options
##### `version`
Version of kiwi-scp to use for this instance.
Default: Version of [`master` branch](https://github.com/ldericher/kiwi-scp/tree/master).
##### `shells`
Sequence of additionally preferable shell executables when entering service containers.
Default: `- /bin/bash`
Example:
```yaml
runtime:
shells:
- /bin/zsh
- /bin/fish
```
##### `projects`
Sequence of project definitions in this instance.
###### Project definition
Defining a project in this instance. Any subdirectory with a `docker-compose.yml` should be considered a project. The directory name is equivalent to the project name.
Format[^1]: Mapping using the keys `name` (required), `enabled` and `override_storage`
Example:
```yaml
- name: "hello_world"
enabled: true
```
##### `environment`
Custom variables available in projects' `docker-compose.yml` files.
Format[^1]: Mapping of `KEY: "value"` pairs
Example:
```yaml
environment:
HELLO: "World"
FOO: "Bar"
```
##### `storage`
Configuration for the service data storage.
Format: Mapping using the key `directory`
Example:
```yaml
storage:
directory: "/var/local/kiwi"
```
###### `storage:directory`
Path to the local service data directory, the only currently supported service data storage.
Available as **${KIWI_INSTANCE}** in projects.
Default: `"/var/local/kiwi"`
##### `network`
Configuration for the internal `kiwi_hub` network.
Format: Mapping using the keys `name` and `cidr`
Example:
```yaml
network:
name: "kiwi_hub"
cidr: "10.22.46.0/24"
```
###### `network:name`
Configuration for the internal `kiwi_hub` network.
Default: `"kiwi_hub"`
###### `network:cidr`
[CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#IPv4_CIDR_blocks) for the subnet of the internal `kiwi_hub` network.
Default: `"10.22.46.0/24"`
<font size="5">**For everything else, look at `kiwi --help`**
**Happy kiwi-ing!**</font>
[^1]: This is the officially correct format. For enabling varying conventions, there are multiple accepted formats. Start trying and check with `kiwi list --show` -- if it makes sense, it will likely just work.