Merge pull request #195 from noqdev/task/docs-20230304

Doc Fixes - 03/04/2023

.github/workflows/build-container.yml

@@ -57,12 +57,12 @@ jobs:
         id: build-container
         run: |
           docker logout ghcr.io
-          aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/o4z3c2v2
+          aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/iambic
           . build-env/bin/activate && make build_docker
           make trivy_scan
           make trivy_sbom
           make upload_docker
-          docker logout public.ecr.aws/o4z3c2v2
+          docker logout public.ecr.aws/iambic
           docker buildx prune --filter=until=96h -f
       - uses: actions/upload-artifact@v3
         with:

Dockerfile

@@ -1,4 +1,4 @@
-FROM public.ecr.aws/o4z3c2v2/iambic_container_base:1.0
+FROM public.ecr.aws/iambic/iambic_container_base:1.0
 
 ARG FUNCTION_DIR="/app"
 WORKDIR ${FUNCTION_DIR}

Makefile

@@ -1,13 +1,13 @@
 BUILD_VERSION := $(shell python build_utils/tag_and_build_container.py print-current-version)
-IAMBIC_PUBLIC_ECR_ALIAS := o4z3c2v2
+IAMBIC_PUBLIC_ECR_ALIAS := iambic
 
 .PHONY: prepare_for_dist
 prepare_for_dist:
 	rm -f proposed_changes.yaml # especially important if this is run locally
 
 .PHONY: auth_to_ecr
 auth_to_ecr:
-	bash -c "AWS_PROFILE=iambic_open_source/iambic_image_builder aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/o4z3c2v2"
+	bash -c "AWS_PROFILE=iambic_open_source/iambic_image_builder aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws/${IAMBIC_PUBLIC_ECR_ALIAS}"
 
 docker_buildx := docker buildx build \
 	--platform=linux/amd64 \

deployment/github_app/vars.tf

