docs.modx.pro

Introduction ​

Teleport is an extensible scripting tool for working with one or more local (non-cloud) MODX Revolution installations.

Teleport currently acts mainly as a packaging tool that extends the MODX Transport API and provides commands for extracting and injecting custom MODX site snapshots. It can easily be extended to perform many other MODX-related tasks.

Installation ​

There are several ways to install Teleport. Choose one:

  • Phar - The simplest way to get started is to download the latest teleport.phar and place it in a directory where you can run it. In this distribution, Teleport will create subdirectories profile/ and workspace/ to store generated site profiles and extracted transport packages. The phar distribution includes all dependencies required to use Teleport.

    Note

    You cannot use the Teleport HTTP Server from the phar distribution; it is not included in the phar.

  • Releases - You can download any Teleport release as zip or tar.gz, extract it to a directory (e.g. ~/teleport/), and run composer install there to install dependencies. Project releases are available here.

  • Git Clone - Developers can clone the teleport repository from GitHub and run composer install --dev in the project directory to install dependencies, including those in the require-dev section of composer.json.

Usage ​

Commands ​

You interact with Teleport by running commands with optional arguments.

Teleport provides the following commands:

  • Profile - Generate a JSON profile of a MODX site for use by other commands.

  • Extract - Extract files, data, and/or other artifacts defined in an extract template (extract tpl) from a MODX site and pack them into a transport package that can later be injected into another MODX site.

  • Inject - Inject a transport package produced by Teleport Extract into a MODX site using a given profile.

  • Push - Send a file (source) to a destination.

  • UserCreate - Create a user in a MODX site according to a given profile.

  • Packages/GC - Remove outdated package versions from a MODX site according to a given profile.

  • Workspace/GC - Clean the contents of the workspace/ directory in the Teleport working folder.

CLI usage ​

The simplest way to use Teleport is to run its commands from a Bash shell. See the command documentation for required and optional parameters.

Teleport HTTP Server ​

Teleport (except the phar build) includes a custom HTTP server built on ReactPHP that can run on any port. This lets you run Teleport commands over HTTP, avoiding timeouts and other issues that can occur with long-running processes on typical web server setups.

Extending Teleport ​

Teleport can be extended in several ways. For best results, create your own project that uses Teleport as a library and keep your custom extensions under version control.

The easiest way to start a custom Teleport project is Composer's create-project command using the modxcms/teleport-project boilerplate:

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

See the GitHub project for more on using the boilerplate.

Custom extract templates ​

The Teleport Extract command uses JSON extract templates (extract tpl) to define how a transport package is built from MODX site resources/objects. You can create your own templates for backups, custom packages, add-ons, or development workflows. See Creating custom extract templates (Extract Tpls) for details.

Custom Teleport commands ​

In development

Contribute ​

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