README¶ ↑

<img src=“https://travis-ci.org/ianfleeton/zmey.svg?branch=master” alt=“Build Status” />

Zmey is a template for building e-commerce websites. Fork it, keep what you do need and delete what you don’t. It’s pre-release quality and has not yet been given a version number.

Configuration¶ ↑

Most configuration is kept in the one and only website object stored in the database.

Services (job queues, cache servers, search engines, etc.)¶ ↑

Background tasks are handled by Sidekiq which depends on Redis.

Deployment instructions¶ ↑

Deployment is handled by Capistrano. To deploy to production run the following:

bundle exec cap production deploy

Ruby version¶ ↑

Zmey runs on Ruby 3.1.3.

System dependencies¶ ↑

Uses RMagick and convert, which depend on ImageMagick, for image resizing.

For Ubuntu:

apt-get install libmagickwand-dev imagemagick

For Fedora:

dnf install ImageMagick-devel

For macOS with Homebrew:

brew install imagemagick@6
brew link --force imagemagick@6

wkhtmltopdf¶ ↑

Zmey uses the LGPL wkhtmltopdf tool for generating invoices and other PDF documents from HTML. A macOS binary package can be downloaded from:

https://wkhtmltopdf.org/downloads.html

Installing wkhtmltopdf on Ubuntu 18.04 and later¶ ↑

Download and install with:

wget https://downloads.wkhtmltopdf.org/0.12/0.12.5/wkhtmltox_0.12.5-1.bionic_amd64.deb
sudo apt install ./wkhtmltox_0.12.5-1.bionic_amd64.deb

The binary is installed at /usr/local/bin/wkhtmltopdf but is used by Whenever in a background task so it will need to be included in cron’s PATH. Edit cron jobs with:

crontab -e

Then check that /usr/local/bin is in the path, for example:

PATH=/usr/local/bin:/usr/bin:/bin

Installing wkhtmltopdf on macOS¶ ↑

Download the following from GitHub and run the package installer:

github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox-0.12.5-1.macos-cocoa.pkg

The binary is installed at /usr/local/bin/wkhtmltopdf

Database creation¶ ↑

bin/rails db:create
cp config/secrets.sample.yml config/secrets.yml
# edit config/database.yml and config/secrets.yml as necessary

Database initialization¶ ↑

bundle exec rake db:migrate && RAILS_ENV=test bundle exec rake db:migrate
bundle exec rake db:test:prepare
bundle exec rake db:seed

How to run the test suite¶ ↑

You will need geckodriver to run the JavaScript tests with selenium-webdriver. This can be downloaded from github.com/mozilla/geckodriver/releases

bin/rspec

You can run the tests faster in parallel using parallel_tests which will take advantage of multiple cores:

rake parallel:spec

Be sure to set up multiple databases as described in the README github.com/grosser/parallel_tests

REST API documentation¶ ↑

Zmey can be accessed remotely using its REST API:

• github.com/ianfleeton/zmey/tree/master/api_doc

Webhooks¶ ↑

Zmey uses webhooks to allow:

• non-essential or idiosyncratic behaviour to be implemented as microservices

• external actions to be triggered when events occur

Zmey has some default webhook implementations. To use any or all of these webhooks, run the adapter service: github.com/ianfleeton/zmey-webhook-handlers

List of webhooks¶ ↑

• Image (image_created)

• Order (order_created)

Environment variables¶ ↑

ZMEY_EXCEPTION_RECIPIENT

Email address to which exception notifications will be sent.

ZMEY_REPOSITORY

URL of the git repository. Used when deploying with Capistrano.