Self-Hosted Installation

This section provides guides for getting set up with a self-hosted instance of Meltano's open source data analytics software on your local computer or using popular hosting solutions:

TIP

Are you trying Meltano for the first time? You can skip the installation process and we'll set you up with a free 30-day trial of Meltano as a hosted service. If you decide you want to switch to self-hosted later we can clone your instance so you can take it with you. Sign up here.

Local Installation

In this section, we will install Meltano as a local application on your computer that you can access from your browser and on the command line.

TIP

We do not have a double click installer at this time, but it is on our roadmap and we will be sure to update this page when we do!

Requirements

Before you install Meltano, make sure you have the following requirements installed and up to date.

Unix-like environment

WARNING

There is currently a known issue with macOS 10.15 and Python 3. For more information, visit issue #1468.

Recent versions of Linux and macOS are both fully supported, but Windows is not.

If you'd like to run Meltano on Windows, you can install it inside the Windows Subsystem for Linux (WSL). You may also try installing Meltano on Docker, although Docker on Windows is known to have some idiosyncrasies that might hinder Meltano's ability to function.

Python 3+

TIP

You may refer to https://realpython.com/installing-python/ for platform specific installation instructions.

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

python --version

If you've installed Python 3, but are not getting the result you expect, you may have installed Python 3 alongside an existing Python 2 installation. In this case, please use python3 and pip3 wherever this guide refers to the python and pip commands.

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
 to ensure that it is using the Python3 pip
pip --version

 Update pip
pip install --upgrade pip

Virtual Environment

IMPORTANT

Unless you are building a Docker image, it is strongly recommended that Meltano be installed inside a virtual environment in order to avoid potential system conflicts that may be difficult to debug.

Why use a virtual environment?

Your local environment may use a different version of Python or other dependencies that are difficult to manage. The virtual environment provides a "clean" space to work without these issues.

We suggest you create a directory where you want your virtual environments to be saved (e.g. .venv/). This can be any directory in your environment, but we recommend saving it in your Meltano project to make it easier to keep track of.

Then create a new virtual environment inside that directory:

mkdir .venv
python -m venv .venv/meltano

Activating Your Virtual Environment

Activate the virtual environment using:

source .venv/meltano/bin/activate

If the virtual environment was activated successfully, you'll see a (meltano) indicator added to your prompt.

TIP

Once a virtual environment is activated, it stays active until the current shell is closed. In a new shell, you must re-activate the virtual environment before interacting with the meltano command that will be installed in the next step.

To streamline this process, you can define a shell alias that'll be easier to remember than the entire activation invocation:

 Add to `~/.bashrc`, `~/.zshrc`, etc, depending on the shell you use:
alias meltano!="source $MELTANO_PROJECT_PATH/.venv/meltano/bin/activate"

 Use as follows, after creating a new shell:
meltano!

You can deactivate a virtual environment by typing deactivate in your shell.

Install Meltano

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

pip install meltano

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

meltano --version

Now that you've installed Meltano and its requirements, you can create your first project.

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 Getting Started 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 yourprojectname

Then you can cd into your new project:

cd yourprojectname

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 Getting Started Guide to get started.

Amazon Web Services (AWS)

Prerequisites

This guide assumes that you have a functioning Docker image where your Meltano project is already bundled with the Meltano installation. To track this issue, follow meltano#624.

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)
  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)

TIP

The IP address can be mapped to a domain using Route53. We will be writing up a guide on how to do this. You can follow along at meltano#625.

Next Steps

Once you have successfully installed Meltano from the command line, you will need to [create your first project from the command line]/developer-tools/command-line-interface.html#create-your-first-project).

Troubleshooting Installation

TIP

Are you having installation or deployment problems? We are here to help you. Check out Getting Help on the different ways to get in touch with us.

Configure network access

TIP

This section is only necessary if you do not have a Security Group that allows for port 5000,5010 inbound.

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

Upgrading Meltano Version

We release a new version of Meltano every week. To keep tabs on the latest releases, follow along on the Meltano blog, or have a look at our CHANGELOG.

Using Meltano UI

When an update is available, you will be informed of this automatically through a shiny blue button in the top right corner of Meltano UI:

Clicking this button will show more information and give you the option to install the update right away:

The Meltano UI will refresh automatically once installation is complete.

Using the command line

If you're not using Meltano UI, you can update Meltano to the latest version by running the following command in your terminal:

meltano upgrade
Last Updated: 2/13/2020, 11:29:24 PM