Add document for the execution script

README.md

@@ -15,154 +15,104 @@
   <a href="https://github.com/tungbq/devops-toolkit/stargazers"><img alt="GitHub Repo stars" src="https://img.shields.io/github/stars/tungbq/devops-toolkit"/></a>
 </p>
 
-## Key features
+## Key Features
 
-- **Pre-installed Tools**: Includes a variety of essential tools such as git, python, ansible, terraform, kubectl, helm, awscli, azurecli, etc.
-- **Continuous Integration**: Utilizes full CI/CD for deployment to Docker Hub using GitHub Actions.
-- **Documentation**: Provides detailed documentation for each tool included.
-- **Regular Updates**: Weekly checks and updates for core tools ensure the toolkit's reliability and security.
-- **Sample code**: Includes sample code demonstrating the usage of various tools available in the toolkit.
-- **Support for Build Variants**: Enables users to customize the toolkit by building it with their preferred versions of each tool.
-- **Support Configuration Reusable**: Mounts a config folder on the host to the container. This allows reusing configurations in the container, like AWS and Azure login sessions, ...
+- **Comprehensive Toolset**: Pre-installed with tools like Git, Python, Ansible, Terraform, kubectl, Helm, AWS CLI, Azure CLI, and more.
+- **Easy Integration**: Use it directly or customize it with your preferred versions.
+- **Efficient Updates**: Weekly updates ensure the latest versions and security patches.
+- **Configuration Reusability**: Mounts host config folders for seamless reuse across sessions.
 
-## Prerequisites 🔓
+## Getting Started
 
