Platform.sh Quick Starter Guide

This is a quick starter guide to working with platform.sh hosted projects. At the moment this is focused on Mac users deploying Drupal projects.

Important Notes

This document is not endorsed platform.sh team gurus. It's a work-in-progress. Feedback and contributions are welcome.

Official Documentation

The official platform.sh docs are very helpful. Start here and read through it:

https://docs.platform.sh/

Git Reading Further

http://rogerdudler.github.io/git-guide/

Web Development: Getting Started

Most of these setup items are useful for local development, no matter the hosting solution.

Mac Users: Install MAMP

Free version is fine to give access to the latest version of PHP in terminal without disrupting core Mac settings (which can make life bad). https://www.mamp.info/en/downloads/

Mac Users: Make MAMP's PHP the Mac Default PHP (much newer)

Edit user profile file:

nano ~/.profile

Add MAMP's PHP to the PATH variable on any line before export PATH (adjust "php7.1.1" to what actually lives there, make sure 7.0 or higher for Composer requirements):

PATH="/Applications/MAMP/bin/php/php7.1.1/bin:$PATH"

If not seeing an "export PATH", add this line to the bottom of the file:

export PATH

Completely close out of terminal and re-open or force terminal to re-read profile settings with:

source ~/.profile

Test php version (should NOT be 5.x, SHOULD be 7.x)

php -v

Mac Users: Make MAMP's mysql useable in terminal as it is not available by default

Edit user profile file:

nano ~/.profile

Add MAMP's mysql to the PATH variable on any line before export PATH:

PATH="/Applications/MAMP/Library/bin:$PATH"

Completely close out of terminal and re-open or force terminal to re-read profile settings with:

source ~/.profile

Test:

mysql

It should print out general information. Type quit and return to exit.

SSH Access

Setup RSA Keys and sync with platform.sh https://docs.platform.sh/development/ssh.html

Note: SSH access will not be fully available until hosted environments are redeployed. See "Force Redeploy Environment" after setup for details.

Git

Install Git, a primary tool for working with and syncing hosted code with multiple developers. See top downloads section of this page: https://git-scm.com/downloads

Composer

Install composer, used in the Drupal 8 world (along with many other standardized php projects) to install modules and libraries to a local website via terminal. Change to the home directory before proceeding:

cd ~/

Then proceed with instructions at: https://getcomposer.org/download/

Drush

Drush is handy for clearing Drupal cache via Terminal among many other tasks such as syncing non-Git files. Great news: Drush is pre-installed with any local platform website install. More on Drush: http://docs.drush.org/en/8.x/

rsync

A version of this is pre-installed on a Mac with no action required to start.

platform CLI

Install the platform command line interface (CLI), joining the cool kids and make hosting things happen with a few keystrokes. Most hosting tasks are developer centric with the most useful features found in the CLI (not the web admin UI). https://docs.platform.sh/overview/cli.html

For ease of use, add platform CLI to user profile path:

nano ~/.profile

Add platform CLI to path on any line above export PATH

PATH="/Users/USERNAME/.platformsh/bin:$PATH"

Completely close out of terminal and re-open or force terminal to re-read profile settings with:

source ~/.profile

Test installation with:

platform list

Download and Build Local Website

platform primarily works through Git with several additional features available through the platform command. Use platform to accelerate Git items, access databases and more!

Move to a directory where cloned websites from remote environments will live locally. For example:

cd ~/Documents

Get a list of projects that live at platform.sh

platform projects

Select the project and download, confirming folder name that will be created for it when prompted:

platform get PROJECTIDHERE

Build the project, installing all contributed libraries and modules outside of custom code stored in the Git repository:

cd FOLDERNAME
platform build

Download the remote database.

platform db:dump

Find the file that was downloaded using ls:

ls

Example file: "PROJECTIDHERE--master--app--dump.sql"

Create a local database to use for the site:

mysql -u root -proot -e "create database platform_website_org";

Confirm that the database exists:

mysql -u root -proot -e "show databases";

Then overwrite local database with (altering to taste first):

mysql -u root -proot platform_website_org < PROJECTIDHERE--master--app--dump.sql

Enable local configuration settings by copying the local example settings file. This will not be available for Git inclusion (pre-excluded for local flexibility and security). Be aware that the example.settings.local.php file includes various flags and toggles to force Drupal into debug mode. That's a good thing a majority of the time. Configuration can also be altered as needed:

cp web/sites/example.settings.local.php web/sites/default/settings.local.php

Add the following to the bottom of settings.local.php to add a required hash (supplied by platform when remote, not local) and configure local db settings. Edit as needed:

/*
 * hash salt generally provided at runtime on platform.sh
 */

$settings['hash_salt'] = 'juXLp+xMCBiCrCTA*h6DVpveiXn4VH.2Z';

/*
 * Database configuration
 */

