Skip to main content

App Deployment

If you are participating in the Self-hosted Environments Private Beta, see the Self-hosted tab for a set of unique instructions.

Before you get started, ensure the resources used by your Turbine streaming app exist on the Meroxa Platform within the Environment you wish to deploy to. You can check signing in to the Meroxa Dashboard or by running the following Meroxa CLI command to list all resources and their state.

This example shows the output if the as3 resource was created in Meroxa's common Multi-tenant Environment.

$ meroxa resources list
                 UUID                      NAME          TYPE        ENVIRONMENT                                             URL                                              TUNNEL   STATE
====================================== ============ =============== ============= ========================================================================================== ======== =======
 a012b345-cd67-8e9f-g01h-ij2k345l6mn7  as3          s3              common        s3://us-west-1/bucketname                                                               N/A     ready

If the resources don't exist, you must create your resources using the Meroxa Dashboard or CLI before proceeding to the next steps. Otherwise, you may run into an error.

Prepare to Deploy

The Turbine application framework uses git for version control. Upon initializing your application, git init is performed locally on your behalf. This creates a new repository in the project folder of your Turbine data app, which can be used to track your code. You will need commit your code changes before deploying by running a few commands.

The production or primary branch for Turbine streaming apps is always main. When git init is run, what is defined as your init.defaultBranch is set as the primary branch by default in the case you have this set as master.

  1. Ensure you are in the correct branch by using git branch.

  2. Review your Turbine code to make sure everything is correct.

  3. Stage your code changes and commit.

    # Commit changes to `main` branch

$ git branch
  * main
$ git add . 
$ git commit -m "First commit"
[main (root-commit) <short-sha> First commit
5 files changed, 18 insertions(+)
create mode 100644 .gitignore
create mode 100644 README.md
create mode 100644 app.json
create mode 100644 fixtures
create mode 100644 index.js

Now that you've committed your code changes you are ready to deploy to our multi-tenant common environment or your self-hosted environment (in private beta)!

Deploy to Meroxa

Using the Meroxa CLI, run the meroxa apps deploy command in the project folder root of your Turbine streaming app. This will start the process of deployment. The Meroxa CLI will print out the steps taken and confirm once deployment is successful.

When deploying a Turbine streaming application, our multi-tenant common environment is the default. This means you do not have to include the --env flag.

# Deploy from `main` branch to Meroxa

$ meroxa apps deploy
Validating your app.json...
    ✔ Checked your language is "javascript"
    ✔ Checked your application name is "liveapp"
Checking for uncommitted changes...
    ✔ No uncommitted changes!
Deploying application "liveapp"...
    ✔ Application built
    ✔ Can access your Turbine resources
    ✔ Application processes found. Creating application image...
    ✔ Platform source fetched
    ✔ Dockerfile created
    ✔ "turbine-liveapp.tar.gz" successfully created in "/Users/local/path/liveapp"
    ✔ Source uploaded
    ✔ Removed "turbine-liveapp.tar.gz"
    ✔ Dockerfile removed
    ✔ Successfully built process image ("UUID")
    ✔ Deploy complete
    ✔ Application "liveapp" successfully created!

  ✨ To visualize your application visit https://dashboard.meroxa.io/apps/liveapp/detail

Feature Branch Deployments to Meroxa

You can use feature branches to create test deployments of your Turbine streaming apps.

  1. Checkout a new feature branch. You can name it anything you'd like, just note that the branch name will be included in the Turbine data app name. In this example, we'll name it test.
  2. Make any appropriate changes to your Turbine code for your test. Make sure you are using the appropriate Source and Destination Resources that can be used with testing.
  3. Stage your code changes and commit.
  4. Use meroxa apps deploy in the root of your Turbine data app project. This will start the process of deployment. The Meroxa CLI will print out the steps taken and confirm once deployment is successful. 
# Commit changes to `this-is-a-test` feature branch

$ git checkout -b test
Switched to a new branch 'this-is-a-test'
$ git commit -m "Testing"
[test <short-sha>] Testing
1 file changed, 1 insertion(+), 1 deletion(-)

# Deploy from `this-is-a-test` feature branch to Meroxa

$ meroxa apps deploy
Validating your app.json...
    ✔ Checked your language is "javascript"
    ✔ Checked your application name is "liveapp"
    ✔ Feature branch (this-is-a-test) detected, setting app name to "liveapp-this-is-a-test"...
Checking for uncommitted changes...
    ✔ No uncommitted changes!
Deploying application "liveapp-this-is-a-test"...
    ✔ Application built
    ✔ Can access your Turbine resources
    ✔ Application processes found. Creating application image...
    ✔ Platform source fetched
    ✔ Dockerfile created
    ✔ "turbine-liveapp-this-is-a-test.tar.gz" successfully created in "/Users/local/path/liveapp"
    ✔ Source uploaded
    ✔ Removed "turbine-liveapp-this-is-a-test.tar.gz"
    ✔ Dockerfile removed
    ✔ Successfully built process image ("UUID")
    ✔ Deploy complete
    ✔ Application "liveapp-this-is-a-test" successfully created!

  ✨ To visualize your application visit https://dashboard.meroxa.io/apps/UUID/detail

Limitations

The ability to deploy from feature branches is a first step towards enabling continuous development on the Meroxa Platform. Here are things to know about this feature in the current state:

  • There are assumptions we make when it comes to deploying Turbine streaming apps:
    • Deployments from main are classified as production.
    • Deployments from feature branches other than main or is considered tests.
    • For tests, we identify them apart from production by appending the feature branch name to the end of the application name.
  • We do not yet support updating Turbine streaming apps. To redeploy, you must first delete the existing data application from Meroxa.
  • We do not check for looping effects across multiple streaming applications, resources, and collections. We highly recommend reviewing your Turbine code carefully before you deploy.
  • There is no concept of branch management on Meroxa. This must currently be managed entirely in a local or remote repository.
  • We do not yet support the automatic management of multiple development environments and their resources. However, this is something we plan to improve on.

Redeployment

Anytime you need to update the logic of your Turbine data app, you must remove, edit and redeploy it.

See application removal for instructions on how to remove your Turbine data app from the Meroxa Platform before preparing for redeployment.

Once successfully removed, you can make the desired changes to your Turbine data app, stage and commit your changes, and deploy again.

When deploying a Turbine streaming application, our multi-tenant common environment is the default. This means you do not have to include the --env flag.

# Commit changes to `main` branch

$ git add .
$ git commit -m "Update resource configuration"
[main (root-commit) <short-sha> Update resource configuration
1 file changed, 1 insertion(+), 1 deletion(-)

# Deploy from `main` branch to Meroxa

$ meroxa apps deploy
Validating your app.json...
    ✔ Checked your language is "javascript"
    ✔ Checked your application name is "liveapp"
Checking for uncommitted changes...
    ✔ No uncommitted changes!
Deploying application "liveapp"...
    ✔ Application built
    ✔ Can access your Turbine resources
    ✔ Application processes found. Creating application image...
    ✔ Platform source fetched
    ✔ Dockerfile created
    ✔ "turbine-liveapp.tar.gz" successfully created in "/Users/local/path/liveapp"
    ✔ Source uploaded
    ✔ Removed "turbine-liveapp.tar.gz"
    ✔ Dockerfile removed
    ✔ Successfully built process image ("UUID")
    ✔ Deploy complete
    ✔ Application "liveapp" successfully created!

  ✨ To visualize your application visit https://dashboard.meroxa.io/apps/liveapp/detail