Tracked Items

ClusterCS offers a completely automated process for creating a full replica of a website in a new environment. The most common case is to create a new development environment for our production website, migrate Production to this new environment, apply all new features, plugins and any other changes that are needed, test to make sure everything works correctly and then migrate the new updated code and database to the Production environment. 

When we’re making a full replica of the original website, meaning a complete copy of the original code and database, the new location would normally contain the same config files that point to the original database location and perhaps other configurations that should be updated in the new environment. 

This is where Tracked Items comes into action to complete the entire migration process automatically by updating specific files to the new environment specific values. The primary purpose of Tracked Items section is to allow the user to define those files that are environment specific and provide special variables that can be used within those files that will take different values based on the environment where they are being migrated. 

It’s worth to mention that if we are using the ClusterCS installers to deploy the initial code, the Tracked Items sections is configured automatically to keep track of the right files and variables so migrations can be performed in a fully automated way.  

Let’s see how we can configure this section if we need custom setups. 

As mentioned before, the primary target for Tracked Items is to define the files that can be automatically updated on migrations. But those files need to use Tracked Variables so let’s see what those are first. 

Tracked Variables can be of 2 kinds: generated and custom.  

Generated variables correspond to databases and users available on the environment that is currently selected. For each selected database a set of 3 variables are being automatically defined: 

• $ENV_DB_NAME_<number>$ – this will contain the database name. The value represents the current environment database name 

• $ENV_DB_HOST_< number >$ – this variable represents the database host, usually “localhost”. Since ClusterCS can be deployed in many clustered configurations, this value is “determined” based on various factors but for complicated scenarios, if the determined value is not correct, you may want to hardcode per environment specific values. 
• $ENV_DB_PORT_<number>$ – this is the database port, usually “3306” and most often not specified in config scripts. If the ClusterCS setup has special configurations such as database proxies, this variable can be used to set the correct port. As in the case of the previous “host” variable, this can be hardcoded to specific per environment values if the ClusterCS determined value on migrations is not what is desired. 

Each selected database user will have 2 variables generated automatically: 

• $ENV_DB_USER_<number>$ – this variable will contain the user name. The value represents the current environment user name. 
• $ENV_DB_PASS_<number>$ – the user password. Values are displayed as “<hidden>” for security purposes but they contain the per environment user password. 

Custom variables are a way to define any other specific values that need to change per environment. 

Both generated and custom variables have the default value that will be used for all environments. In the case of generated variables, those default values are reevaluated for each environment, but custom variables will remain as defined. In order to ensure a specific value is being used for an environment, “Env Custom” button allows defining hardcoded values per environment. 

The <number> in each of the generated variable is automatically determined by the system in order to differentiate the resource they refer to in the case where several databases or users are available. The selected databases are defined in the Tracked Database section and can be “All” selected by default in an unknown setup or can be set to “Custom” and specific database and users selected. It is recommended to use the “Custom” option and only select the databases and users that are actually needed in the migration as these will be selected by default in the “Migrate” tab. 

Once we have the Tracked Variables defined, we can use them in Tracked Files. The files that we want to rewrite with environment specific values on migrations can be defined here and we are required to provide the file path (the path of the file that will be deployed/overwritten) and the file contents. File path will be appended to the environment root, for example, a file path “public_html/config.php” will result in  

/home/<user_name>/web/<env_name>/public_html/config.php 

If we take a simple example for WordPress, the file path in default setups would be “public_html/wp-config.php” and in file contents, we can paste the entire original file and replace the relevant values with variables, ex: 

define(‘DB_NAME’, ‘$ENV_DB_NAME_1$’); 
define(‘DB_USER’, ‘$ENV_DB_USER_1$’); 
define(‘DB_PASSWORD’, ‘$ENV_DB_PASS_1$’); 
define(‘DB_HOST’, ‘$ENV_DB_HOST_1$’);

Once we have the tracked files setup, migrations are now fully automated. When going to “Migrate” page, databases and users will be automatically selected and “Auto” selected for target environment, the option “Rewrite tracked files” enabled by default. Under these conditions, ClusterCS will create a new database and user in the target environment, the defined tracked file paths will be overwritten with the provided file contents and variables in the file contents replaced with environment specific values (ex: the new database name, user name, user password).