GoCanvas Local macOS Development Environment

A step-by-step guide to walk you through the setup & configuration of your local macOS development environment.

Required Files —

You'll need to reach out to one of the developers on your team to get these files, which are excluded from Git.

Database Dump (approximately 20 GB)
aws.rb - Lives in the /appbuilder/config directory.
config_secure.yml - Lives in the /appbuilder/config directory.
database.yml - Lives in the /appbuilder/config directory.
fog_credentials.yml - Lives in the /appbuilder/config directory.

Prerequisites —

Please Note:
You MUST have either the Command Line Tools (CLT) for Xcode, or the full Xcode application installed.

# Install the Command Line Tools (CLT) for Xcode.
$ xcode-select --install

Install Homebrew —

# The Homebrew installation script explains what it will do and then pauses before it does it.
#   Homebrew URL: https://brew.sh/
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Verify the installation.
$ brew help

Git —

Please Note:
You may have Git already installed. To check, run git version in the terminal. If you get an error running the command proceed with the steps below.

Install Git —

$ brew update
$ brew install git

Setup RSA SSH Keys —

# Check for any existing SSH keys.
$ ls -al ~/.ssh

# Generate a new SSH key.
$ ssh-keygen -t rsa -b 4096 -C "[email protected]"

# This creates a new ssh key, using the provided email as a label.
Generating public/private rsa key pair.

# When you're prompted to "Enter a file in which to save the key," press
# Enter. This accepts the default file location.
Enter a file in which to save the key (/Users/you/.ssh/id_rsa): [Press enter]

# At the prompt, type a secure passphrase.
Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]

# Start the ssh-agent in the background.
$ eval "$(ssh-agent -s)"
Agent pid <process-id>

# If you're using macOS Sierra 10.12.2 or later, you will need to modify
# your `~/.ssh/config` file to automatically load keys into the ssh-agent and
# store passphrases in your keychain.
Host *
 AddKeysToAgent yes
 UseKeychain yes
 IdentityFile ~/.ssh/id_rsa

# Add your SSH private key to the ssh-agent and store your passphrase in the
# keychain. If you created your key with a different name, or if you are adding
# an existing key that has a different name, replace id_rsa in the command with the
# name of your private key file.
$ ssh-add -K ~/.ssh/id_rsa

# Copy your public SSH key to your clipboard.
$ pbcopy < ~/.ssh/id_rsa.pub

# Navigate to the "Settings" page in GitLab and select "SSH Keys" from the left sidebar 
# to add your SSH key to GitLab.
#   GitLab URL: https://intgit.gocanvas.com/profile/keys
#
# Paste your key in the "Key" section and give it a relevant "Title".

# Test your SSH connection.
$ ssh -T [email protected]
Welcome to GitLab, @"your_username"!

Clone The Repository —

Open your preferred Terminal application.
Create a new folder on your local computer where you want to store the repository. For example:
```
$ mkdir -p ~/Projects/GoCanvas
```

Clone the appbuilder repository from GitLab:

$ git clone [email protected]:web/appbuilder.git

Navigate to the newly cloned repository:
```
$ cd ~/Projects/GoCanvas/appbuilder
```

OpenSSL —

Install OpenSSL (from Homebrew) —

$ brew install openssl

Configure OpenSSL —

Add OpenSSL to your $PATH

$ echo 'export PATH="$(brew --prefix openssl)/bin:$PATH";' >> ~/.bash_profile

For compilers to find this software you'll need to set the following:

$ echo 'export CPPFLAGS="-I$(brew --prefix openssl)/include";' >> ~/.bash_profile
$ echo 'export LDFLAGS="-L$(brew --prefix openssl)/lib";' >> ~/.bash_profile

For pkg-config to find this software you may need to set the following:

$ echo 'export PKG_CONFIG_PATH="$(brew --prefix openssl)/lib/pkgconfig";' >> ~/.bash_profile

Please Note:
You MUST either Restart Your Terminal or source your shell after running export commands.

