getting-started.rst

Getting Started with the |cdk|

This topic describes how to download, install, and configure the |cdk|.

Installing the |cdk|

This section describes how to install the |cdk|, and lists the prerequsites for each supported language.

Prerequisites

You must install Node.js (>= 8.11.x) to use the command-line toolkit and language bindings.

If you use Java, you must set the JAVA_HOME environment variable to the path to where you have installed the JDK on your machine to build an |cdk| app in Java.

Specify your credentials and region with the AWS CLI. You must specify both your credentials and a region to use the toolkit. See :ref:`credentials <credentials>` for information on using the AWS CLI to specify your credentials.

Installing the Command-Line Toolkit

Install the toolkit using the following npm command:

npm install -g aws-cdk

Run the following command to see the currently installed version of the toolkit (this guide was written for |version|):

cdk --version

Configuring the |cdk|

You must specify your default credentials and region to use the toolkit.

Use the AWS Command Line Interface aws configure command to specify your default credentials and region.

You can also set environment variables for your default credentials and region. Environment variables take precedence over settings in the credentials or config file.

• AWS_ACCESS_KEY_ID specifies your access key
• AWS_SECRET_ACCESS_KEY specifies your secret access key
• AWS_DEFAULT_REGION specifies your default region

See Environment Variables in the CLI User Guide for details.

The |cdk| toolkit needs to know how to execute your |cdk| app. It requires that the --app command-line option points to an executable program that adheres to the toolkit's protocol. Although you can include an --app option every time you use the toolkit, we recommend that you instead create a cdk.json file at the root of your project directory with the following content:

.. tabs::

    .. group-tab:: C#

        Define the :code:`--app` option in a **cdk.json** file:

        .. code-block:: json

            {
              "app": "dotnet run --project HelloCdk.csproj"
            }

    .. group-tab:: JavaScript

        Define the :code:`--app` option in **cdk.json** to execute **hello-cdk.js**
        using **node**:

        .. code-block:: json

            {
              "app": "node bin/hello-cdk.js"
            }

    .. group-tab:: TypeScript

        Define the :code:`--app` option in **cdk.json** to execute **hello-cdk.js**
        using **node**:

        .. code-block:: json

            {
              "app": "node bin/hello-cdk.js"
            }

    .. group-tab:: Java

        Specify a
        **CLASSPATH**, which contains both the compiled code and dependencies,
        to execute the Java program.

        Use **maven-dependency-plugin** in your **pom.xml** file to produce the file **.classpath.txt**
        whenever the project is compiled:

        .. code-block:: xml

            <build>
                <plugins>
                    <!-- ... -->

                    <!-- Emit the classpath to ./.classpath.txt so cdk.json can use it -->
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-dependency-plugin</artifactId>
                        <version>2.8</version>
                        <executions>
                        <execution>
                            <id>build-classpath</id>
                            <phase>generate-sources</phase>
                            <goals>
                                <goal>build-classpath</goal>
                            </goals>
                            <configuration>
                                <outputFile>.classpath.txt</outputFile>
                            </configuration>
                        </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>

        Run **mvn compile** and verify that **.classpath.txt** exists:

        .. code-block:: sh

            mvn compile
            ls .classpath.txt

        Create a shim **app.sh** to execute the |cdk| Java app:

        .. code-block:: sh

            #!/bin/bash
            exec java -cp target/classes:$(cat .classpath.txt) com.acme.MyApp app $@

        Define the :code:`--app` option in **cdk.json**:

        .. code-block:: json

            {
              "app": "/bin/bash ./app.sh"
            }