$databases['default']['default'] = array (
  'database' => 'platform_website_org',
  'username' => 'root',
  'password' => 'root',
  'host' => 'localhost',
  'port' => '3306',
  'driver' => 'mysql',
  'prefix' => '',
  'collation' => 'utf8mb4_general_ci',
);

Sync the Drupal files directory (image uploads, cache files, other non-dev code items):

vendor/bin/drush rsync @PROJECTIDHERE.BRANCHNAME:%files @PROJECTIDHERE._local:sites/default

Creating A New Feature: Workflow

First, move to the project folder:

cd /local-website-dir

Checkout the master branch locally before attempting to branch it into a new feature branch (unless planning to branch from another branch):

git checkout master

Pull the latest code from the current remote repository:

git pull

Tell platform to create a new branch of the current remote repository via platform. This will also auto-run git branch twitter-bootstrap-install locally and check it out/set as active branch (git checkout twitter-bootstrap-install).

platform e:branch twitter-bootstrap-install

If the branch was already created locally before running the above line, the following example steps would activate a platform environment:

git checkout twitter-bootstrap-install
git push
platform e:activate

Make a few worthy file changes. In this example, Twitter Bootstrap theme was installed using composer. This could also be completed locally by logging into the site and adding via the Drupal site admin area or by visiting the Drupal site, locating a module, downloading, extracting files where they belong (but the following one liner saves time and works better with great platform Composer features, less code to commit):

composer require drupal/bootstrap

To see what changes were made that need to be committed, the following command may be helpful:

git diff

Git add commands could be executed for each file individually, or all added all at once with:

git add .

For a more interactive approach with detailed options of what/what not to stage:

git add -p

Commit changes with helpful message:

git commit -m "Installed Twitter Bootstrap"

Push the changes to the repository on platform.sh. Durring this process, an updated environment is launched to show code changes, replacing the previous environment once launched without downtime (continuous deployment).

git push

Check out the site once the environment has been rebuilt and launched. To list available URLs for the current environment, type:

platform e:url

A few URLs will be listed. Type 0 and hit return to start. It will launch the environment's website in the default browser. This can also be found in the online admin interface if preferred.

Syncing Non-Git Files and Data with Parent Environment

While working on a feature, it may be desired to update non-get files and database from the parent environment for example, to get the latest news posts with their uploaded photos. Confirmations to sync database and files are given separately, so one or the other or both can be synced.

platform e:sync

Make a Snapshot (backup)

Before merging the feature branch into the parent branch, it may be a good idea to make a backup of the parent environment which includes files and database. Snapshots are stored on Platform for 7 days and are helpful in case something goes wrong.

Checkout the parent branch associated with the environment that needs a snapshot, e.g.:

git checkout master

Make a snapshot:

platform snapshot:create

Return to the Git feature branch that will be merged:

git checkout twitter-bootstrap-install

Merge Feature Branch to Master (Live) or Parent Branch

Once the feature is complete, approved and ready to merge with the parent branch, initiate a platform merge. This will also redeploy the parent environment (without downtime):

platform e:merge

Type in 'Y' and hit return to confirm the merge.

Note about databases: As with most hosting solutions and development workflows, Git-related code updates will not affect the parent environment database (or any database). Database configurations and content (usually set when logged into Drupal) will need to be reapplied to the parent environment website.

Delete Feature platform Environment

Make sure to locally checkout the branch that has a remote environment that needs to be deleted. Example:

'git checkout twitter-bootstrap-install'

Then, use platform to delete the remote environment. This will not delete the remote or local Git branch (if adding --no-delete-branch option), only the running environment to save on available hosting plan resources (can be reactivated anytime).

platform e:delete --no-delete-branch

The local branch will still be checked out. Switch to master locally with:

git checkout master

Also a good habit to ensure all is up-to-date locally before proceeding with another feature branch, etc.:

git pull

Activate Environment for Existing Offline Remote Branch

If a Platform environment has been deleted and needs reactivated and/or any remote repository offline branch needs to have an active environment, checkout the local branch and activate with:

git checkout the-feature-branch
platform e:activate

Cool Random Stuff

Force Redeploy Environment

This will force a platform.sh environment to be redeployed, handy if new ssh keys are added or other non-git type account changes (NO environment files will change unless redeployed, a unique platform feature)

git commit --allow-empty -m 'force redeploy'
git push PROJECTIDHERE@git.us.platform.sh:PROJECTIDHERE.git master

platform CLI fun

Open the hosting admin website

platorm web

Composer: Update All Modules and Core with One Line!

composer update

Then:

git add composer.lock
git commit -m "Updated all the things with one line!"
git pull
git push

Prevent Database Dumps From Getting Committed

Open the .gitignore file for the project:

nano .gitignore

If it doesn't already exist, add the following line and save:

*.sql

Commit the change:

git add .gitignore
git commit -m "Ignore DB Dumps created via platform db:dumb"
git pull
git push

Todo

  • Add more "Cool Random Stuff"
  • Everything else that is being forgotten...

Built With

Share this project:

Updates