To source your current shell session, you can run: exec $SHELL.

Install Ruby —

Install `rbenv` —

$ brew update
$ brew install rbenv ruby-build rbenv-default-gems rbenv-gemset

Add the following to your ~/.bash_profile to initialize rbenv in your $PATH.

# ADD & LOAD `rbenv` EVERY TIME YOU OPEN A TERMINAL.
if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi

## DEFINE THE `rbenv` ROOT DIRECTORY.
RBENV_ROOT=$HOME/.rbenv
## DEFINE WHERE `rbenv` CUSTOM SCRIPTS WILL LIVE.
PATH=$RBENV_ROOT/bin:$PATH

Install `bundler` —

Add bundler to the default-gems list installed with each Ruby version.

$ echo 'bundler' >> $(rbenv root)/default-gems

Install Ruby Versions —

# LIST ALL AVAILABLE RUBY VERSIONS.
$ rbenv install -l

# INSTALL THE LATEST RUBY VERSION.
$ rbenv install 2.6.1

# INSTALL RUBY VERSION 2.3.8.
$ rbenv install 2.3.8

# SET THE GLOBAL VERSION OF RUBY TO BE USED.
$ rbenv global 2.6.1

# INSIDE THE `<project-root>` DIRECTORY, DEFINE THE RUBY VERSION TO USE.
$ cd <project-root>
$ rbenv local 2.3.8
$ rbenv rehash

Select Ruby Version To Use —

# NAVIGATE TO THE DIRECTORY WHERE YOU CLONED THE REPOSITORY.
$ cd <project-root>

# Set the local version of Ruby to use.
$ rbenv local 2.3.8
$ rbenv rehash

Install Rails —

$ gem install rails -v 5.1.6.1

Configure `imagemagick` & `rmagick` —

Install `imagemagick@6` —

$ brew update
$ brew install imagemagick@6 --build-from-source
$ brew info imagemagick@6 # SHOWS PATH(S)

For pkg-config to find this software you may need to set the following:

$ echo 'export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bash_profile
$ echo 'export PKG_CONFIG_PATH="/usr/local/opt/imagemagick@6/lib/pkgconfig:$PKG_CONFIG_PATH"' >> ~/.bash_profile
$ echo 'export PATH="/usr/local/opt/imagemagick@6/bin:$PATH"' >> ~/.bash_profile

Install `rmagick` —

$ gem install rmagick -v '2.15.2'

Please Note:
You MUST either Restart Your Terminal or source your shell after running export commands.

To source your current shell session, you can run: exec $SHELL.

Install MySQL —

We're going to install MariaDB for our local environment because it's a fork of MySQL that has better performance & optimizations.

$ brew update
$ brew install mariadb

After a successful installation, you can start the server and ensure it autostarts in the future with:

$ brew services start mariadb

Run the secure installation setup for MySQL.

# DO NOT set a password for the `root` user during this setup.
$ /usr/local/bin/mysql_secure_installation

Install Sequel Pro —

$ brew update
$ brew cask install sequel-pro

Open the Sequel Pro application.
On the "New Connection Window", select the Socket tab.
Use the following settings to connect to your local MySQL instance:
- Name: localhost
- Username: root
- Password: blank
- Database: blank
- Socket: blank (Default port is 3306)
- Connect Using SSL: [ ]
Click Test Connection to verify your database connection settings.
If the database connection test succeeds, click Save Changes.
Click Connect.

Import The Development Database Dump —

Open the Sequel Pro application.
Navigate to Database -> Add Database to create a new database with the following settings:
- Database Name: rails3_development
- Database Encoding: Default (utf8mb4)
- Database Collation: Default (utf8mb4_general_ci)
Navigate to File -> Import and select the database dump provided to you by your team.

Update The Development Database —

Open your preferred Terminal application.
In terminal, navigate to the root directory for the appbuilder repository you just cloned from GitLab.
```
$ cd ~/Projects/GoCanvas/appbuilder
```
Run rake db:migrate in the terminal to run the database migration script(s).

