jmm/kiwi-scp
2
0
Fork 0
Code Projects Wiki Activity

README

Browse source
This commit is contained in:
Jörn-Michael Miehe 2022-02-22 00:02:28 +01:00
parent d4eb91dae8
commit 98caa876ce
1 changed files with 52 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

73
README.md
View file

@ -18,24 +18,24 @@ The simple tool for managing container servers
## Installation ## Installation
A convenience installer is available as [install.sh](./install.sh) in this directory. 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. You can `curl | sh` it using the following one-liner.
```shell script ```shell script
curl --proto '=https' --tlsv1.2 -sSf 'https://raw.githubusercontent.com/ldericher/kiwi-scp/master/install.sh' | sh 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. 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`. Please consider installing into a directory inside your `$PATH`.
Run in a root shell or use `sudo sh` instead for system-wide installation. Run in a root shell or use `sudo sh` at the end instead for system-wide installation.
You should now be able to run `kiwi init --show` and see the default configuration file. You should now be able to run `kiwi list --show` and see the default configuration file.
This downloads the latest version of the main kiwi-scp executable and sets it up for you. This installs the latest version of the kiwi-scp package and sets it up for you.
### Adjusting environment for `kiwi` ### Adjusting environment for `kiwi`
The `kiwi` executable depends on [Python](https://www.python.org/) 3.6 (or later) and 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`. [less](http://www.greenwoodsoftware.com/less/) being in your `$PATH`.
In some cases, notably when using a multi-version system such as In some cases, notably when using a multi-version system such as
@ -69,8 +69,8 @@ A kiwi-scp instance is a directory containing a bunch of static configuration fi
"Static" there as in "those don't change during normal service operation". "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. 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`. Non-static, but persistent files are to be kept in a "service data directory", by default `/var/local/kiwi`.
In your `docker-compose.yml` files, you can refer to that directory as **${TARGETROOT}**. In your `docker-compose.yml` files, you can refer to that directory as **${KIWI_INSTANCE}**.
Start the current directory as a kiwi-scp instance using `kiwi up`, or stop it using `kiwi down`. 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. This also creates kiwi's internal hub network, which you can use as **kiwi_hub** in your `docker-compose.yml` files.
@ -88,7 +88,7 @@ Before enabling or starting, consider editing the new project's `docker-compose.
Finally, enable it with `kiwi enable <project-name>`. Finally, enable it with `kiwi enable <project-name>`.
You can also create, enable or (analogously) disable multiple projects in a single command. 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}**. 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>`. Finally, start a project using `kiwi up <project-name>`.
@ -100,7 +100,7 @@ kiwi-scp extends the logical bounds of `docker-compose` to handling multiple pro
#### The `kiwi_hub` #### The `kiwi_hub`
With kiwi-scp, you get the internal kiwi_hub network for free. With kiwi-scp, you get the internal `kiwi_hub` network for free.
It allows for network communication between services in different projects. 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! Be aware, services only connected to the kiwi_hub can't use a port mapping!
In most cases, you will want to use this: In most cases, you will want to use this:
@ -112,25 +112,23 @@ networks:
``` ```
#### The `CONFIGDIR` #### The `KIWI_CONFIG`
Sometimes, it's convenient to re-use configuration files across projects. Sometimes, it's convenient to re-use configuration files across projects.
For this use case, create a directory named `conf` in a project. For this use case, create a directory named `config` in your instance.
Those will all be combined into a directory available as **${CONFIGDIR}** in your `docker-compose.yml` files. In your `docker-compose.yml` files, you can refer to that directory as **${KIWI_CONFIG}**.
#### `kiwi.yml` options #### `kiwi.yml` options
##### `version` ##### `version`
Version of kiwi-scp to use for this instance. Version of kiwi-scp to use for this instance.
Default: Latest version.
##### `runtime:storage` Default: Version of [`master` branch](https://github.com/ldericher/kiwi-scp/tree/master).
Path of the service data directory, available as **${TARGETROOT}** in projects.
Default: `/var/kiwi` ##### `shells`
Sequence of additionally preferable shell executables when entering service containers.
##### `runtime:shells`
List of additionally preferable shell executables when entering service containers.
Default: `- /bin/bash` Default: `- /bin/bash`
Example: Example:
@ -141,17 +139,44 @@ runtime:
- /bin/fish - /bin/fish
``` ```
##### `runtime:env` ##### `projects`
Associative array of custom variables available in projects' `docker-compose.yml` files. Sequence of project definitions in this instance.
Default: `null`
###### Project definition
Defining a project in this instance. Any subdirectory with a `docker-compose.yml` might be considered a project.
Format: Mapping using the keys `name`, `enabled` and `override_storage`
Example: Example:
```yaml ```yaml
runtime: - name: "hello_world"
env: enabled: true
```
##### `environment`
Custom variables available in projects' `docker-compose.yml` files.
Format: Mapping of `KEY: "value"` pairs
Example:
```yaml
environment:
HELLO: "World" HELLO: "World"
FOO: "Bar" FOO: "Bar"
``` ```
##### `storage`
Configuration for the service data storage.
Format: Mapping using the key `directory`
###### `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`
#### For everything else, look at `kiwi --help` #### For everything else, look at `kiwi --help`
#### Happy kiwi-ing! #### Happy kiwi-ing!