# Setting up a DLAMI instance
After you [choose a DLAMI](choose-dlami.md) and [choose an Amazon Elastic Compute Cloud (Amazon EC2) instance type](instance-select.md) that you want to use, then you're ready to set up your new DLAMI instance.
If you haven't yet chosen a DLAMI and EC2 instance type, then see [Getting started with DLAMI](getting-started.md).
**Topics**
+ [Finding the ID of a DLAMI](find-dlami-id.md)
+ [Launching a DLAMI instance](launch.md)
+ [Connecting to a DLAMI instance](setup-connect.md)
+ [Setting up a Jupyter Notebook server on a DLAMI instance](setup-jupyter.md)
+ [Cleaning up a DLAMI instance](setup-cleanup.md)
# Finding the ID of a DLAMI
Each DLAMI has a unique identifier (ID). When you launch a DLAMI instance using the Amazon EC2 console, you can optionally use the DLAMI ID to search for the DLAMI that you want to use. When you launch a DLAMI instance using the AWS Command Line Interface (AWS CLI), this ID is required.
You can find the ID for the DLAMI of your choice by using an AWS CLI command for either Amazon EC2 or Parameter Store, a capability of AWS Systems Manager. For instructions on installing and configuring the AWS CLI, see [Get started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started) in the *AWS Command Line Interface User Guide*.
------
#### [ Using Parameter Store ]
**To find a DLAMI ID using **ssm get-parameter****
In the following [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-parameter.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ssm/get-parameter.html) command, for the `--name` option, the parameter name format is */aws/service/deeplearning/ami/\$1architecture/\$1ami\$1type/latest/ami-id*. In this name format, *architecture* can be either **x86\$164** or **arm64**. Specify the *ami\$1type* by taking the DLAMI name and removing the keywords "deep", "learning", and "ami". AMI Name can be found in [Deep Learning AMIs Release Notes](appendix-ami-release-notes.md).
**Important**
To use this command, the AWS Identity and Access Management (IAM) principal that you use must have the `ssm:GetParameter` permission. For more information about IAM principals, see the [Additional resources](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html#id_roles_additional-resources) section of **IAM roles** in the *IAM User Guide*.
+
```
aws ssm get-parameter --name /aws/service/deeplearning/ami/x86_64/base-oss-nvidia-driver-ubuntu-22.04/latest/ami-id \
--region us-east-1 --query "Parameter.Value" --output text
```
The output should look similar to the following:
```
ami-09ee1a996ac214ce7
```
**Tip**
For some currently supported DLAMI frameworks, you can find more specific example **ssm get-parameter** commands in [Deep Learning AMIs Release Notes](appendix-ami-release-notes.md). Choose the link to the release notes of your chosen DLAMI, and then find its ID query in the release notes.
------
#### [ Using Amazon EC2 CLI ]
**To find a DLAMI ID using **ec2 describe-images****
In the following [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/describe-images.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/describe-images.html) command, for the value of the filter `Name=name`, enter the DLAMI name. You can specify a release version for a given framework, or you can get the latest release by replacing the version number with a question mark (?).
+
```
aws ec2 describe-images --region us-east-1 --owners amazon \
--filters 'Name=name,Values=Deep Learning Base OSS Nvidia Driver GPU AMI (Ubuntu 22.04) ????????' 'Name=state,Values=available' \
--query 'reverse(sort_by(Images, &CreationDate))[:1].ImageId' --output text
```
The output should look similar to the following:
```
ami-09ee1a996ac214ce7
```
**Tip**
For an example **ec2 describe-images** command that's specific to the DLAMI of your choice, see [Deep Learning AMIs Release Notes](appendix-ami-release-notes.md). Choose the link to the release notes of your chosen DLAMI, and then find its ID query in the release notes.
------
**Next step**
[Launching a DLAMI instance](launch.md)
# Launching a DLAMI instance
After you [find the ID](find-dlami-id.md) of the DLAMI that you want to use to launch a DLAMI instance, you're ready to launch the instance. To launch it, you can use either the Amazon EC2 console or the AWS Command Line Interface (AWS CLI).
**Note**
For this walkthrough, we might make references specific to the Deep Learning Base OSS Nvidia Driver GPU AMI (Ubuntu 22.04). Even if you select a different DLAMI, you should be able to follow this guide.
------
#### [ EC2 console ]
**Note**
To accelerate high-performance computing (HPC) and machine learning applications, you can launch your DLAMI instance with an Elastic Fabric Adapter (EFA). For specific instructions, see [Launching a AWS Deep Learning AMIs Instance With EFA](tutorial-efa-launching.md).
1. Open the [EC2 Console](https://console.aws.amazon.com/ec2).
1. Note your current AWS Region in the top-most navigation. If this isn't your desired Region, then change this option before you continue. For more information, see [Amazon EC2 service endpoints](https://docs.aws.amazon.com/general/latest/gr/ec2-service.html#ec2_region) in the *Amazon Web Services General Reference*.
1. Choose **Launch Instance**.
1. Enter a name for your instance and select the DLAMI that is right for you.
1. Find an existing DLAMI in **My AMIs** or choose **Quick Start.**
1. Search by DLAMI ID. Browse the options then select your choice.
1. Choose an instance type. You can find the recommended instance families for your DLAMI in [Deep Learning AMIs Release Notes](appendix-ami-release-notes.md). For general recommendations on DLAMI instance types, see [Choosing a DLAMI instance type](instance-select.md).
1. Choose **Launch Instance**.
------
#### [ AWS CLI ]
+ To use the AWS CLI, you must have the ID of the DLAMI that you want to use, the AWS Region and EC2 instance type, and your security token information. Then, you can launch the instance using the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/run-instances.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ec2/run-instances.html) AWS CLI command.
For instructions on installing and configuring the AWS CLI, see [Get started with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started) in the *AWS Command Line Interface User Guide*. For more information, including command examples, see [Launch, list, and close Amazon EC2 instances for the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-services-ec2-instances.html).
------
After you launch your instance using either the Amazon EC2 console or AWS CLI, wait for the instance to be ready. This usually takes only a few minutes. You can verify the status of the instance in the [Amazon EC2 console](https://console.aws.amazon.com/ec2). For more information, see [Status checks for Amazon EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-system-instance-status-check.html) in the *Amazon EC2 User Guide*.
**Next step**
[Connecting to a DLAMI instance](setup-connect.md)
# Connecting to a DLAMI instance
After you [launch a DLAMI instance](launch.md) and the instance is running, you can connect to it from a client (Windows, macOS, or Linux) using SSH. For instructions, see [Connect to your Linux instance using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html) in the *Amazon EC2 User Guide*.
Keep a copy of the SSH login command handy in case you want to set up a Jupyter Notebook server after you log in. To connect to the Jupyter webpage, you use a variation of that command.
**Next step**
[Setting up a Jupyter Notebook server on a DLAMI instance](setup-jupyter.md)
# Setting up a Jupyter Notebook server on a DLAMI instance
With a Jupyter Notebook server, you can create and run Jupyter notebooks from your DLAMI instance. With Jupyter notebooks, you can conduct machine learning (ML) experiments for training and inference while using the AWS infrastructure and accessing packages built into the DLAMI. For more information about Jupyter notebooks, see [The Jupyter Notebook](https://jupyter-notebook.readthedocs.io/en/latest/notebook.html) on the Jupyter User Documentation website.
To set up a Jupyter Notebook server, you must:
+ Configure the Jupyter Notebook server on your DLAMI instance.
+ Configure your client to connect to the Jupyter Notebook server. We provide configuration instructions for Windows, macOS, and Linux clients.
+ Test the setup by logging in to the Jupyter Notebook server.
To complete these steps, follow the instructions in the following topics. After you've set up a Jupyter Notebook server, you can run the example notebook tutorials that ship in the DLAMIs. For more information, see [Running Jupyter Notebook Tutorials](tutorial-jupyter.md).
**Topics**
+ [Securing server](setup-jupyter-secure.md)
+ [Starting server](setup-jupyter-start-server.md)
+ [Connecting client](setup-jupyter-connect.md)
+ [Logging in](setup-jupyter-login.md)
# Securing the Jupyter Notebook server on a DLAMI instance
To keep your Jupyter Notebook server secure, we recommend setting up a password and creating an SSL certificate for the server. To configure a password and SSL, first [connect to your DLAMI instance](setup-connect.md), and then follow these instructions.
**To secure the Jupyter Notebook server**
1. Jupyter provides a password utility. Run the following command and enter your preferred password at the prompt.
```
$ jupyter notebook password
```
The output will look something like this:
```
Enter password:
Verify password:
[NotebookPasswordApp] Wrote hashed password to /home/ubuntu/.jupyter/jupyter_notebook_config.json
```
1. Create a self-signed SSL certificate. Follow the prompts to fill out your locality as you see fit. You must enter `.` if you wish to leave a prompt blank. Your answers will not impact the functionality of the certificate.
```
$ cd ~
$ mkdir ssl
$ cd ssl
$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout mykey.key -out mycert.pem
```
**Note**
You might be interested in creating a regular SSL certificate that is third-party signed and does not cause the browser to give you a security warning. This process is much more involved. For more information, see [Securing a notebook server](https://jupyter-notebook.readthedocs.io/en/6.2.0/public_server.html#securing-a-notebook-server) in the Jupyter Notebook user documentation.
**Next step**
[Starting the Jupyter Notebook server on a DLAMI instance](setup-jupyter-start-server.md)
# Starting the Jupyter Notebook server on a DLAMI instance
After you [secure your Jupyter Notebook server with a password and SSL](setup-jupyter-secure.md), you can start the server. Log in to your DLAMI instance and run the following command that uses the SSL certificate that you created previously.
```
$ jupyter notebook --certfile=~/ssl/mycert.pem --keyfile ~/ssl/mykey.key
```
With the server started, you can now connect to it via an SSH tunnel from your client computer. When the server runs, you will see some output from Jupyter confirming that the server is running. At this point, ignore the callout that you can access the server via a local host URL, because that won't work until you create the tunnel.
**Note**
Jupyter will handle switching environments for you when you switch frameworks using the Jupyter web interface. For more information, see [Switching Environments with Jupyter](tutorial-jupyter.md#tutorial-jupyter-switching).
**Next step**
[Connecting a client to the Jupyter Notebook server on a DLAMI instance](setup-jupyter-connect.md)
# Connecting a client to the Jupyter Notebook server on a DLAMI instance
After you [start the Jupyter Notebook server on your DLAMI instance](setup-jupyter-start-server.md), configure your Windows, macOS, or Linux client to connect to the server. When you connect, you can create and access Jupyter notebooks on the server in your workspace and run your deep learning code on the server.
## Prerequisites
Be sure you have the following, which you need to set up an SSH tunnel:
+ The public DNS name of your Amazon EC2 instance. For more information, see [Amazon EC2 instance hostname types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-naming.html) in the *Amazon EC2 User Guide*.
+ The key pair for the private key file. For more information about accessing your key pair, see [Amazon EC2 key pairs and Amazon EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) in the *Amazon EC2 User Guide*.
## Connect from a Windows, macOS, or Linux client
To connect to your DLAMI instance from a Windows, macOS, or Linux client, follow the instructions for your client's operating system.
------
#### [ Windows ]
**To connect to your DLAMI instance from a Windows client using SSH**
1. Use an SSH client for Windows, such as PuTTY. For instructions, see [Connect to your Linux instance using PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-from-windows.html) in the *Amazon EC2 User Guide*. For other SSH connection options, see [Connect to your Linux instance using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-linux-instance.html).
1. (Optional) Create an SSH tunnel to a running Jupyter server. Install Git Bash on your Windows client, and then follow the connection instructions for macOS and Linux clients.
------
#### [ macOS or Linux ]
**To connect to your DLAMI instance from a macOS or Linux client using SSH**
1. Open a terminal.
1. Run the following command to forward all requests on local port 8888 to port 8888 on your remote Amazon EC2 instance. Update the command by replacing the location of your key to access the Amazon EC2 instance and the public DNS name of your Amazon EC2 instance. Note, for an Amazon Linux AMI, the user name is `ec2-user` instead of `ubuntu`.
```
$ ssh -i ~/mykeypair.pem -N -f -L 8888:localhost:8888 ubuntu@ec2-###-##-##-###.compute-1.amazonaws.com
```
This command opens a tunnel between your client and the remote Amazon EC2 instance that is running the Jupyter Notebook server.
------
**Next step**
[Logging in to the Jupyter Notebook server on a DLAMI instance](setup-jupyter-login.md)
# Logging in to the Jupyter Notebook server on a DLAMI instance
After you [connect your client to the Jupyter Notebook server on your DLAMI instance](setup-jupyter-connect.md), you can log in to the server.
**To log in to the server in your browser**
1. In the address bar of your browser, enter the following URL, or click on this link: [https://localhost:8888](https://localhost:8888)
1. With a self-signed SSL certificate, your browser will warn you and prompt you to avoid continuing to visit the website.
![\[SSL warning\]](http://docs.aws.amazon.com/dlami/latest/devguide/images/ssl-warning1.png)
Since you set this up yourself, it is safe to continue. Depending your browser you will get an "advanced", "show details", or similar button.
![\[SSL warning confirmation\]](http://docs.aws.amazon.com/dlami/latest/devguide/images/ssl-warning2.png)
Click on this, then click on the "proceed to localhost" link. If the connection is successful, you see the Jupyter Notebook server webpage. At this point, you will be asked for the password you previously set up.
Now you have access to the Jupyter Notebook server that is running on the DLAMI instance. You can create new notebooks or run the provided [Tutorials](tutorials.md).
# Cleaning up a DLAMI instance
When you no longer need your DLAMI instance, you can stop it or terminate it on Amazon EC2 to avoid incurring unexpected charges.
If you stop an instance, you can keep it around and start it later when you want to use it again. Your configurations, files, and other non-volatile information are stored in a volume on Amazon Simple Storage Service (Amazon S3). While your instance is stopped, you incur S3 charges for retaining the volume, but you don't incur charges for compute resources. When your start the instance again, it will mount that storage volume with your data.
If you terminate an instance, it's gone, and you cannot start it again. Of course, you won't incur any more charges for the compute resources with a terminated instance. However, your data still resides on Amazon S3, and you can continue to incur S3 charges. To prevent all further charges related to your terminated instance, you must also delete the storage volume on Amazon S3. For instructions, see [Terminate Amazon EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html) in the *Amazon EC2 User Guide*.
For more information about Amazon EC2 instance states, such as `stopped` and `terminated`, see [Amazon EC2 instance state changes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-lifecycle.html) in the *Amazon EC2 User Guide*.