$ rails new path/to/new-app --template=path/to/template ---skip-spring --skip-active-record --skip-action-cable
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 # ... 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.
- Choose a Workarea version to use with the new application
- Locate the app template for your chosen Workarea version
- Choose and locate a ruby executable that's compatible with your chosen Workarea version
- Choose and locate a rails executable that's compatible with your chosen Workarea version and ruby executable
- 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.
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.
Locate App Template
For your chosen Workarea version, change to the directory where that gem is installed 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.
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.
Choose a Ruby version within this range and locate its executable, installing it if necessary.
$ 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.
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.
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.
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
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
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
You may also use
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
# 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
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. WebLinc 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 to you by WebLinc.
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.
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:email@example.com https://you:firstname.lastname@example.org added to sources
$ gem sources ***CURRENT SOURCES*** https://rubygems.org/ https://you:email@example.com
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. Within WebLinc, 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 (managed by WebLinc), and your user or group must have at least read permission to the repository you'd like to view or clone (managed by the WebLinc team that maintains the code). 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.
 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.