Skip to main content

Install via Docker

Running the IAMbic docker container locally​

Prerequisites​

Before you begin, you'll need to have the following tools installed on your system:

Steps​

Note: for instructions on how to use IAMbic, reference Using IAMbic

To run the docker container locally, you can use the docker command:

Basic run:

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/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/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/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/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/iambic/iambic:latest <command>

Shortcut​

We recommend that you add the following to your ~/.bashrc or ~/.bash_profile:

echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws:ro -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e AWS_PROFILE -e HOME=/app -v <iambic-templates>:/templates:Z public.ecr.aws/iambic/iambic:latest"' >> ~/.bashrc
echo 'alias iambic="docker run -it -u $(id -u):$(id -g) -v ${HOME}/.aws:/app/.aws:ro -e AWS_CONFIG_FILE=/app/.aws/config -e AWS_SHARED_CREDENTIALS_FILE=/app/.aws/credentials -e AWS_PROFILE -e HOME=/app -v <iambic-templates>:/templates:Z public.ecr.aws/iambic/iambic:latest"' >> ~/.zshrc

That way you can just execute iambic seamlessly as an application within your system:

iambic import

Building the IAMbic docker container​

You can also build your own IAMbic docker container by cloning the IAMbic repo and following the below steps:

Prerequisites​

Before you begin, you'll need to have the following tools installed on your system:

  • Docker
  • Docker Compose

If you don't have these tools installed, follow the instructions below:

Steps​

Clone the IAMbic repository to your local machine.​

git clone https://github.com/noqdev/iambic.git
cd iambic/
docker build -t your-username/project-name:tag .

Replace your-username/project-name:tag with the name you want to give your Docker image. For example, johnsmith/my-project:v1.0.0. The . at the end of the command specifies that the Dockerfile is located in the current directory.

Test the Docker image.​

Run the following command to start a Docker container using the image you just built:

docker run your-username/project-name:tag <command>

This command starts the container using the Docker image you just built.

You should be able to start the documentation server by typing: docker run your-username/project-name:tag doc_serve. Then try to access this documentation resource on http://localhost:3000.

Push the Docker image to Docker Hub or a private repository.​

Docker Hub is a popular registry for storing and sharing Docker images. If you don't have a Docker Hub account, sign up for one.

Alternatively, publish the docker image to a repository of your choice.

If you choose to store the docker image in docker hub...

Login:

docker login

This command will prompt you to enter your Docker Hub username and password.

Once you're logged in, run the following command to push the Docker image to Docker Hub:

docker push your-username/project-name:tag

This command uploads the Docker image to Docker Hub, where it can be accessed by other users.