Git Installation
Last updated Mar 5th, 2021 | Page history | Improve this page | Report an issue
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$287 per month—let's make that $500!
Learn moreInstalling MODX from git is a great way to have the very latest version, and is also required if you're planning to contribute to the development of MODX. It does require a few more steps than a standard installation.
Installation process¶
You'll need to:
- get the files from GitHub
- install composer dependencies
- build the core package
- run the standard setup
Each step is discussed below in detail.
Get the files from GitHub¶
Git clone the revolution repository on GitHub using this syntax:
Note that it's preselecting the 3.x branch and installs into the www directory, you may tweak that to match your desired setup.
Or, if you'd like to contribute back: fork modxcms/revolution to your own GitHub account, clone that repository as "origin" and add the modxcms/revolution repository as a remote called "upstream":
You can switch to a different branch using git checkout <name-of-branch> or git checkout -b 3.x upstream/3.x
Install dependencies with Composer¶
MODX uses Composer to manage internal dependencies that are necessary to run 3.x.
If you do not yet have Composer installed on your system find the installation instructions here. The command below assumes you've installed Composer globally, for example by running mv composer.phar /usr/local/bin/composer after the installation instructions linked above.
Run composer install in the root of the www directory.
It may be necessary from time-to-time to run composer update to make sure you're up-to-date.
Run the build¶
After the dependencies are installed, cd to the _build folder and copy config files there.
Typically, no changes to these files are necessary, but you can change the database connection settings if needed.
Next, run php transport.core.php within the _build folder:
You can also run this from the project root as php _build/transport.core.php if you're previously created the configuration files.
Run Setup¶
Now you are ready to execute the standard setup through the browser, e.g. http://localhost/setup/.
Make sure you check both the "Core package has been manually unpacked" and "Files are already in-place" options when installing from Git. Typically, these are pre-selected for you.
Continue with the setup and then you're all set!
Upgrading Your Local Git Repository After Commits¶
Run the following to update your local git repository after commits.
If you cloned directly from modxcms/revolution, use origin:
You can replace 3.x with any other branch.
It may be necessary to run the build step and setup again after loading changes.
Contributing By Sending Pull Requests¶
If you've fixed a bug or added an improvement, and you're working on a fork of the revolution repository, you can send a pull request to MODX which will be reviewed by the core integrators.
See the Contribute section for more information.
Switching Branches¶
If you want to switch to a different branch (that you have already checked out locally), simply type these commands:
Of course, replacing 2.5.x with the actual name of the branch you want to switch to. After you've done so, run the build and run setup/ again, since different branches might have different databases.
Switching backwards is not always recommended; ie, switching from 2.x (the latest features in development for next minor release) to 2.5.x (the latest patches for next patch release), since database changes cannot be executed in reverse. While no major issues should occur, be careful when doing this or keep your work in separate databases for each branch you work on.
Additional Information¶
Alternative: using create-project¶
The composer create-project command will clone, install dependencies, and build the core in one step.
From the parent directory into which you want to install MODX, run the following command where your_directory is the directory you want MODX installed into. (This can also be . to install into the current, empty, directory.)
If you want to point git at your own fork to contribute back to MODX:
-
git remote add upstream https://github.com/modxcms/revolution.git -
git remote set-url origin {your github repo url} - You may also need:
git remote set-url --push origin {your github repo url}
Now navigate to the standard setup, e.g. http://localhost/setup/ to configure and install MODX.
DYLD error with MAMP on Mac OS X¶
If you use MAMP on Mac OS X, you may get problems (errors about DYLD libraries not being included) when trying to execute transport.core.php from the terminal. This is because the MAMP PHP libraries won't be on the dynamic linker path by default.
To adjust the dynamic linker library path to include the MAMP PHP libraries, run the following command via the terminal:
You can then execute transport.core.php by using the absolute path to the MAMP PHP executable:
Making sure php is in your PATH¶
If you're encountering issues with running the composer or build steps, check if PHP is in your PATH by doing the following:
If you do not get something like the above, please ask someone or Google on how to get it installed.
In some local development environments (e.g. MAMP, XAMMP), you may also want to verify which version of PHP you're using.
If that does not return the path you're expecting, edit the $PATH in your ~/.bash_profile or ~/.zshrc.
Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
Backers
Budget
$287 per month—let's make that $500!
Learn more