Introduction

Teleport is an extensible scripting toolkit for working with one or more local MODX Revolution installations. It currently functions primarily as a packaging toolkit which extends the MODX Transport APIs and provides commands for extracting and injecting customizable snapshots of MODX deployments. But it can be extended easily to perform an infinite variety of actions related to MODX.

Install

There are various methods for installing Teleport so you can begin using it. Choose the one that best fits your needs:

  • Phar - The easiest way to start using Teleport is to download the latest teleport.phar and put it in a directory where the application can do it's work. In this distribution, Teleport will attempt to create subdirectories called profile/ and workspace/ where it will store generated site Profiles and Extracted transport packages, respectively. The phar distribution includes all dependencies required to use Teleport. Note however that you cannot run the Teleport HTTP Server from the phar distribution; it is not included in the Phar.

  • Releases - You can download zip and tar.gz formats of any Teleport release, extract them in an appropriate location, and run composer install in that location to download the required dependencies. GitHub releases of the project are available here.

  • Git Clone - Contributors can clone the teleport repository or their own fork of it from GitHub, and run composer install --dev in that location to download the required dependencies, including those specified in the require-dev section of the composer.json.

Use

Actions

At the most basic level, you interact with the Teleport application by calling a specific Teleport action with any number of arguments.

Currently, Teleport provides the following Actions:

  • Profile - Generate a JSON profile of a MODX installation that can be used by other Actions to interact with it.

  • Extract - Extract files, data, and/or other artifacts described by a specified extract tpl, from a MODX installation described by a specified profile, and package them into a transport that can later be Injected into any other MODX installation.

  • Inject - Inject a specified transport package generated by a Teleport Extract, into a MODX installation described by a specified profile.

  • Push - Push a specified source file to a specified target location.

  • UserCreate - Create a User in a MODX installation described by a specified profile.

  • Packages/GC - Remove outdated versions of packages from a MODX installation described by a specified profile.

  • Workspace/GC - Empty the contents of the Teleport workspace.

CLI Requests

The simplest way to use Teleport is by calling Teleport Actions on the command line. See documentation for an Action to discover the required and optional arguments for calling that specific Teleport Action.

Teleport HTTP Server

Teleport comes with a custom HTTP server, built with ReactPHP that can be run on any server port. This allows access to Teleport Actions over HTTP, bypassing timeout and other issues that can occur when attempting to execute long-running processes using your public web server configuration.

Extend

Teleport is intended to be easily extensible in a couple of ways. For best results, it is recommended you create your own project using Teleport as a library where you can track your custom additions to the application in the VCS of your choice. The easiest way to get started with a custom Teleport project is by using Composer's create-project command from the modxcms/teleport-project boilerplate package.

php composer.phar create-project --prefer-source --stability=dev modxcms/teleport-project teleport-opengeek/

You can find more information about using the boilerplate package at the GitHub project.

Custom Extracts

The Teleport Extract Action uses a JSON extract tpl to describe how a transport package is created from a variety of MODX site resources. You can easily create your own tpls to quickly build custom packages for an infinite variety of purposes from backing up sites, to building extras, to creating custom deployment workflows. See Creating Custom Extract Tpls for more information.

Custom Teleport Actions

Coming soon: the ability to define Custom Actions when using Teleport as a library in your application.

Contribute

We welcome all contributions to the Teleport application and library. Learn more about the variety of ways you can contribute and how.