modxcms / teleport
An extensible scripting and packaging toolkit for MODX Revolution
Installs: 98
Dependents: 1
Suggesters: 0
Security: 0
Stars: 57
Watchers: 18
Forks: 24
Open Issues: 14
Requires
- php: >=7.0
- ext-json: *
- ext-pdo: *
- react/child-process: ^0.4
- react/event-loop: ^0.4
- react/http: ^0.4
- react/promise: ^2.1
- symfony/filesystem: ^2.4.0
- symfony/finder: ^2.2.0
Requires (Dev)
- symfony/process: ^2.1
Suggests
- ext-ev: It is critical to have this or ext-libevent if you plan to use the server or endpoint listener.
- ext-libevent: It is critical to have this or ext-ev if you plan to use the server or endpoint listener.
- ext-posix: If running teleport from a user different from the php process, it will need to switch to that user.
- aws/aws-sdk-php: Require this with ^2.0 version constraint to enable registration of an S3 stream wrapper.
This package is auto-updated.
Last update: 2024-11-06 16:07:41 UTC
README
Teleport is an extensible scripting toolkit for working with one or more local MODX Revolution installations.
Teleport 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.
MODX Revolution 3.x
Please use the 2.x
branch and releases for MODX 3.x support.
Requirements
In order to use Teleport, your environment must at least meet the following requirements:
- PHP >= 5.4
- MODX Revolution >= 2.1 (MySQL)
You must also be able to run PHP using the CLI SAPI.
NOTE: At the current time, various Teleport Extract tpls only support MySQL deployments of MODX Revolution.
Usage on Linux environments with the PHP posix extension can take advantage of advanced user-switching features.
Teleport strives to be a multi-platform tool, and currently works equally well in Linux and OS X environments. Windows support is unknown at this time; Windows contributors wanted.
Installation
There are several methods for installing Teleport. The easiest way to get started is by installing the Teleport Phar distribution.
IMPORTANT: Using any of the installation methods, make sure you are running Teleport as the same user PHP runs as when executed by the web server. Failure to do so can corrupt your MODX site by injecting and/or caching files with incorrect file ownership.
Download and Install Phar
Create a working directory for Teleport and cd to that directory, e.g.
mkdir ~/teleport/ && cd ~/teleport/
Download the latest teleport.phar
distribution of Teleport into your Teleport working directory.
Create a Profile of a MODX site:
php teleport.phar --action=Profile --name="MyMODXSite" --code=mymodxsite --core_path=/path/to/mysite/modx/core/ --config_key=config
Extract a Snapshot from the MODX site you just profiled:
php teleport.phar --action=Extract --profile=profile/mymodxsite.profile.json --tpl=phar://teleport.phar/tpl/develop.tpl.json
Other Installation Methods
Alternatively, you can install Teleport using the source and Composer. Learn more about using git clone or a release archive.
IMPORTANT: If you want to use the Teleport HTTP Server you cannot use the Phar distribution. You MUST use one of the other installation methods.
Teleport in your PATH
With any of the installation methods you can create an executable symlink called teleport pointing to bin/teleport, or directly to the teleport.phar. You can then simply type teleport
instead of bin/teleport
or php teleport.phar
to execute the teleport application.
Basic Usage
In all of the usage examples that follow, call teleport based on how you have installed the application. For example, if you installed from source, substitute bin/teleport
for php teleport.phar
; if you have created an executable symlink to the teleport.phar, substitute teleport
for php teleport.phar
in the sample commands. The following examples assume you have installed the teleport.phar distribution.
NOTE: Before using Teleport with a MODX site, you will need to create a Teleport Profile from the installed site.
Create a MODX Site Profile
You can create a Teleport Profile of an existing MODX site using the following command:
php teleport.phar --action=Profile --name="MySite" --code=mysite --core_path=/path/to/mysite/modx/core/ --config_key=config
The resulting file would be located at profile/mysite.profile.json and could then be used for Extract or Inject commands to be run against the site represented in the profile.
Learn more about Teleport Profiles.
Extract a Snapshot of a MODX Site
You can Extract a Teleport snapshot from a MODX site using the following command:
php teleport.phar --action=Extract --profile=profile/mysite.profile.json --tpl=phar://teleport.phar/tpl/develop.tpl.json
The snapshot will be located in the workspace/ directory if it is created successfully.
You can also Extract a Teleport snapshot and push it to any valid stream target using the following command:
php teleport.phar --action=Extract --profile=profile/mysite.profile.json --tpl=phar://teleport.phar/tpl/develop.tpl.json --target=s3://mybucket/snapshots/ --push
In either case, the absolute path to the snapshot is returned by the process as the final output. You can use this as the path for an Inject source.
NOTE: The workspace copy is removed after it is pushed unless you pass --preserveWorkspace to the CLI command.
Learn more about the Teleport Extract Action.
Inject a Snapshot into a MODX Site
You can Inject a Teleport snapshot from any valid stream source into a MODX site using the following command:
php teleport.phar --action=Inject --profile=profile/mysite.profile.json --source=workspace/mysite_develop-120315.1106.30-2.2.1-dev.transport.zip
NOTE: If the source is not within the workspace/ directory a copy will be pulled to that location and then removed after the Inject completes unless --preserveWorkspace is passed.
Learn more about the Teleport Inject Action.
UserCreate
You can create a user in a profiled MODX site using the following command:
php teleport.phar --action=UserCreate --profile=profile/mysite.profile.json --username=superuser --password=password --sudo --active --fullname="Test User" --email=testuser@example.com
NOTE: This uses the security/user/create processor from the site in the specified profile to create a user, and the action accepts any properties the processor does.
Learn more about the Teleport UserCreate Action.
Get Started
Learn more about Teleport in the documentation.
License
Teleport is Copyright (c) MODX, LLC
For the full copyright and license information, please view the LICENSE file that was distributed with this source code.