> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/4/deploy-container-image/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Deploy Gateway container image

> Instructions for deploying Itential Gateway using a containerized deployment method.

## Gateway containerization

Itential Gateway can be deployed using a containerized method of deployment.

### Prerequisites

Before proceeding, the following prerequisites must be met:

* OCI compliance
* Docker repository access
* AWS CLI on the host OS

> **Info**
>
> For CLI commands, remember to input the desired version for your environment, where applicable (e.g., `docker run --name iag_4.3.4`). For sample illustration purposes only, version `4.3.4` is used in this article.

### Container management platform

Gateway images are compliant with [Open Container Initiative (OCI)](https://opencontainers.org/) specifications; however, this guide assumes the use of Docker. Specific instruction for using technologies that manage OCI containers, such as Docker Compose, falls outside the scope of this guide.

### Docker repository access

Gateway images are hosted on the Itential Docker repository. Contact your Itential Account Manager to obtain the credential information needed to download images from this repository, including your:

* Access key ID
* Secret access key

### AWS command line interface

[Amazon Web Services Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/) must be installed on your host operating system (OS).

> **Info**
>
> For CLI commands, remember to input the desired version for your environment, where applicable.

## Log into the Itential Docker repository

Before you can begin working with Gateway containers, you must log into the Itential Docker repository. Issue the following command.

```bash
export AWS_ACCESS_KEY_ID=<access_key_id>
export AWS_SECRET_ACCESS_KEY=<secret_access_key>

aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 497639811223.dkr.ecr.us-east-2.amazonaws.com
```

| Parameter             | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| `<access_key_id>`     | The AWS access key ID provided by your Itential Account Manager.     |
| `<secret_access_key>` | The AWS secret access key provided by your Itential Account Manager. |

## Pull container images

To download images from the container registry, issue a `docker pull` command.

```bash
bundle_name=config
docker pull 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:4.3.4
```

## Start a Gateway container

To start a Gateway container, issue the following commands.

### Create Docker network

```bash
docker network create itential-network
```

### Start container

```bash
docker run --name iag_2023_3 -d --network itential-network -p 127.0.0.1:8083:8083/tcp 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:4.3.4
```

## Gateway dependencies

The [Gateway dependencies](./system-requirements#gateway-dependencies) must be running in your environment. This guide assumes these dependencies will be hosted via containers. However, dependencies may also be hosted via stand-alone servers, as they would be in a non-containerized Gateway application.

> **Info**
>
> Gateway andItential Platform must be on the same Docker network for each application to communicate with the other.

## Use the Gateway image

To start a Gateway container, issue the following command:

```bash
docker run --name some_IAG -d --network some_network \
-p host_machine_ip:host_port_number:container_port_number/tcp \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>
```

| Parameter      | Description                                                                                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `some_IAG`     | The desired name of the container.                                                                                                                                     |
| `some_network` | The Docker network to run the container in. If this network does not already exist, it will need to be created using the `docker network create some_network` command. |
| `tag`          | The desired version of Gateway to run. This can also be used to upgrade the Gateway image.                                                                             |

> **Info**
>
> The `host_machine_ip`, `host_port_number`, and `container_port_number` fields should be added and should match theItential Platform container docs. The Gateway port is 8083.

> **Warning**
>
> Referring to a feature release version of Gateway (e.g., `automation-gateway:4.3.0`) will result in the *latest maintenance release* of that version being run. Itential recommends using a specific maintenance release version (e.g., `automation-gateway:4.3.4`) in production environments.

## Set up Gateway database persistence

The default behavior of the Gateway container is to reset the Gateway database once the container is stopped using the `docker-compose down` command.

For the Gateway database to persist so that it is still available if the container is restarted or stopped, set up a volume to host the database on the host machine.

#### Create the mount location on the host machine

```bash
mkdir -p ./volumes/iag/data
```

#### Set up the mount reference in the docker-compose file

```bash
docker run --name some_IAP -d --network some_network \
-p host_machine_ip:host_port_number:container_port_number/tcp \
--mount type=bind,source=./volumes/iag/data,target=/opt/itential/automation-gateway/data \
497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>
```

## Build a customized Gateway image

The Gateway image does not have root access. If packages that require root access need to be added to the image, Itential recommends that you build a new Gateway image that adds the packages.

The following Dockerfile example builds a new Gateway image that adds the git package.

```dockerfile
## base the image on the Gateway image
##
FROM 497639811223.dkr.ecr.us-east-2.amazonaws.com/automation-gateway:<tag>
USER root
RUN mkdir -p /opt/ansible/logs && \
chown itential:itential /opt/ansible/logs && \
apk add git
USER itential
```

## Gateway properties

All the properties listed in the `properties.yml` file can be configured using environment variables.

For each property, place the text `automation_gateway_` in front of the Gateway property name.

**Example**

```yaml
environment:
  ## configure logging
  automation_gateway_logging_level: 'INFO'
  ## enable ansible and provide the paths to the playbooks, collections, and roles
  automation_gateway_ansible_enabled: 'true'
```

## Learn more

* Example Docker Compose files can be found in the [Itential Open Source GitLab](https://gitlab.com/itentialopensource/itential-containers-docker-compose-examples) repository. Documentation for these examples is provided in README files located throughout the project.
* To use Itential Gateway Docker images, see the demo examples provided at [Docker Compose examples Gateway](https://gitlab.com/itentialopensource/itential-containers-docker-compose-examples/-/blob/main/Gateway/README.md).

> Instructions for deploying Itential Gateway using a containerized deployment method.