> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/virtual-hsm/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/virtual-hsm/tutorials/deploying-the-vhsm-container-on-an-ec2-instance.md).

# Deploying the vhsm Container on an EC2 Instance

#### Prerequisites

* [Create a EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html#ec2-launch-instance) and ensure that the **Instance type** is one of these [supported configurations](https://docs.enclaive.cloud/virtual-hsm/documentation/supported-cloud-configurations).
* Ensure your EC2 instance has proper [IAM permissions](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_ECS.html) to pull images from ECR.
* Make sure your EC2 instance's security group allows communication on the required ports.
* Depending on your setup, you may need to expose specific ports for accessing services within the container.

To install and run the `vhsm-aws` container from Amazon ECR on your EC2 instance, follow these steps:

 1\. Connect to your EC2 instance.

2. Install and configure Docker on your EC2 instance.

```bash
sudo apt update
sudo apt install docker.io
```

3\. Install AWS CLI on your EC2 instance.

```
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
```

\
4\. Configure AWS credentials.

```
aws configure
```

where

* **AWS Access Key ID**: (Get from your AWS IAM)
* **AWS Secret Access Key**: (Get from your AWS IAM)
* **Default region name**: us-east-1 (or the region you are using)
* **Default output format**: Leave it as None

5\. Authenticate Docker to Amazon ECR registry where the vhsm container image is stored.

```bash
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com
```

6\. Pull the `vhsm-aws` image from ECR.

For example, to pull the image tagged as `1.4.1-0`:

```bash
docker pull 709825985650.dkr.ecr.us-east-1.amazonaws.com/enclaive/vhsm:1.4.1-0
```

7\. Run a container named `vhsm-aws-container` using Docker.

```bash
docker run --cap-add IPC_LOCK -p8200:8200 --name vhsm-aws-container 709825985650.dkr.ecr.us-east-1.amazonaws.com/enclaive/vhsm:1.4.1-0
```

**Remarks:**

* `-p8200:8200`: vhsm runs on port 8200. Map the the port to the outbound port of choice (e.g. 8200).
* `--cap-add IPC_LOCK` : The `IPC_LOCK` capability allows a process to **lock memory** using `mlock(2)` and related system calls. This means the process can prevent some or all of its memory from being swapped out to disk. It's essential for applications that handle **sensitive data**, such as cryptographic keys or credentials, and want to avoid them being written to swap space.

8\. Verify the container is running.

```bash
docker ps
```

9\. To check the logs from the container to ensure it's working properly, you can use:

```bash
docker logs vhsm-aws-container
```

#### Troubleshooting:

* If you run into issues with Docker permissions, make sure your user has permission to access Docker. You may need to run Docker commands with `sudo` or add your user to the Docker group.
* If authentication fails when running `docker login`, ensure that your AWS credentials are configured correctly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.enclaive.cloud/virtual-hsm/tutorials/deploying-the-vhsm-container-on-an-ec2-instance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.