App Template

Workarea includes a Rails application template, henceforth app template, which you can use with the rails new command to create a new Workarea application.

$ rails new path/to/new-app \
  --template=path/to/template \
  --skip-spring \
  --skip-active-record \
  --skip-action-cable \
  --skip-puma \
  --skip-coffee \
  --skip-turbolinks \
  --skip-bootsnap \ 
  --skip-yarn

The following usage example should work for most developers most of the time. If it does not work for your use case, or you need further explanation, see Usage in Detail.

# Choose a name/path for the application and store it in a variable
$ APP_PATH=new-app

# Choose a Workarea version and store it in a variable
$ WORKAREA_VERSION=3.0.6

# From here, you can copy and paste the remaining command lines

# Create and change to the application path
$ mkdir -p $APP_PATH && cd $APP_PATH

# Create a Gemfile that locks the chosen Workarea version
$ bundle init
$ echo "gem 'workarea', '$WORKAREA_VERSION', source: 'https://gems.weblinc.com'" >> Gemfile

# Install the chosen version of Workarea and a compatible version of Rails
# This is done within the current Ruby version, which we assume is compatible
$ bundle
Fetching gem metadata from https://gems.weblinc.com/....
# ...

# Run `rails new` using Rails from the bundle
# Create the application in the current working directory
# Overwrite the existing Gemfile with the one created by the app template
# Provide the path to the app template within the bundled Workarea
$ bundle exec rails new ./ --force \
  --template=$(bundle show workarea | grep workarea)/docs/guides/source/app_template.rb \
  --skip-spring \
  --skip-active-record \
  --skip-action-cable \
  --skip-puma \
  --skip-coffee \
  --skip-turbolinks \
  --skip-bootsnap \
  --skip-yarn
# ...
Which plugins to include? (ex. clothing,wish_lists) # list plugins to include
Run seed data? (y/n) n # reply 'y' or 'n'
# ...

Usage in Detail

To create a new Workarea application using the app template, complete the following steps.

  1. Choose a Workarea version to use with the new application
  2. Locate the app template for your chosen Workarea version
  3. Choose and locate a ruby executable that's compatible with your chosen Workarea version
  4. Choose and locate a rails executable that's compatible with your chosen Workarea version and ruby executable
  5. Use your chosen ruby and rails executables to run the rails new command with the required arguments and options, including the path to the app template for your chosen Workarea version

Let's look at each of these in turn.

Choose Workarea Version

Choose a Workarea version depending on your need. For example, if you are confirming a bug report, use the version of Workarea from the report. If you are creating a new application for Production, use the latest version of Workarea.

The following examples demonstrate various ways to browse Workarea versions. Each of these examples requires access to Workarea gems or access to Workarea sources.

List All Available Versions

The following shell command prints a list of all available Workarea versions.

$ gem search -a ^workarea$

***REMOTE GEMS***

workarea (3.0.5, 3.0.4, 3.0.3, 3.0.2, 3.0.1, 3.0.0)

Browse All Available Versions on the Web

Alternatively, you can browse Workarea gem versions on the web at https://gems.weblinc.com/gems/workarea.

browsing Workarea versions on the web

Install the Latest Version

The following command installs the latest version of Workarea in the current environment.

$ gem install workarea
Fetching: workarea-3.0.5.gem (100%)
Successfully installed workarea-3.0.5
Parsing documentation for workarea-3.0.5
Installing ri documentation for workarea-3.0.5
Done installing documentation for workarea after 0 seconds
1 gem installed

List Installed Versions

The following example shows which Workarea versions are installed in the current environment.

$ gem list ^workarea$

***LOCAL GEMS***

workarea (3.0.5, 3.0.4)

View Version in Source

If you have Workarea source access, view the version at core/lib/workarea/version.rb.

viewing Workarea version in source

Locate App Template

For your chosen Workarea version, change to the directory where that gem is installed[1] or that source is checked out, or navigate to where that source is hosted. Then find the app template at ./docs/guides/source/app_template.rb.

app template

If browsing the app template at a remote location, copy the file to the environment in which you will be creating the new application.

Displaying Gem Installation Locations using RubyGems

The following example prints information about gems installed through RubyGems, including their installation location.

$ gem list ^workarea$ --details

***LOCAL GEMS***

workarea (3.0.5, 3.0.4)
    Author: Ben Crouse
    Homepage: http://www.workarea.com
    Installed at (3.0.5): /Users/chriscressman/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0
                 (3.0.4): /Users/chriscressman/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0

    The Workarea commerce platform

Choose & Locate Ruby Executable

For your chosen Workarea version, change to the installation directory for workarea-core, or if using source, change or browse to core/. Then view the contents of ./workarea-core.gemspec. The value assigned to required_ruby_version represents the range of compatible Ruby versions for the chosen Workarea version. Refer to the RubyGems Patterns guide if you aren't familiar with conventions used for Ruby version constraints.

The following example retrieves the information from an installed gem.

$ cd ~/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/workarea-core-3.0.5
$ grep required_ruby_version workarea-core.gemspec
  s.required_ruby_version = '>= 2.3.0'

The following screen shot browses to the source on the web.

