README

Still under development - Do not use just yet!

A CLI tool to automate git deployments and builds with fortrabbit. Built to work with most PHP applications (Laravel, Symfony, Wordpress, etc.). Currently only tested with the "Universal Stack" on Fortrabbit.

Usage

Installation

Add the cli project somewhere on your system:

git clone git@github.com:tedslittlerobot/frb-cli.git
cd frb-cli
composer install

Then add an alias to your rc file (~/.zshrc, ~/.bashrc) - something like

alias frb='/{user-home}/projects/frb-cli/frb'

To update, simply cd into the directory, and run:

git fetch
git pull
composer update

NB. Ideally, this will be installable through composer, but I am coming up against some dependancy issues when installing alongside some other common global projects. (Dependancy issues are between illuminate's support and the open source version of illuminate's collections).

Project Setup

Then, at your project root, you can run frb init staging production to set up the .deploy folder, and put in some sample config files for staging and production - you can change the names of your different deployment environments.

Edit the config file(s) with your fortrabbit app name, and other details (see config section below for explanation of options)

Deploy!

For the first time running a git deploy with fortrabbit, you will need to run:

frb deploy:first production

And from then on, you can run:

frb deploy production

Config File

Config files can be created when you first bootstrap your project - frb init staging production will create staging and production config files.

Alternatively, you can use the frb make:env command to add a sample file to your config directory.

NB. There are serveral more config options that are as yet undocumented - mainly to handle the differences between "pro" and "universal" apps.

The sample config file looks like this:

name               : project_name
frb_zone           : deploy.eu2.frbit.com
target_branch      : origin/master
remote_branch      : master

before :
  - php artisan down
  - run : ls -al
    on : local

after :
  - php artisan migrate
  - php artisan up


build_commands :
  - make
  - run: make build
    in: assets/js

build_output :
  - public/build
  - public/build.json

name

This is the app name in fortrabbit.

frb_zone

This is the deploy location of the app. You can get this from the second half of the git address (ie. my_app@deploy.eu2.frbit.com:my_app.git)

target_branch

The local name of the branch you want to deploy from. origin/master is the default, as that will mean that it will only deploy code that has been accepted into the master branch of the remote origin repository on GitHub (or wherever your main repository is - GitLab, BitBucket, etc.)

For example, if you use a forking model, then this may be upstream/master. Or upstream/develop for a staging site.

remote_branch

In most circumstances, this should not be changed. Fortrabbit uses the master branch on its remote repository. If you know what you're doing and you change that for whatever reason, you can change it here. In 99% of cases though, we do not recommend changing the default deploy branch.

build_commands

A list of build commands to be run locally to generate the site's assets. You can specify a directory to run the command in as well - for example,

build_commands :
  - yarn
  - yarn run production
  - run: yarn run && yarn run production
    in: web/app/themes/MyTheme

build_directories

A list of directories that have been generated by the build commands. These will be scp'd up to the server. For example:

build_directories :
  - public/\_css
  - public/\_js
  - public/\_fonts

build_files

A list of files that have been generated by the build commands. These will be scp'd up to the server. For example:

build_files :
  - public/manifest.json

Commands

frb init [...environment1, environment2, etc.]

Sets up the .deploy directory with an appropriate git ignore file (for ignoring logs and other files that you don't want to commit)

Accepts any number of space separated environment names, and will create a sample environment file for each.

frb make:env [new-environment-name]

Creates a sample environment file in the .deploy directory.

frb ssh [environment]

SSH's you into the server for the given environment.

frb deploy [environment]

Runs a full deploy to the given environment.

frb deploy:first [environment]

Runs an initial deploy to the given environment. Must be run before frb deploy will work.

frb deploy:touch [environment]

Runs a code-only deploy to the given environment. Will not build or push any assets.

frb deploy:assets [environment] [--scp-only] [--build-only]

Runs an assets-only deploy - building and pushing assets to the remote server.

frb remote:reset [environment]

Runs a reset command on the remote server. Warning - this is a destructive command!

To Do

Add remote command hooks (maintanence mode during deploy?)
Detect remote server status and run :first if it needs it...!
Detect (isFile()) the build-push targets and run the directory / file task for whichever type it is
Add confirmation to the reset command
E add remote:run command for running single commands
Add proper output logging
Nicer error handling
Git check on valid branch at start as well as clear stage
E get secrets from FRB command
E DB Backup command?
Download / backup existing build directories to .deploy/tmp, then repush them on fail
N init : Bootstrap a project's .deploy folder
N make:env : Create an environment file
E ssh : SSH into the server
E deploy : Deploys to environment
E deploy:first : Run the first deploy
E deploy:touch : Deploys without uploading any assets
E deploy:assets : Push assets only (--scp-only --build-only)
E remote:reset : Reset the remote FRB instance

tlr / frb-cli

Maintainers

Details