Patterns and back-end manager

Romanesco installation - Part 1

IMPORTANT

There is a command line installer available now, so no need to follow these steps manually anymore. Go check out Romanesco Seed and save yourself some trouble.

This document covers the installation of MODX through Gitify, up to the initial build. It assumes your server meets the requirements for installing MODX.

Additionally, you need to have Git (v2) and Gitify installed on your system.

Create starting point

  • Clone Romanesco Soil
  • Create empty database
  • Copy / rename .gitify.project to .gitify

Install MODX

Gitify modx:install

Change autoincrement value of database tables

In order to make it easier to maintain and reuse Romanesco elements in different installs, some element types will benefit from a fixed ID. To make sure an element can always receive the same ID from Gitify, we have to reserve a range of IDs for it in the database. We'll do this by hiking up the autoincrement value of the table to a high enough number (in this case: 100000).

To adjust the relevant autoincrement values, run the following queries inside your database:

TRUNCATE TABLE modx_site_templates;

ALTER TABLE modx_access_actiondom AUTO_INCREMENT=100001;
ALTER TABLE modx_access_actions AUTO_INCREMENT=100001;
ALTER TABLE modx_access_category AUTO_INCREMENT=100001;
ALTER TABLE modx_access_context AUTO_INCREMENT=100001;
ALTER TABLE modx_access_elements AUTO_INCREMENT=100001;
ALTER TABLE modx_access_media_source AUTO_INCREMENT=100001;
ALTER TABLE modx_access_menus AUTO_INCREMENT=100001;
ALTER TABLE modx_access_namespace AUTO_INCREMENT=100001;
ALTER TABLE modx_access_permissions AUTO_INCREMENT=100001;
ALTER TABLE modx_access_policies AUTO_INCREMENT=100001;
ALTER TABLE modx_access_policy_template_groups AUTO_INCREMENT=100001;
ALTER TABLE modx_access_policy_templates AUTO_INCREMENT=100001;
ALTER TABLE modx_access_resource_groups AUTO_INCREMENT=100001;
ALTER TABLE modx_access_templatevars AUTO_INCREMENT=100001;

ALTER TABLE modx_actiondom AUTO_INCREMENT=100001;
ALTER TABLE modx_actions AUTO_INCREMENT=100001;
ALTER TABLE modx_actions_fields AUTO_INCREMENT=100001;

ALTER TABLE modx_categories AUTO_INCREMENT=100001;
ALTER TABLE modx_dashboard AUTO_INCREMENT=100001;
ALTER TABLE modx_dashboard_widget AUTO_INCREMENT=100001;
ALTER TABLE modx_document_groups AUTO_INCREMENT=100001;
ALTER TABLE modx_documentgroup_names AUTO_INCREMENT=100001;
ALTER TABLE modx_fc_profiles AUTO_INCREMENT=100001;
ALTER TABLE modx_fc_sets AUTO_INCREMENT=100001;
ALTER TABLE modx_lexicon_entries AUTO_INCREMENT=100001;
ALTER TABLE modx_media_sources AUTO_INCREMENT=100001;
ALTER TABLE modx_member_groups AUTO_INCREMENT=100001;
ALTER TABLE modx_membergroup_names AUTO_INCREMENT=100001;
ALTER TABLE modx_property_set AUTO_INCREMENT=100001;

ALTER TABLE modx_site_htmlsnippets AUTO_INCREMENT=100001;
ALTER TABLE modx_site_plugins AUTO_INCREMENT=100001;
ALTER TABLE modx_site_snippets AUTO_INCREMENT=100001;
ALTER TABLE modx_site_templates AUTO_INCREMENT=100001;
ALTER TABLE modx_site_tmplvar_access AUTO_INCREMENT=100001;
ALTER TABLE modx_site_tmplvars AUTO_INCREMENT=100001;

ALTER TABLE modx_user_group_roles AUTO_INCREMENT=100001;

The autoincrement value also needs to be adjusted for some packages, but that can only be done after the packages are installed.

Install packages

  • Create API key at modmore.com
  • Add ModMore username to .gitify
  • Add ModMore API key to .modmore.com.key file in project root