Ruby version constraint

Choose a Ruby version within this range and locate its executable, installing it if necessary.

The following example lists Ruby versions installed by ruby-build that are managed by rbenv.

$ rbenv versions
  system
  2.2.7
  2.3.0
  2.3.3
  2.3.4
* 2.4.1 (set by /Users/chriscressman/.rbenv/version)

The following example temporarily changes the Ruby version, setting the global ruby executable to a version other than the default.

$ RBENV_VERSION=2.3.4 ruby -v
ruby 2.3.4p301 (2017-03-30 revision 58214) [x86_64-darwin15]

Choose & Locate Rails Executable

For your chosen Workarea version, change to the installation directory for workarea-core, or if using source, change or browse to core/. Then view the contents of ./workarea-core.gemspec. The versions of Rails compatible with this version of Workarea are specified as a dependency in the format add_dependency 'rails', '~> n.n.n'. Refer to the RubyGems Patterns guide if you aren't familiar with conventions used for Ruby version constraints.

The following example retrieves the information from an installed gem.

$ cd ~/.rbenv/versions/2.4.1/lib/ruby/gems/2.4.0/gems/workarea-core-3.0.5
$ grep "'rails'" workarea-core.gemspec
  s.add_dependency 'rails', '~> 5.0.0'

The following screen shot browses to the source on the web.

Rails version constraint

Choose a Rails version within this range and locate its executable within the chosen Ruby version, installing it if necessary.

Under certain circumstances, using the correct rails executable is surprisingly difficult. The Recommended Usage section of this guide demonstrates using Bundler to solve this problem.

Run Rails New

Using your chosen ruby and rails executables, run rails new, providing an argument to specify the path to the new application and an option to specify the path to the chosen Workarea app template. Also provide the option to skip Active Record to improve performance and avoid a few nuisances caused by the application assuming you're using an SQL database.

$ rails new path/to/new-app --template=path/to/template --skip-active-record

Unless you are particularly comfortable using Spring, you should also provide the skip-spring option to skip this feature since it has been a source of confusion and problems in Workarea applications.

$ rails new path/to/new-app --template=path/to/template --skip-active-record --skip-spring

Workarea does not make use of ActionCable, you should also provide the skip-action-cable option to skip this feature.

$ rails new path/to/new-app --template=path/to/template --skip-active-record --skip-spring --skip-action-cable

Furthermore, you can provide the skip-bundle option to defer bundling the new application until after it is created. This is useful if you'd like to modify the new application's Gemfile before bundling, perhaps to specify specific plugin version constraints (see below).

$ rails new path/to/new-app --template=path/to/template --skip-active-record --skip-spring --skip-action-cable --skip-bundle

The app template includes several options that queue off of environment variables, and in some cases, prompts if those environment variables are not set. The follow sections cover the app template options.

Including Plugins

The app template prompts for a list of Workarea plugins to include in the application's Gemfile.

Which plugins to include? (ex. clothing,wish_lists)

Submit an empty string (press Enter) to exclude all plugins.

Provide a comma separated list of plugins to include them in the application's Gemfile. For each plugin you may use the plugin's gem name or repository name, optionally omitting the workarea- prefix and optionally including whitespace after each comma. The following examples are all valid.

workarea-clothing,workarea-wish_lists
workarea-clothing,workarea-wish-lists
clothing,wish_lists
clothing, wish_lists

Each plugin is added to the Gemfile without a version constraint.

# new-app/Gemfile

# ...

source 'https://gems.weblinc.com' do
  gem 'workarea', '~> 3.0.5'
  gem 'workarea-clothing'
  gem 'workarea-wish_lists'
end

You may want to skip bundling the app immediately in order to provide version constraints before bundling (see above).

For unattended usage, set WORKAREA_PLUGINS to provide the list of plugins.

# include plugins
$ WORKAREA_PLUGINS=clothing,wish_lists rails new path/to/new-app --template=path/to/template --skip-spring --skip-active-record --skip-action-cable --skip-bundle
# exclude plugins
$ WORKAREA_PLUGINS= rails new path/to/new-app --template=path/to/template --skip-spring --skip-active-record --skip-action-cable --skip-bundle

Using Local Sources

Set WORKAREA_PLUGINS_ROOT_PATH and/or WORKAREA_PATH to use your local Workarea source code instead of packaged Workarea gems.

The examples below assume the following local source code repositories.

$ tree --noreport -L 1 ~/Code
/Users/You/Code/
├── workarea
├──”€ workarea-clothing
├──€ workarea-copy
└──”€ workarea-wish-lists

Set WORKAREA_PLUGINS_ROOT_PATH to the parent directory of your local source code repositories (~/Code in the example above). Specify the path as an absolute path or a path relative to the current working directory. The app template will use this path for each Workarea gem in the application's Gemfile.

# new-app/Gemfile

# ...

gem 'workarea', path: '/Users/chriscressman/Code/workarea'
gem 'workarea-clothing', path: '/Users/chriscressman/Code/workarea-clothing'
gem 'workarea-wish_lists', path: '/Users/chriscressman/Code/workarea-wish-lists'

