# Installation

In this section, we will install Meltano as an application you can access from your browser and command line. If you prefer to install to Docker, please view the installation instructions here.

# Requirements

Before you install meltano with pip install meltano make sure you have the following requirements installed and up to date.

# Python 3+

• Python 3.6.1+

To check if you have the correct Python version, open your terminal and use the following commands to check the version:

python --version

# pip

pip is a package installer that comes automatically with Python 3+. This is also what we will be using to install Meltano. Here are some commands related to pip that may be of interest:

# Check for current version of pip
pip --version

# Update pip
pip install --upgrade pip

# Virtual Environment

# Recommened Virtual Environment Setup

We suggest you create a directory where you want your virtual environments to be saved, e.g.:

• Linux, OSX: ~/virtualenvs
• Windows: %ALLUSERSPROFILE%\\virtualenvs

Then create a new virtual environment inside that directory:

# Linux, OSX
mkdir ~/virtualenvs
python -m venv ~/virtualenvs/meltano

# Windows
mkdir %ALLUSERSPROFILE%\\virtualenvs
python -m venv %ALLUSERSPROFILE%\\virtualenvs\\meltano

# Activating Your Virtual Environment

Activate the virtual environment using:

# Linux, OSX
source ~/virtualenvs/meltano/bin/activate

# Windows
%HOME%\\virtualenvs\\meltano\\Scripts\\activate.bat

# Installing Meltano

Now that you have your virtual environment set up and running, navigate to the directory where you want to install Meltano and run the following command:

pip install meltano

Once the installation completes, you can check if it was successful by running:

meltano --version

That's it! Meltano is now be available for you to use. Now we can create a Meltano project.

# Linux, OSX
export PATH=$PATH:$HOME/virtualenvs/meltano/bin/meltano

# Windows
setx PATH "%PATH%;%ALLUSERPROFILES\virtualenvs\meltano\Scripts\meltano"

# Installing on Docker

Docker is an alternative installation option to using a virtual environment to run Meltano. To use these instructions you will need to install Docker onto your computer and have it running when you execute the commands below.

# Using Pre-built Docker Images

We provide the meltano/meltano docker image with Meltano pre-installed and ready to use.

Note: The meltano/meltano docker image is also available in GitLab's registry: registry.gitlab.com

This image contains everything you need to get started with Meltano.

# download or update to the latest version
docker pull meltano/meltano

# look the currently installed version
docker run meltano/meltano --version

# Initialize Your Project

Once you have Docker installed, running, and have pulled the pre-built image you can use Meltano just as you would in our Quickstart Guide. However, the command line syntax is slightly different. For example, let's create a new Meltano project:

docker run -v $(pwd):/projects \
             -w /projects \
             meltano/meltano init YOUR_PROJECT_NAME

Then you can cd into your new project:

cd YOUR_PROJECT_NAME

We can then start the Meltano UI. Since ui is the default command, we can omit it.

docker run -v $(pwd):/project \
             -w /project \
             -p 5000:5000 \
             meltano/meltano

You can now visit http://localhost:5000 to access the Meltano UI.

If you are a Meltano end-user who is not going to be contributing code to our open source repository, you should be able to use Meltano entirely from the UI at this point.

Follow the steps in our Quickstart Guide to get started.

# For Contributors: Example Command Line Syntax for Docker

Here are some example of CLI commands you may need to run if you are working with Meltano as an open source contributor:

# Running the ELT from the Command Line

To run the ELT and extract some data from the tap-carbon-intensity into target-sqlite:

docker run -v $(pwd):/project \
             -w /project \
             meltano/meltano elt tap-carbon-intensity target-sqlite

# Adding a Model from the Command Line

Now that we have data in your database, let's add the corresponding model bundle as the basis of our analysis.

docker run -v $(pwd):/project \
             -w /project \
             meltano/meltano add model model-carbon-intensity-sqlite

# Upgrading Version

We release new versions of Meltano weekly. To update Meltano to the latest version, run the following command in your terminal:

pip install --upgrade meltano

Follow along on the Meltano blog to keep tabs on the latest releases, or visit our CHANGELOG.

# Deployment

# Amazon Web Services (AWS)

In this section, we will be going over how you can deploy a Meltano Docker image to AWS.

# Setting Up Elastic Container Service (ECS)

1. Login to AWS Console
2. Search for ECS and click on the link

1. We will create a new Container definition by clicking on the Configure button in the custom card
2. Fill out the form with the following data:

• Container name: Meltano
• Image: YOUR_DOCKER_IMAGE_URL
  • Examples:
    • docker.io/namespace/image-name:tag
    • registry.gitlab.com/namespace/project/image-name:tag
• Memory Limits (MiB): Soft limit 1024
• Port mappings:
  • 5000/tcp (meltano)
  • 5010/tcp (airflow)

1. Click Update button to finish setting up your container defintion
2. Click Edit next to the Task defintion heading
3. Update the form with the following:

• Task definition name: meltano-run
• Network mode: awsvpc
• Task execution role: ecsTaskExecutionRole
• Compatibilities: FARGATE
• Task memory: 1GB (1024)
• Task CPU: 0.25 vCPU (256)

1. Click Next to move to the next step

# Review service properties

1. Verify that the properties are as follows:

• Service name: meltano-service
• Number of desired tasks: 1
• Security group: Automatically create new
• Load balancer type: None

1. Click Next to move on to the next step

# Configure your cluster

The main configuration here is the Cluster name. We provide a suggestion below, but feel free to name it as you wish.

• Cluster name: meltano-cluster
• VPC ID: Automatically create new
• Subnets: Automatically create new

# Review cluster configuration

After you click Next, you will have the opportunity to review all of the properties that you set. Once you confirm that the settings are correct, click Create to setup your ECS.

You should now see a page where Amazon prepares the services we configured. There will be spinning icons on the right of each service that will live update as it finished. Once you see everything has setup properly, you're cluster has been successfully deployed!

# Final steps

1. Open the page with your cluster
2. Click on the Tasks tab
3. You should see a task that has a status of RUNNING for Last Status
4. Click on the Task ID link (e.g., 0b35dea-3ca..)
5. Under Network, you can find the URL for your instance under Public IP (e.g., 18.18.134.18)
6. Open a new tab in your browser and visit this new URL on port 5000 (e.g., http://18.18.134.18:5000)

# Configure network access

Once you complete the cluster setup, you should be brought to the detail page for the service. You should be default on a tab called Details with a Network Access section.

1. Navigate to the Details tab
2. Under Network Access, click on the link next to Security Groups (e.g., sg-f0dj093dkjf10)
3. This should open a new tab with your security group
4. Navigate to the Inbound Rules tab on the bottom of the page
5. Click Edit Rules
6. Delete any existing rules
7. Click Add Rule with the following properties:

• Type: Custom TCP Rule
• Protocol: TCP
• Port Range: 5000
• Source: Custom 0.0.0.0/0

1. Click "Add Rule" with the following properties:

• Type: Custom TCP Rule
• Protocol: TCP
• Port Range: 5010
• Source: Custom 0.0.0.0/0

1. Click Save rules

# Troubleshooting

Are you having installation or deployment problems? We are here to help you. Please fill out this issue template and we'll get back to you as soon as we can!