Configuration

Since Trek is a multi-environment add-on, all of it's configuration is managed in a config array. You will need to add the $config['trek'] array to your user/config/config.php file. The only required option is the 'environments' = [] array.

At a minimum, you will need to add the following to your user/config/config.php file. This assumes you have a single remote database, such as your production site, that you are releasing migrations to. All other options will retain their default value.

$config['trek'] = [
    'environments' => [
        'production' => [
            'hostname' => 'prod-db.somedomain.com',
            'database' => '',
            'username' => '',
            'password' => '',
        ],
     ]
 ];

For more advanced configuration, Trek will perform an array_replace() with it's default options (seen below) with what is in your config.php file, thus if you don't need to change anything else like requireBackup, or threshold, and want to use the default values, then you don't need to add them to your config.php file.

Your environments can have any name you want, but the hostname, database, username, and password are all required. The last environment in the array is assumed to be your production environment, regardless of the array key name.

Default configuration

$config['trek'] = [
    /*
    Example databases format. The environment names can be anything you want, but they should be in progressive order,
    e.g. your production environment should probably be last.

    'environments' => [
        'staging' => [
            'hostname' => 'stag-db.somedomain.com',
            'database' => '',
            'username' => '',
            'password' => '',
        ],
        'production' => [
            'hostname' => 'prod-db.somedomain.com',
            'database' => '',
            'username' => '',
            'password' => '',
        ],
     ]
     */
    'environments' => [],

    /*
    The default storage locations for migrations is in your site's user/cache/migrations folder, however, it is
    recommended to use an external storage service such as Amazon S3 to ensure the migration files are not accidentally
    deleted. Alternatively, you can create a folder outside of your user/cache folder to circumvent EE's cache clearing,
    which will delete the contents in the user/cache folder.
     */
    'storage' => [
        'local' => [
            'path' => PATH_CACHE.'migrations',
        ],

        /*
        BoldMinded will not assist in creating or troubleshooting S3 access. You will need to configure your account,
        bucket, user, group, and IAM roles and permissions. If you do not configure permissions correctly, Trek will
        throw an exception error... this is how you will know something is incorrect with the values below, or with
        your user, group, or IAM settings in AWS.

        's3' => [
            'key' => '',
            'secret' => '',
            'bucket' => '',
            'region' => 'us-east-2', aka, "US East (Ohio)" https://docs.aws.amazon.com/general/latest/gr/rande.html
            'path' => '',
        ]
        */
    ],

    // A slower backup routine, but it progressively updates the status bar for more accurate status of the backup.
    // Setting this to false will perform a faster backup in a single http request, but the progress bar will not display.
    'progressiveBackup' => true,

    // Always perform a backup before releasing? This will backup the remote database you are about to release to.
    'requireBackup' => true,

    // How many migrations should be considered too many, and notify the user they should consider releasing?
    'threshold' => 50,

    // Do we push migrations to an external location, or pull them?
    'method' => 'push', // push|pull

    /*
    CAUTION: the following should only be changed if you understand the consequences, and if changed BoldMinded
    may choose to void support requests pertaining to a non-default 'migrate' config array.
     */
    'migrate' => [
        'models' => [
            'Category' => true,
            'CategoryField' => true,
            'CategoryGroup' => true,
            'Channel' => true,
            'ChannelField' => true,
            'ChannelEntry' => true,
            'ChannelFormSettings' => true,
            'ChannelLayout' => true,
            'GlobalVariable' => true,
            'Site' => true,
            'Snippet' => true,
            'SpecialtyTemplate' => true,
            'Status' => true,
            'Template' => true,
            'TemplateGroup' => true,
            'TemplateRoute' => true,
            'Member' => true,
        ],
        'postActions' => [
            'cp\/(addons\/settings)\/(\S+)' => true,
            'cp\/(addons)' => true,
            'cp\/(settings)\/(\S+)' => true,
        ],
        'getActions' => [
            'cp\/(addons\/install)\/(\S+)' => true,
        ],
    ],
];

As noted in the code above, everything in the 'migrate' = [] array can be overridden in your site's user/config/config.php file, but it is not recommended and in most cases not necessary.

For example, if you choose to set 'Member' => false, which means no updates to your exp_members table will be released to a remote environment. There may be a use case for this, and you can choose to go that route, but you're doing so at your own risk.

All support requests assume your migrate array values are identical to the ones above, or what is found in the trek/Config/settings.php file. If the array differs in anyway, BoldMinded may not be able to assist you with your support issue.

Storage

By default Trek saves all migrations and database backups in your user/cache folder, but it is recommended to save migrations to a different location. Trek only uses the default user/cache folder because it should be writable as part of ExpressionEngine's default configuration. It is common for 3rd party add-ons to flush the cache, so you want to avoid having your migrations accidently deleted by another add-on. For this reason it is highly suggested to choose another local directory path, or use an Amazon S3 bucket. You can manually relocate your migration files as needed. For example, if after installing Trek some migrations are saved to the user/cache folder, you may want to move them to a directory above the web root. If your public directory is /var/www/html/public, you may want to save migrations to /var/www/html/migrations. To do that, change the storage['local']['path'] value in your config file, then move the migration files to that new folder. The same process may be taken if you decide to add an S3 bucket in the future. If a migration file goes missing, and an error occurs in a remote environment because a query, or group of queries were not executed, BoldMinded can not assist with such errors.

As noted in the default configuration array, if storage['s3'] is provided, then Trek will save all migrations to the defined bucket. BoldMinded does not provide support in creating and configuring permissions to S3. If you have issues connecting to the bucket, you will receive an error message and will need to self diagnose and fix the issue.

Database backups are not currently saved to S3. The backup routine uses ExpressionEngine's native backup services and by default will save the database backups to the user/cache directory on the server you initiated the backup command on. For example, if you are releasing from a development site to production, and issue the backup and release command from the development server, then the production databases' backup .sql file will be saved in your development server's user/cache directory.