-Before you begin, ensure that you have [Docker](https://docs.docker.com/engine/install/) installed. It's also helpful to have a basic understanding of Docker concepts.
+Use the provided execution script simplifies setup, execution and managing DevOps Toolkit.
 
-## Versioning 🔖
-
-Below is the versioning strategy for the repository and DockerHub:
-
-- Tagging format:
-  - Repository: `vX.Y.Z`, for example: `v1.2.3`
-  - DockerHub: `X.Y.Z`, for example: `1.2.3`. (Usage: `docker pull tungbq/devops-toolkit:1.2.3`)
-- Tagging description:
-  - Specific tag (e.g., `0.1.0`, `0.2.3`): Contains the latest tooling version and repository features at the time this repository is tagged.
-  - In addition to that, we offer the latest tag on DockerHub (`latest`): Contains the latest tooling version and repository features inside the toolkit, which will be built and updated on a weekly basis.
-
-_NOTE_: In the following section, we use the latest tag in the documentation, but you can specify your desired tag based on your needs.
-
-## Use devops-toolkit with execution script
-
-The `devops-toolkit` script in this repo helps you use the devops-toolkit in the fast and efficience way.
-
-### Install
+### 1. Install
 
 ```bash
 curl -o devops-toolkit https://raw.githubusercontent.com/tungbq/devops-toolkit/main/devops-toolkit
 chmod +x devops-toolkit
 sudo mv devops-toolkit /usr/local/bin/
 ```
 
-### Run
+### 2. Run
 
-Navigate to your working directory then run the devops-toolkit
+- Initialize the docker image, container and configuration directory:
 
 ```bash
-# See available commands or get help
-devops-toolkit help
-# Start a new container
-devops-toolkit run
-# Start a new container and run a command
-devops-toolkit run ls -la
-# Execute the shell
-devops-toolkit shell
-# Update the devops-toolkit
-devops-toolkit update
-# Remove container
-devops-toolkit cleanup
+devops-toolkit init
+# Run 'devops-toolkit init vX.Y.Z' if you want to use specific version. E.g: devops-toolkit init 1.0.2
 ```
 
-## Use devops-toolkit with docker command
-
-In this option you use your own docker command to start and run the devops-toolkit.
-
-### Quick start 🔥
-
-- Use latest tag
+- Start a shell in new container:
 
-  ```bash
-  mkdir -p ~/.dtc
-  docker run --network host -it --rm -v ~/.dtc:/dtc tungbq/devops-toolkit:latest
-  ```
-
-- Use specific tag
+```bash
+devops-toolkit run
+```
 
-  ```bash
-  docker run --network host -it --rm -v ~/.dtc:/dtc tungbq/devops-toolkit:0.1.0
-  ```
+- Execute a command in the container:
 
-- _NOTE_
-  - You can replace `~/.dtc` with any desired folder path on your VM.
-  - Remove the `-v ~/.dtc:/dtc` option if you do not wish to store configurations on the host (not recommended for configuration reuse).
+```bash
+devops-toolkit run ls -la
+```
 
-### Demo 📺
+- Access the shell:
 
 ```bash
-docker run --network host --rm -v ~/.dtc:/dtc tungbq/devops-toolkit:latest samples/run_sample.sh
+devops-toolkit shell
 ```
 
-Check out the full sample and instruction at [**samples**](./samples/)
+- For more commands, use `devops-toolkit help`.
 
-## Getting started 📖
+## Use DevOps Toolkit with docker command directly
 
-### Pull the official image from Docker Hub
+Follow this instruction if you would like to use from docker command without the help of the execution script
 
-DockerHub image: [**tungbq/devops-toolkit:latest**](https://hub.docker.com/r/tungbq/devops-toolkit)
+### 1. Quick Start
 
 ```bash
-docker pull tungbq/devops-toolkit:latest
+mkdir -p $HOME/.dtc # Skip this step if you already created the configuration folder before
+docker run --network host -it --rm -v $HOME/.dtc:/dtc tungbq/devops-toolkit:latest
 ```
 
-### Build your own image
-
-Skip this step if you use the image from DockerHub
-
-- If you prefer to build your own image from the source code, refer to the [**build_toolkit_image**](./docs/build/build_toolkit_image.md) instructions.
-- We can customize the toolkit by building it with our preferred versions of each tool.
-
-### Start and explore the toolkit container
+### 2. Advanced Run Options
 
-Once you have the image ready, you can start using the toolkit with the following commands
+```bash
+docker run -it --name devops-toolkit-ctn \
+    --volume "$PWD:$PWD" \
+    --volume "$HOME/.dtc:/dtc" \
+    --volume "$HOME/.ssh:/root/.ssh" \
+    --workdir "$PWD" \
+    --network host \
+    tungbq/devops-toolkit:latest
+
+# Adjust the docker run command base on your use cases
+```
 
-- Start devops-toolkit container
+### 3. Note
 
-  ```bash
-  docker run --network host -it --rm -v ~/.dtc:/dtc tungbq/devops-toolkit:latest
-  ```
+- You can replace `$HOME/.dtc` with any desired folder path on your VM.
+- Remove the `-v $HOME/.dtc:/dtc` option if you do not wish to store configurations on the host (not recommended for configuration reuse).
 
-- Now we are in the docker container terminal, let's explore it
+## Versioning
 
-  ```bash
-  root@docker-desktop:~# python3 --version
-  Python 3.12.2
+We use the following versioning scheme:
 
-  root@docker-desktop:~# terraform --version
-  Terraform v1.7.5
-  on linux_amd64
+- **Repository Tags**: `vX.Y.Z` (e.g., `v1.2.3`)
+- **Docker Tags**: `X.Y.Z` or `latest` for the most recent version.
 
-  root@docker-desktop:~# kubectl version
-  Client Version: v1.29.3
-  Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
+You can pull specific versions from Docker Hub using:
 
-  root@docker-desktop:~# aws configure
-  root@docker-desktop:~# az login --use-device-code
+```bash
+docker pull tungbq/devops-toolkit:1.2.3
+docker pull tungbq/devops-toolkit:latest
+```
 
-  # ... more command as your needed
-  ```
+For more details on versioning, check the [release notes](https://github.com/tungbq/devops-toolkit/releases).
 
 ## User Guide 📖
 
 Explore the comprehensive guide below to gain insight into the detailed utilization of every tool within the toolkit.
 
-- Prepare configuration folder on the Host (Skip this step if you do not intend to reuse configurations.)
-
-  ```bash
-  mkdir ~/.dtc
-  ```
-
-  _NOTE:_ We are using `~/.dtc` to store toolkit configurations, but you can choose any folder name on the host.
-
 - For detailed instructions on using specific tools, refer to: [**DevOps toolkit specific tool user guide**](./docs/usage/README.md)
 - For instructions on common run modes, visit [**DevOps toolkit common run mode**](./docs/usage/run_mode.md)
 

devops-toolkit

@@ -180,6 +180,7 @@ shell_access() {
 usage() {
     log $BLUE "Usage: $0 [command] [options]"
     echo "Commands:"
+    echo "  init [version]: Initialize the container and configuration directory. If version is omitted, initializes with the latest image."
     echo "  run [command]: Start a new container and run a command"
     echo "  exec [command]: Execute a command in an existing container"
     echo "  cleanup: Remove the container"
@@ -191,7 +192,35 @@ usage() {
     echo "  shell: Get a shell inside the running container"
 }
 
+init() {
+    local version="$1"
+    local image="${DOCKER_IMAGE%:*}:${version:-latest}"
+
+    # Check if the directory exists
+    if [ ! -d "$CONFIG_MOUNT_PATH" ]; then
+        # If the directory doesn't exist, create it
+        mkdir -p "$CONFIG_MOUNT_PATH"
+        echo "Config path $DICONFIG_MOUNT_PATHR created."
+    else
+        echo "Config path $CONFIG_MOUNT_PATH already exists."
+    fi
+
+    if docker inspect --type=container "$CONTAINER_NAME" > /dev/null 2>&1; then
+        log $YELLOW "Container $CONTAINER_NAME already exists. Skipping initialization."
+        log $YELLOW "Run 'devops-toolkit cleanup' then init again if you want to re-init!"
+    else
+        log $BLUE "Initializing container with image $image..."
+        pull_image "$image"
+        start_container "$image"
+        log $GREEN "Initialization complete."
+    fi
+}
+
 case "$1" in
+    init)
+        shift
+        init "$1"
+        ;;
     run)
         RUN_MODE="run"
         shift
@@ -237,4 +266,4 @@ case "$1" in
         usage
         exit 1
         ;;
-esac
+esac