@@ -23,7 +23,7 @@ variable "iambic_public_repo_url" {
   type        = string
   description = "Iambic Public Repo URL"
 
-  default = "public.ecr.aws/o4z3c2v2"
+  default = "public.ecr.aws/iambic"
 }
 
 variable "iambic_image_name" {

docker-compose-cicd.yaml

@@ -3,7 +3,7 @@ services:
   iambic-cicd:
     # NOTE: This compose file loads the image from ECR, not from what you are running
     # locally.
-    image: public.ecr.aws/o4z3c2v2/iambic:latest
+    image: public.ecr.aws/iambic/iambic:latest
     environment:
       - IAMBIC_CONFIG=arn:aws:secretsmanager:us-west-2:759357822767:secret:dev/iambic-full
       - IAMBIC_CONFIG_ASSUME_ROLE=arn:aws:iam::759357822767:role/IambicSpokeRole

docs/web/docs/1-getting_started/1-install_and_configure.mdx

@@ -18,6 +18,8 @@ git init
 cat <<EOF > .gitignore
 **/secrets.yaml
 proposed_changes.yaml
+env/
+venv/
 EOF
 ```
 
@@ -43,9 +45,9 @@ curl https://iambic.org/scripts/install.sh | bash
 
 Note: we require sudo because we are installing the script `iambic` into `/usr/local/bin/` of your file system to ensure it is in your path.
 
-For detailed Docker setup instructions, please visit the [Install via Docker](/technical_reference/installation/install_via_docker) guide.
+For detailed Docker setup instructions, please visit the [Install via Docker](/technical_reference/installation/install_iambic_via_docker) guide.
 
-You can also [install the wheel](/technical_reference/installation/install_via_the_wheel), or [install IAMbic locally](/technical_reference/installation/download_the_repo). <!-- #TODO why would I want these options? We need one liner each about what benefit they offer or about what circumstance might make me choose them. -->
+You can also [install the wheel](/technical_reference/installation/install_iambic_via_python_wheel), or [install IAMbic locally](/technical_reference/installation/install_iambic_via_the_repo). <!-- #TODO why would I want these options? We need one liner each about what benefit they offer or about what circumstance might make me choose them. -->
 
 ### Configuring IAMbic
 

docs/web/docs/1-getting_started/2-aws.mdx

@@ -49,7 +49,6 @@ After configuring IAMbic, you should see your accounts referenced in your reposi
 Feel free to move this file around in the repository. When IAMbic is run, it will look for the configuration
 by referencing the `template_type` and it expects to find a template_type of `NOQ::Core::Config`.
 
-
 ### 2. Import AWS Resources
 
 After configuring IAMbic for AWS, run the `iambic import` command from the repository you created.

docs/web/docs/2-how_to_guides/1-configure_iambic_with_wizard.mdx

@@ -9,9 +9,9 @@ toc_max_heading_level: 5
 The easiest way to get started with IAMbic is to run the configuration wizard. The wizard will generate a configuration file that matches your environment by asking specific questions in a Q&A style.
 
 Start the wizard by first using one of these methods
-* [installing the `docker` container](/technical_reference/installation/install_via_docker)
-* [installing the iambic wheel](/technical_reference/installation/install_via_the_wheel) into the virtual environment of your choice
-* [installing the IAMbic project from source](/technical_reference/installation/download_the_repo).
+* [installing the `docker` container](/technical_reference/installation/install_iambic_via_docker)
+* [installing the iambic wheel](/technical_reference/installation/install_iambic_via_python_wheel) into the virtual environment of your choice
+* [installing the IAMbic project from source](/technical_reference/installation/install_iambic_via_the_repo).
 
 ### Usage
 

docs/web/docs/3-technical_reference/installation/install_via_docker.mdx → docs/web/docs/3-technical_reference/installation/1_install_iambic_via_docker.mdx

@@ -10,11 +10,7 @@ toc_max_heading_level: 5
 
 Before you begin, you'll need to have the following tools installed on your system:
 
-* Docker
-
-If you don't have these tools installed, follow the instructions below:
-
-* [Install Docker](https://docs.docker.com/get-docker/)
+* Docker ([Install Docker](https://docs.docker.com/get-docker/))
 
 ### Steps
 
@@ -24,38 +20,38 @@ To run the docker container locally, you can use the docker command:
 
 Basic run:
 
-    docker run public.ecr.aws/s2p9s3r8/iambic:latest <command>
+    docker run public.ecr.aws/iambic/iambic:latest <command>
 
 We recommend mounting a local volume for the templates that are imported:
 
-    docker run -it -v <local_dir>:/templates public.ecr.aws/s2p9s3r8/iambic:latest <command>
+    docker run -it -v <local_dir>:/templates public.ecr.aws/iambic/iambic:latest <command>
 
 If you want to run IAMbic from the current directory, you can use a BASH trick to get the current working directory:
 
-    docker run -it -v ${pwd}:/templates public.ecr.aws/s2p9s3r8/iambic:latest <command>
+    docker run -it -v ${pwd}:/templates public.ecr.aws/iambic/iambic:latest <command>
 
 It is best to run as the current user to make sure that templates written to disk are written in the user and group currently active on the host:
 
-    docker run -it -u $(id -u):$(id -g) -v ${pwd}:/templates public.ecr.aws/s2p9s3r8/iambic:latest <command>
+    docker run -it -u $(id -u):$(id -g) -v ${pwd}:/templates public.ecr.aws/iambic/iambic:latest <command>
 
 Optionally you can store the volume in your system's docker context - be forwarned that the docker context could be coerced to delete the volume without warning using a command like `docker system prune` - it is generally best to store templates on your hard drive in a place where the chances of accidental deletion are minimized:
 
-    docker run -it -u $(id -u):$(id -g) -v /templates public.ecr.aws/s2p9s3r8/iambic:latest <command>
+    docker run -it -u $(id -u):$(id -g) -v /templates public.ecr.aws/iambic/iambic:latest <command>
 
 Depending on where your cloud credentials are stored, you may have to mount the relevant directory inside the docker container as well:
 
-    docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v ${pwd}:/templates:Z public.ecr.aws/s2p9s3r8/iambic:latest <command>
+    docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v ${pwd}:/templates:Z public.ecr.aws/iambic/iambic:latest <command>
 
 ### Shortcut
 
 We recommend that you add the following to your ~/.bashrc or ~/.bash_profile:
 
 ```bash
-echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v <local_dir\>:/templates:Z public.ecr.aws/s2p9s3r8/iambic:latest <command>"' >> ~/.bashrc
+echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v <local_dir\>:/templates:Z public.ecr.aws/iambic/iambic:latest <command>"' >> ~/.bashrc
 ```
 
 ```zsh
-echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v <local_dir\>:/templates:Z public.ecr.aws/s2p9s3r8/iambic:latest <command>"' >> ~/.zshrc
+echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e "AWS_PROFILE=${AWS_PROFILE}" -v <local_dir\>:/templates:Z public.ecr.aws/iambic/iambic:latest <command>"' >> ~/.zshrc
 ```
 
 That way you can just execute iambic seamlessly as an application within your system:

docs/web/docs/3-technical_reference/installation/download_the_repo.mdx → docs/web/docs/3-technical_reference/installation/2_install_iambic_via_the_repo.mdx

@@ -29,7 +29,7 @@ You can now make changes to the files in the repository and commit them using Gi
 
 ## Use IAMbic from the local repository
 
-Create a [virtual environment](https://virtualenv.pypa.io/en/latest/user_guide.html) or python environment into which you'd like to install IAMbic. See [install via the wheel](/technical_reference/installation/install_via_the_wheel) methods 1, 2, and 3 for more information on setting up your environment.
+Create a [virtual environment](https://virtualenv.pypa.io/en/latest/user_guide.html) or python environment into which you'd like to install IAMbic. See [install via the wheel](/technical_reference/installation/install_iambic_via_python_wheel) methods 1, 2, and 3 for more information on setting up your environment.
 
 Install poetry: `pip install poetry`.
 

docs/web/docs/3-technical_reference/installation/3_install_iambic_via_python_wheel.mdx

@@ -0,0 +1,54 @@
+---
+title: Install IAMbic via Python Wheel
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+---
+
+## Pre-requisites
+
+* Python 3.10 or later
+
+## Install Python if you have not already
+
+To download IAMbic from PyPI, you will need to ensure that Python is installed on your machine. Here are two methods for installing Python:
+
+### Method 1: Python
+
+1. Go to the [Python Downloads page]( https://www.python.org/downloads) and download and install Python 3.10 or later.
+1. Create a virtual environment and install IAMbic by running the following commands:
+
+```bash
+# Create a directory for your iambic templates if you didn't already create one
+mkdir iambic-templates
+cd iambic-templates
+
+# Create a virtual environment to store iambic and its dependencies
+python -m venv venv
+. venv/bin/activate
+
+# Install IAMbic
+pip install iambic-core
+```
+
+Test by running `iambic --help`
+
+### Method 2: Use pyenv (Recommended for managing multiple versions of Python)
+
+1. Install [pyenv](https://github.com/pyenv/pyenv) by following the instructions on their GitHub page. (`brew install pyenv` on Mac)
+1. Install [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) by following the instructions on their GitHub page. (`brew install pyenv-virtualenv` on Mac)
+1. Create a virtual environment and install IAMbic by running the following commands:
+
+```bash
+# Install the desired version of Python (replace 3.10 with your desired version).
+pyenv install 3.10
+# Set the Python version globally with `pyenv global 3.10` or locally within a folder with `pyenv local 3.10`.
+pyenv local 3.10
+# Create a virtual environment (replace 3.10 and iambic with your desired version and environment name).
+pyenv virtualenv 3.10 iambic
+# Activate the virtual environment
+pyenv activate iambic
+# Install IAMbic
+pip install iambic-core
+```
+
+Test by running `iambic --help`

docs/web/docs/3-technical_reference/using.mdx

@@ -8,9 +8,9 @@ toc_max_heading_level: 5
 
 To use IAMbic, first install IAMbic by following any of these methods:
 
-* [Install via Docker](/technical_reference/installation/install_via_docker) (preferred method)
-* [Install via the Wheel](/technical_reference/installation/install_via_the_wheel)
-* [Download the Repo](/technical_reference/installation/download_the_repo)
+* [Install via Docker](/technical_reference/installation/install_iambic_via_docker) (preferred method)
+* [Install via the Wheel](/technical_reference/installation/install_iambic_via_python_wheel)
+* [Download the Repo](/technical_reference/installation/install_iambic_via_the_repo)
 
 Once IAMbic is installed on your system, you can use it. There are three core IAMbic tasks:
 

install.sh

@@ -34,7 +34,7 @@ fi
 
 echo
 
-ECR_PATH="public.ecr.aws/o4z3c2v2/iambic:latest"
+ECR_PATH="public.ecr.aws/iambic/iambic:latest"
 
 echo "Installing iambic..."
 DOCKER_CMD="#!/bin/bash
@@ -53,7 +53,7 @@ done
 ENV_VAR_ARGS=\"\$ENV_VAR_ARGS -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials\"
 ENV_VAR_ARGS=\"\$ENV_VAR_ARGS -e AWS_CONFIG_FILE=/app/.aws/config\"
 
-docker run -w /templates -it -u \$(id -u):\$(id -g) -v \${HOME}/.aws:/app/.aws \$ENV_VAR_ARGS --mount \"type=bind,src=\$(pwd),dst=/templates\"  public.ecr.aws/o4z3c2v2/iambic:latest \"\$@\""
+docker run -w /templates -it -u \$(id -u):\$(id -g) -v \${HOME}/.aws:/app/.aws \$ENV_VAR_ARGS --mount \"type=bind,src=\$(pwd),dst=/templates\"  public.ecr.aws/iambic/iambic:latest \"\$@\""
 
 echo