From 98caa876cea597e6f926321c93816893c1795131 Mon Sep 17 00:00:00 2001 From: ldericher <40151420+ldericher@users.noreply.github.com> Date: Tue, 22 Feb 2022 00:02:28 +0100 Subject: [PATCH] README --- README.md | 79 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 52 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index a4da112..59bcab7 100644 --- a/README.md +++ b/README.md @@ -18,24 +18,24 @@ The simple tool for managing container servers ## 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. ```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. 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. -This downloads the latest version of the main kiwi-scp executable and sets it up for you. +You should now 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 (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`. 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". 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}**. +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 **${KIWI_INSTANCE}**. 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. @@ -88,7 +88,7 @@ Before enabling or starting, consider editing the new project's `docker-compose. Finally, enable it with `kiwi enable `. 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 `. @@ -100,7 +100,7 @@ kiwi-scp extends the logical bounds of `docker-compose` to handling multiple pro #### 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. Be aware, services only connected to the kiwi_hub can't use a port mapping! 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. -For this use case, create a directory named `conf` in a project. -Those will all be combined into a directory available as **${CONFIGDIR}** in your `docker-compose.yml` files. +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: Latest version. +Version of kiwi-scp to use for this instance. -##### `runtime:storage` -Path of the service data directory, available as **${TARGETROOT}** in projects. -Default: `/var/kiwi` +Default: Version of [`master` branch](https://github.com/ldericher/kiwi-scp/tree/master). + +##### `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` Example: @@ -141,17 +139,44 @@ runtime: - /bin/fish ``` -##### `runtime:env` -Associative array of custom variables available in projects' `docker-compose.yml` files. -Default: `null` +##### `projects` +Sequence of project definitions in this instance. + +###### 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: ```yaml -runtime: - env: - HELLO: "World" - FOO: "Bar" +- name: "hello_world" + enabled: true ``` +##### `environment` +Custom variables available in projects' `docker-compose.yml` files. + +Format: 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` + +###### `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` #### Happy kiwi-ing!