Setting up a Terracotta environment on Windows¶
Terracotta comes with full support for Windows, even though setup might be more complicated compared to Unix systems.
Set up conda and install Terracotta¶
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.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.
Go to the Terracotta folder, and run
$ conda env create -f environment.yml
If the command finished without errors, you have successfully installed Terracotta.
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.
If you do not have an account on AWS yet, just head over and create one.
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 boxProgrammatic access
, and attach theAdministratorAccess
policy.After you have created the IAM user, AWS will show you the corresponding ID and access key. Save those for later.
Install the AWS command line tools by executing
$ conda activate terracotta $ pip install awscli
You can now use the AWS CLI:
$ aws --help
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
.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).
First up, install the Windows subsystem for Linux. You can install any Linux flavor you want, but in this tutorial we are using Ubuntu.
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.10 and some libraries:
$ sudo add-apt-repository ppa:deadsnakes/ppa $ sudo apt update $ sudo apt install build-essential gdal-bin git libgdal-dev python3.10-dev
Create a new virtual Python environment that we will use to deploy Terracotta:
$ pip install virtualenv --user $ virtualenv --python=python3.10 ~/envs/tc-deploy
Activate the new environment by running
$ source ~/envs/tc-deploy/bin/activate
Clone Terracotta inside Linux:
$ git clone https://github.com/DHI-GRAS/terracotta.git
Switch to the Terracotta folder and install the Zappa requirements and Terracotta:
$ pip install -r zappa_requirements.txt $ pip install -e .
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.