Setting up a Terracotta environment on Windows 10

Terracotta comes with full support for Windows 10, even though setup might be more complicated compared to Unix systems.

Set up conda and install Terracotta

  1. Download and install Git for Windows.

  2. Download and install Miniconda. If you do not give the installer permissions to append conda to your PATH, you will have to use the Anaconda shell for the following steps.

  3. Clone the Terracotta repository to your hard drive by running

    $ git clone https://github.com/DHI-GRAS/terracotta.git
    

    Alternatively, you can choose and download a release version.

  4. Go to the Terracotta folder, and run

    $ conda env create -f environment.yml
    

    If the command finished without errors, you have successfully installed Terracotta.

  5. Before using Terracotta, activate the environment via

    $ conda activate terracotta
    

    You can now use the Terracotta CLI:

    $ terracotta --help
    

Optional: Configure AWS credentials

Terracotta unfolds its full potential when used with cloud services. All drivers support raster files located on AWS S3, and databases on S3 (through the RemoteSQLiteDriver) or RDS (through the MySQLDriver). To use these features, you need to create an account and authenticate with it.

  1. If you do not have an account on AWS yet, just head over and create one.

  2. You will need to create an IAM user that has programmatic access to your account. For that purpose, go to the IAM service and create a new IAM user.

    In the easiest setup, you can give it full permission to your account (but make sure to keep the key secret). For that, enter a username (such as awscli), check the box Programmatic access, and attach the AdministratorAccess policy.

  3. After you have created the IAM user, AWS will show you the corresponding ID and access key. Save those for later.

  4. Install the AWS command line tools by executing

    $ conda activate terracotta
    $ pip install awscli
    

    You can now use the AWS CLI:

    $ aws --help
    
  5. Configure the credentials to use with the AWS CLI:

    $ aws configure
    

    When asked for it, paste the ID and key of the IAM user you created in step 2. You will also have to choose a default AWS region, e.g. eu-central-1.

  6. You should now be able to use your AWS account programmatically. You can try this via

    $ aws s3 ls
    

    You should now see a list of your S3 buckets if you have created any.

By configuring the AWS credentials through the AWS CLI, Terracotta is now able to access all of your resources on AWS.

Optional: Set up Zappa on WSL

We rely on the magic provided by Zappa to deploy Terracotta on AWS Lambda. Since AWS Lambda workers run on Linux, we cannot use a Windows environment for deployment. This is why we rely on the Windows subsystem for Linux (WSL).

  1. First up, install the Windows subsystem for Linux. You can install any Linux flavor you want, but in this tutorial we are using Ubuntu.

  2. This and all further steps should be executed in a WSL shell. We will have to re-install Terracotta and its dependencies inside Linux.

    We will start by installing Python 3.6 and some libraries:

    $ sudo add-apt-repository ppa:deadsnakes/ppa
    $ sudo apt update
    $ sudo apt install build-essential gdal-bin git libgdal-dev python3.6-dev
    
  3. Create a new virtual Python environment that we will use to deploy Terracotta:

    $ pip install virtualenv --user
    $ virtualenv --python=python3.6 ~/envs/tc-deploy
    

    Activate the new environment by running

    $ source ~/envs/tc-deploy/bin/activate
    
  4. Clone Terracotta inside Linux:

    $ git clone https://github.com/DHI-GRAS/terracotta.git
    
  5. Switch to the Terracotta folder and install the Zappa requirements and Terracotta:

    $ pip install -r zappa_requirements.txt
    $ pip install -e .
    
  6. Install and configure the AWS CLI:

    $ pip install awscli
    $ aws configure
    

And you’re done! You should now be able to deploy Terracotta on AWS Lambda.