Gitify package:install --all

Then run the last batch of SQL queries. This will delete the default Collections template (Blog) and update the autoincrement value for the newly installed packages as well:

TRUNCATE TABLE modx_collection_templates;
TRUNCATE TABLE modx_collection_template_columns;

ALTER TABLE modx_clientconfig_group AUTO_INCREMENT=100001;
ALTER TABLE modx_clientconfig_setting AUTO_INCREMENT=100001;
ALTER TABLE modx_collection_settings AUTO_INCREMENT=100001;
ALTER TABLE modx_collection_template_columns AUTO_INCREMENT=100001;
ALTER TABLE modx_collection_templates AUTO_INCREMENT=100001;
ALTER TABLE modx_contentblocks_category AUTO_INCREMENT=100001;
ALTER TABLE modx_contentblocks_default AUTO_INCREMENT=100001;
ALTER TABLE modx_contentblocks_field AUTO_INCREMENT=100001;
ALTER TABLE modx_contentblocks_layout AUTO_INCREMENT=100001;
ALTER TABLE modx_contentblocks_template AUTO_INCREMENT=100001;
ALTER TABLE modx_contentblocks_template AUTO_INCREMENT=100001;
ALTER TABLE modx_migx_config_elements AUTO_INCREMENT=100001;
ALTER TABLE modx_migx_configs AUTO_INCREMENT=100001;
ALTER TABLE modx_migx_elements AUTO_INCREMENT=100001;
ALTER TABLE modx_migx_formtab_fields AUTO_INCREMENT=100001;
ALTER TABLE modx_migx_formtabs AUTO_INCREMENT=100001;
ALTER TABLE modx_quickstartbuttons_buttons AUTO_INCREMENT=100001;
ALTER TABLE modx_quickstartbuttons_sets AUTO_INCREMENT=100001;

Extract packages

  • Gitify extract
  • git add -i (select "Untracked")
  • git commit -m "Extract package data"
  • git reset --hard HEAD

Now, the extract is deleting all the Romanesco elements, BUT!!

By only adding the untracked items with git add -i, the package data is correctly merged with the Romanesco data files.

After that, simply discard the other changes (missing and modified) and your Git repo now contains both the new project data and the Romanesco stuff.

Bonus tip: use this command to go through all the interactive steps in git add -i for you:

echo -e "a\n*\nq\n"|git add -i

http://stackoverflow.com/questions/7446640/adding-only-untracked-files

Build Romanesco

Now we are ready to build the full Romanesco install for the first time!

Gitify build --force

In case something goes wrong or you want to revert for other reasons: Gitify will back up your database inside a _backup folder in your root directory before building.

Change context settings

Of course we don't want Romanesco to decide which domain name our project will use; we want to define our own. That's why the following context settings have been excluded from the build script:

  • set base_url to /
  • set site_url to http://your-domain.loc/
  • set http_host to your-domain.loc
  • set site_start to 1

You'll have to add these keys to every context yourself, in order for them to function correctly.

Change system settings

For Romanesco system settings to become visible, you'll have to create a namespace with the name "Romanesco". No need to fill in any paths here. All system settings are there already in the background, but the Romanesco namespace could not be included with Gitify without also including file paths (which often point to local dev environment).

After you made them reappear, you can set the IDs of some Overview pages, so Romanesco knows where to look for certain files:

  • romanesco.cta_container_id
  • romanesco.global_backgrounds_id
  • romanesco.global_footer_id
  • romanesco.search_result_id

You can also change other settings there, like alter the dist paths if you want to install Semantic UI in a different location, or change the way date / timestamps are being displayed on the website.

Wrapping it up

By now, you will have a MODX installation with 1 page (Home) and not that much to see on the front page itself. In fact, it still looks kind of broken if you visit your site in the browser. That's because the styling needs to be set up also, which we'll cover in part 2 of this installation guide. Nobody said it was easy ;) But don't worry: although the styling has quite a story of its own, step 1 of "applying the basic theme" is a matter of seconds.

Continue to: frontend installation