From 89273ec6886c8ade19bf4ca715e752cdefc7861c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Planchat?= Date: Thu, 18 Mar 2021 12:33:41 +0100 Subject: [PATCH] Updated documentation about usage --- README.md | 12 +++++-- bin/build | 2 +- docs/installation.md | 2 +- docs/usage.md | 78 ++++++++++++++++++++++++++++++++++++++++---- 4 files changed, 83 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 55db7db..6b847b8 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,19 @@ and [Marello](https://www.marello.com/) development. > but to provide an environment based on Docker as identical as > possible to OroCloud and MarelloCloud on a personal computer. +What to expect from this tool? +--- + +This tool has to be used in addition ot the installation instructions +from Oro-family applications. It will build an execution environment +based on Docker and Docker Compose for your existing projects or can +be added to a brand-new project. + Documentation --- -* [Installation](docs/installation.md) -* [Usage](docs/usage.md) +* [Installation of the tool](docs/installation.md) +* [Usage in your Oro-family projects](docs/usage.md) * [Frequently Asked Questions](docs/faq.md) * [Docker for Mac optimizations](docs/docker-for-mac-optimizations.md) * [Versions sunsetting policy, experimental and discontinued support](docs/sunsetting-policy.md) diff --git a/bin/build b/bin/build index a88169a..0ff6e17 100755 --- a/bin/build +++ b/bin/build @@ -10,4 +10,4 @@ $EXEC composer install --dev --optimize-autoloader \ && $EXEC box build \ && docker build -t kiboko/kloud:latest $DIRECTORY/build/ \ && docker push kiboko/kloud \ - && $EXEC composer install --dev --optimize-autoloader \ No newline at end of file + && $EXEC composer install --dev --optimize-autoloader diff --git a/docs/installation.md b/docs/installation.md index 632c99f..31513e3 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,4 +1,4 @@ -Installation +Installation of the tool === Installing system-wide the `kloud` command diff --git a/docs/usage.md b/docs/usage.md index e88c021..cf621f8 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,6 +1,12 @@ -Usage +Usage in your Oro-family projects === +What do you need before starting? +--- + +* Optionally an existing directory with an Oro-family application sources. +* the `kloud` command available in one of the ways described in the [Installation](installation.md) instructions + Initialize your stack --- @@ -13,8 +19,7 @@ Once the command is finished, you will have a file named `.env.dist` containing This file has to be renamed to `.env` in order to be used by Docker Compose. The command have set some ports values for all services, you may wish to change them depending on your environment. -#Available command line options ---- +### Additional command line options * Database engine selection * `--mysql`: Set up the application to use MySQL. @@ -43,8 +48,9 @@ The command have set some ports values for all services, you may wish to change Upgrade your stack --- -In an existing project, you can upgrade the docker stack configuration. automagically. -You can invoke the following command that will guess what services needs to be updated and in case of differences, a wizard will ask you what you wish to keep or delete: +In an existing project, you can upgrade the docker stack configuration automagically. +You can invoke the following command that will guess what services needs to be updated +and in case of differences, a wizard will ask you what you wish to keep or delete: `kloud stack:upgrade` @@ -53,11 +59,15 @@ You can invoke the following command that will guess what services needs to be u Build the required images --- -If you need to build the images you need in a stack, you can execute the following command: +In hte case you are using a [sunsetting or experimental version combination](sunsetting-policy.md), +you will need to build yourself the images. Any other version will be auomatically built and pushed +to Docker Hub, without the need for you to build them yourself. + +Build all necessary images, you need to execute the following command: `kloud image:build` -To enable experimental images, you will need to add option `--with-experimental`. +In case you are using experimental images, you will need to add the additional option `--with-experimental`. Test the required images --- @@ -65,3 +75,57 @@ Test the required images If you need to test if the images you are using are following every constraint you would expect: `kloud image:test` + +Environment commands +--- + +After `kloud stack:init`, you can use the environment commands to do various actions on your local +machine or a remote server. + +### Initialize an environment + +* `kloud environment:init`: Initialize the environment file in local workspace. + +### Environment variables + +* `kloud environment:variable:add`: Add an environment variable. +* `kloud environment:variable:unset`: Unset an environment variable value. +* `kloud environment:variable:get`: Print an environment variable value. +* `kloud environment:variable:set`: Change an environment variable value. +* `kloud environment:variable:list`: Print the list of environment variables and their value. + +### Deploy environment + +* `kloud environment:deploy`: Deploy the application to a remote server using rsync and initialize docker services. + +### Destroy the environment + +* `kloud environment:destroy`: Destroy the docker infrastructure with associated volumes and remove remote directory. + +### Start the environment's services + +* `kloud environment:start`: Start docker services on the remote server. + +### Stop the environment's services + +* `kloud environment:stop`: Stop docker services on the remote server. + +### Synchronize your local sources with the remote + +* `kloud environment:rsync`: Synchronize remote directory according to local directory. + +### Clear the Symfony cache + +* `kloud environment:cache:clear`: SClear cache and restart FPM service. + +### Dump the database from your environment + +* `kloud environment:database:dump`: Dump the database in the current state. + +### Load a database dump into your environment + +* `kloud environment:database:load`: Load a database dump. + +### Open a shell in the environment + +* `kloud environment:shell`: Start a shell session for a service.