Installation

In most cases gem install smashing should allow you to use the smashing command to create your dashboards. Installing Ruby, other requirements, and the Smashing dependencies may vary depending on your operating system.

CentOS 7

Official docs are hard to come by.

• DigitalOcean publishes guides on Install Ruby on CentOS 7 but that one's using rbenv
• Install newer Ruby via RPM

Ubuntu

TODO: update to latest Ubuntu LTS

Use Brightbox-supplied packages, they have a Launchpad package repo page and everything.

See https://www.brightbox.com/docs/ruby/ubuntu/

When the smashing installation instantly fails due to being unable to located openssl, run 'apt install build-essential libssl-dev' - as per https://github.com/Smashing/smashing/issues/28#issuecomment-268635142

Troubleshooting

"implicit declaration of function 'thin_http_parser_init' is invalid in C99" when installing Smashing

See this issue for more context. The suggested workaround is one of the following commands (depending on your environment).

gem install thin -v '1.8.0' -- --with-cflags="-Wno-error=implicit-function-declaration"

# or if installing in another directory/prefix

sudo gem install thin -v '1.8.0' -n /usr/local/bin -- --with-cflags="-Wno-error=implicit-function-declaration" local/usr/bin
sudo gem install smashing -n /usr/local/bin

Installation on Raspi Buster

If you have trouble installing Smashing on Raspberry Pi, this issue may help you. The suggested workaround is:

sudo snap install --classic ruby
sudo apt install build-essential
sudo gem install smashing

macos

TODO: help wanted to write this section

Windows

Tested with the latest builds of Node.js and Ruby on Windows 10 and Windows 11 as at 05/10/2021

---

1. Install Node.js 16.10.0 https://nodejs.org/dist/v16.10.0/node-v16.10.0-x64.msi and Ruby+DevKit 3.0.2-1 https://github.com/oneclick/rubyinstaller2/releases/download/RubyInstaller-3.0.2-1/rubyinstaller-devkit-3.0.2-1-x64.exe
2. Ruby component install screen, select 1 and enter, when done press enter again
3. Start commmand prompt and install bundler using: "gem install bundler"
4. Install Smashing using: "gem install smashing"
5. Create new Smashing project using: "smashing new test-dashboard"
6. Go to the newly created project directory and add the following to the gemfile after gem 'smashing': "gem 'tzinfo-data'"
7. Also add: "ENV['TZ'] = 'Pacific/Auckland'" as the very first line to the config.ru file in the project directory - get the correct value for your zone from https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
8. Change to the new project directory and run: "bundle install"
9. Run "gem uninstall eventmachine" and select y to uninstall
10. Run "gem install eventmachine --platform=ruby"
11. Delete Gemfile.lock from the project directory
12. Run "smashing start"

---

These instructions were tested on Windows 10 Pro, with Ruby 3.0.0 (stable at the time of writing). If you are having troubles installing Smashing on Windows, please get in contact in our chat for support. In case you have confirmed that you found a bug in Smashing, create an issue using the existing label "windows".

NOTE: In case you prefer to use the Windows Subsystem for Linux (WSL) it has been tested and confirmed to work with too.

• Use your preferred Ruby installation method; the tested version for this article was 3.0.0 with RubyInstaller
• Make sure you installed a compatible version of Ruby from this list: https://github.com/Smashing/smashing/blob/master/.github/workflows/main.yml

After you have installed Smashing, you can create a dashboard with smashing new test && cd test. Then you will have to complete the following steps:

• Add "gem 'tzinfo-data'" to your project gemfile
• Add "ENV['TZ'] = 'Europe/Oslo'" on the very first line of config.ru. Use correct TZ database from https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Now you should be able to start Smashing with smashing start, and access your dashboards visiting http://localhost:3030/ 🎉

Troubleshooting

Problems starting smashing due to thin/eventmachine

For a long time (over a year at the time of writing) Windows has had issues with eventmachine and thin gems. You may encounter an error message like rb:2:in require': cannot load such file -- 3.0/rubyeventmachine (LoadError)`

Unfortunately, at this time there is no known fix for that in the latest release of eventmachine. There are, however, workarounds:

• Redmine #30513 Unable to load the EventMachine C extension; windows
• oneclick/rubyinstaller2 #96 Unable to load the EventMachine C extension; To use the pure-ruby reactor, require 'em/pure_ruby'

It is assumed that at this point you have created a new dashboard, installed the gems required with bundle install, and tried to start the server.

That means you will have a Gemfile.lock with eventmachine for your environment. Since we want to install the Ruby platform version, first you must uninstall it with gem uninstall eventmachine. Remove other versions too if present.

Now you should be able to install it with gem install eventmachine --platform=ruby. Finally, edit your Gemfile.lock removing any platform specific information. For example, in the test environment used for this article, Gemfile.lock had eventmachine (1.2.7-x64-mingw32) and the solution was to replace it with eventmachine (1.2.7). Now it should use the right version we installed earlier with --platform=ruby without warnings.

Sample dashboard does not load on Windows, shows only a blank screen

You may find this issue after starting your dashboard. The first thing you must do is look at the browser console. If you see a message similar to the following:

TypeError:
no implicit conversion of Hash into Integer
# ./vendor/bundle/ruby/3.0.0/gems/execjs-2.7.0/lib/execjs/external_runtime.rb:176:in `initialize'

Then your version of Ruby and execjs are not compatible at the moment, due to this pending issue. There is an existing pull request that solves it, but it has not been reviewed.

Alternatively, if your error looks like:

Uncaught Error: ExecJS::ProgramError: TypeError: Object doesn't support this property or method
  (in C:/Users/Bruno/Development/ruby/Ruby30-x64/lib/ruby/gems/3.0.0/gems/execjs-2.7.0/lib/execjs/external_runtime.rb:39:in `exec')

Then you are probably missing npm. Install it on Windows (the stable version is always recommended), confirm you can access node and npm from the command line (otherwise close and start the terminal session again), and restart your dashboard.