The plugin names and paths are derived from the list of plugins you provide to the app template. The Workarea repository is assumed to be named workarea.

To use a different directory name for Workarea, such as workarea-copy from the example above, set WORKAREA_PATH to the path to your Workarea source. Use a path relative to WORKAREA_PLUGINS_ROOT_PATH.

You may also use WORKAREA_PATH without WORKAREA_PLUGINS_ROOT_PATH if you want a local path to Workarea and do not include any plugins when creating the application. In this case, specify WORKAREA_PATH as a path relative to the root of your file system (not absolute).

The following examples demonstrate uses of WORKAREA_PLUGINS_ROOT_PATH and WORKAREA_PATH.

# local workarea (named "workarea") and plugins within ~/Code
$ WORKAREA_PLUGINS_ROOT_PATH=~/Code rails new new-app --template=~/Code/workarea/docs/guides/source/app_template.rb --skip-spring --skip-active-record --skip-action-cable
# using an alternative directory name for workarea
$ WORKAREA_PLUGINS_ROOT_PATH=~/Code WORKAREA_PATH=workarea-copy rails new new-app --template=~/Code/workarea-copy/docs/guides/source/app_template.rb --skip-spring --skip-active-record --skip-action-cable
# using only workarea
$ WORKAREA_PATH=Users/You/Code/workarea rails new new-app --template=~/Code/workarea/docs/guides/source/app_template.rb --skip-spring --skip-active-record --skip-action-cable
# using only workarea, alternate directory name
$ WORKAREA_PATH=Users/You/Code/workarea-copy rails new new-app --template=~/Code/workarea-copy/docs/guides/source/app_template.rb --skip-spring --skip-active-record --skip-action-cable

Seeding

The app template will optionally seed MongoDB and Elasticsearch data after creating the application and prompts for this option.

Run seed data? (y/n)

For unattended usage, set WORKAREA_SEED_DATA as shown in the examples below.

# seed data
$ WORKAREA_SEED_DATA=true rails new path/to/new-app --template=path/to/template --skip-spring --skip-active-record --skip-action-cable
# do not seed data
$ WORKAREA_SEED_DATA=false rails new path/to/new-app --template=path/to/template --skip-spring --skip-active-record --skip-action-cable

Be aware that seeding requires booting the application, and all Workarea dependencies (such as MongoDB and Elasticsearch) must be installed and running in the current environment. Furthermore, the application must be bundled in order to boot, so you cannot seed when using the skip-bundle option.

Accessing Workarea Gems

Most example above require access to Workarea gems. Workarea provides a private gems source at https://gems.weblinc.com for use with RubyGems and Bundler. You must authenticate to this source using credentials provided. Visit https://support.workarea.com to request credentials.

By configuring RubyGems and Bundler with your credentials for this source, your gem and bundle executables can use https://gems.weblinc.com in addition to https://rubygems.org for all gem operations.

Configuring RubyGems

The following examples list the configured RubyGems sources before and after adding an additional source.

$ gem sources
***CURRENT SOURCES***

https://rubygems.org/
$ gem sources --add https://you:abc123@gems.weblinc.com
https://you:abc123@gems.weblinc.com added to sources
$ gem sources
***CURRENT SOURCES***

https://rubygems.org/
https://you:abc123@gems.weblinc.com

Configuring Bundler

Although you can use the bundle config command to configure a gems source in Bundler, the recommended solution is to export BUNDLE_GEMS __WEBLINC__ COM in your shell. Other Workarea tools, such as virtualized training environments and scripts to publish gems, depend on this environment variable being set. Exporting this variable in a shell startup file makes this configuration available to Bundler in addition to these other tools.

# Any shell startup file, such as ~/.profile
export BUNDLE_GEMS __WEBLINC__ COM="you:abc123"

The following example prints Bundler's configuration, which includes the credentials for the gems source provided in the startup file above.

$ bundle config
Settings are listed in order of priority. The top value will be used.
gems.weblinc.com
Set via BUNDLE_GEMS __WEBLINC__ COM: "you:abc123"
Set for the current user (/Users/chriscressman/.bundle/config): "you:abc123"

Accessing Workarea Sources

Source code for Workarea software is hosted at https://stash.tools.weblinc.com. The preferred name for this service is Stash, but you will also see it referred to as Bitbucket and Bitbucket Server. This software is part of the Atlassian suite, and as such, user accounts are managed in Crowd.

To access Workarea sources, you must have a Crowd account, and your user or group must have at least read permission to the repository you'd like to view or clone. To request access to repository access, visit https://support.workarea.com. Furthermore, Workarea repositories are secured by SSH, so to access source code beyond the web interface, you need to create a key pair and add your public key to your Stash account.

The first time you connect to Stash via SSH, your SSH client will display the SSH fingerprint for the server you are connecting to and will ask if you want to continue. To find the RSA fingerprint for Stash, log in to Stash and view the SSH Keys page in your account. The screenshot below highlights the RSA fingerprint. If the fingerprints match, type yes to continue.

RSA fingerprint for Stash

Notes

[1] If you'd prefer to avoid installing the gem, use gem fetch and gem unpack to fetch and unpack the gem contents to a location of your choice.