Running The Application(s) —

Install The Required Gems —

$ cd <project-root>
$ bundle install

Start The server —

$ cd <project-root>
$ rails server

Configure Your IDE(s) —

Visual Studio Code —

Install Visual Studio Code, or optionally you can install Visual Studio Code - Insiders if you'd like to get access to the newer features ahead of time.

$ brew update
$ brew cask install visual-studio-code
$ brew cask install visual-studio-code-insiders

Once installed, open the Visual Studio Code application.
Use the keyboard shortcut ⇧ + ⌘ + P to open the Command Palette. Alternatively, you can navigate to View -> Command Palette to display the Command Palette.
Type in the word Path to the Command Palette input prompt.
Select the following option from the autocomplete list Shell Command: Install code command in PATH. Alternatively, if you installed the "Insiders Edition", this option will be displayed as Shell Command: Install code-insiders command in PATH.
Upon success, you should see the following notification Shell Command: code successfully installed on PATH Alternatively, if you installed the "Insiders Edition", this option will be displayed as Shell Command: code-insiders successfully installed on PATH.

Extensions —

List All Installed Extensions —

code --list-extensions

# For the "Insider's Edition"
code-insiders --list-extensions

"Must Have" Extensions —

dbaeumer.vscode-eslint
eamodio.gitlens
esbenp.prettier-vscode
misogi.ruby-rubocop
rebornix.ruby
shinnn.stylelint

"Nice To Have" Extensions —

aaron-bond.better-comments
alefragnani.Bookmarks
DavidAnson.vscode-markdownlint
dbankier.vscode-instant-markdown
christian-kohler.npm-intellisense
christian-kohler.path-intellisense
donjayamanne.githistory
EditorConfig.EditorConfig
eg2.vscode-npm-script
formulahendry.auto-close-tag
humao.rest-client
mikestead.dotenv
ms-vscode.vscode-typescript-tslint-plugin
mkxml.vscode-filesize
PeterJausovec.vscode-docker
pflannery.vscode-versionlens
redhat.vscode-yaml
Shan.code-settings-sync
steoates.autoimport
WallabyJs.quokka-vscode
yzhang.markdown-all-in-one

"Optional" Extensions —

Equinusocio.vsc-material-theme
lmcarreiro.vscode-smart-column-indenter
ms-vscode.sublime-keybindings
ms-vsliveshare.vsliveshare
naumovs.color-highlight
octref.vetur
PKief.material-icon-theme
pnp.polacode
robertohuertasm.vscode-icons
sdras.night-owl
shyykoserhiy.vscode-spotify
teabyii.ayu
ulthes.theme-firewatch
vscodevim.vim

Code Linting —

We're currently using yarn to manage our linting tasks. Before you can run any of the linters you'll need to run yarn install. In the future these linting tasks will be run in a pre-push git hook managed via Husky, but for now they need to be triggered manually.

`CSS` / `SCSS` Linting —

We're currently using stylelint to lint all CSS/SCSS files in the /app/assets/stylesheets directory, using the stylelint-config-standard configuration as a base.

You can trigger a linting run via yarn run lint:styles

`JavaScript` Linting —

We're using eslint to lint all JS files in the /app/assets/javascripts directory, using the eslint-plugin-prettier preset.

You can trigger a linting run via yarn run lint:js.

Currently this takes a long time to run as we have a lot of libraries in that directory. As we start to move those dependencies out of the assets directory and into gem/packages this should take less and less time.

In the meantime I'd recommend using an ESLint integration with your IDE of choice VSCode, Atom, Webstorm, Sublime.

In the futures we're going to use Prettier to autoformat JS code, which will eliminate a lot of the current warnings/errors.

`Ruby` Linting —

We're currently using Rubocop to lint all .rb files in the app, using the default config.

You can trigger a linting run via yarn run lint:rb

brucebentley/GoCanvas Local Development Environment.md