Skip to content

Set up a development environment

Download the source package (zip) of the Easy8 version you run from Client Zone and unpack it. All commands below run from its root.

To run Easy8 in containers instead, follow the Docker guide and skip this page.

Prerequisites

You need Ruby 4.0, Node.js 24, Percona Server 8.4 (or MySQL 8.4) and Redis. Install the database and its client library for your system first.

macOS

  1. Install the Xcode Command Line Tools: 
    sudo xcode-select --install
  2. Install MySQL.

On Apple Silicon (M-series), build the trilogy gem against Homebrew libraries before bundle install:

brew install mysql openssl zstd
gem install trilogy -v '2.13' \
  -- --with-mysql-config=$(brew --prefix mysql)/bin/mysql_config \
  --with-ldflags="-L$(brew --prefix zstd)/lib -L$(brew --prefix openssl)/lib" \
  --with-cppflags="-I$(brew --prefix openssl)/include"

Linux (Ubuntu and other Debian-based distributions)

  1. Install MySQL. Read the "Configuring MySQL" step of that guide.
  2. Install the client library: 
    sudo apt-get install libmysqlclient-dev

Windows (WSL)

  1. Open the terminal of the latest Ubuntu LTS in WSL.
  2. Install MySQL.
  3. Install the client library: 
    sudo apt-get install libmysqlclient-dev

Install Ruby and Node.js

  1. Install a Ruby version manager, rbenv or RVM.
  2. Install the Ruby version from .ruby-version (4.0.6). The Gemfile allows ~> 4.0.1.
  3. Install Node.js with nvm and enable Corepack, which provides the Yarn version from package.json (4.14.1): 
    nvm use
corepack enable

Install the application

  1. Install Bundler and the Ruby dependencies: 
    gem install bundler
bundle install
  2. Copy config/database.yml.example to config/database.yml and set the database credentials. See the Rails configuration guide.
  3. Create the database: 
    bundle exec rake db:create RAILS_ENV=development
    On WSL, use bundle exec rake db:create RAILS_ENV=development NAME=''.
  4. Run the migrations of Redmine, the engines and the plugins, and install the Node dependencies: 
    RAILS_ENV=development bundle exec rails easy8:install
    On WSL, use RAILS_ENV=development NAME='' bundle exec rails easy8:install.

If the repository contains an .envrc file and you use direnv, run the Rails commands as direnv exec . <command>.

Start the servers

Start the Vite server for the frontend assets in one terminal and keep it running. Compilation errors appear there.

bundle exec vite dev

Start the Rails server in another terminal:

bundle exec rails server

Open http://localhost:3000/.

Next steps