Staff Directory

UC Libraries staff directory application. Manages employees and departments with Devise-based authentication.

Stack: Rails 8.1.2, Ruby 3.4.7, MySQL (development/production), SQLite (test). JavaScript via Shakapacker 9.5.0 (webpack 5 + Babel); styles via Sprockets and Sass.

---

Requirements

• Homebrew (macOS)
• Ruby 3.4.7 (e.g. rbenv)
• Rails 8.1.2 (installed via Bundler)
• MySQL (Homebrew on macOS)
• zstd (compression library, for mysql2 native extension)
• Node.js (version in .nvmrc, managed via nvm)
• Yarn (for JavaScript dependencies)

---

Setup (macOS, Apple Silicon)

This project uses MySQL via the mysql2 gem. On macOS (especially Apple Silicon), extra steps may be needed so native extensions build correctly.

1. Install system dependencies

brew install mysql zstd

2. Ruby

rbenv install 3.4.7   # if not already installed
rbenv local 3.4.7
gem install bundler

Configure Bundler to build mysql2 correctly:

bundle config build.mysql2 --with-mysql-config=/opt/homebrew/opt/mysql/bin/mysql_config

3. Node.js

nvm install
nvm use
yarn install

4. Gems and database

bundle install
cp config/database.yml.example config/database.yml   # if needed; edit with your DB settings
bundle exec rails db:create
bundle exec rails db:migrate
bundle exec rails db:seed

5. Create a user (optional)

Option A — Rake task (run in terminal, not in Rails console):

[email protected] PASSWORD=securepassword bundle exec rails users:create

Replace the email and password with the user’s real credentials.

Option B — Rails console:

bundle exec rails console

User.create!(
  email: '[email protected]',
  password: 'securepassword',
  password_confirmation: 'securepassword'
)

Test server only: When db:seed (or rails users:seed_test_user) is run on the test server (libappstest.libraries.uc.edu), a test user is created: [email protected] / password. This user is never created on production (libapps.libraries.uc.edu). See User management below.

---

Running locally

Start MySQL (if not already running):

brew services start mysql

Start the Rails server:

bundle exec rails server

Open http://localhost:3000 in your browser.

For live JavaScript/asset reload during development, in a second terminal:

bin/shakapacker-dev-server

---

Running tests

bundle exec rspec

Test suite uses SQLite (see config/database.yml test configuration).

---

Optional: nvm hook

To automatically switch to the correct Node version when entering the project directory, add this to your shell config (e.g. .zshrc):

# Auto-load node version from .nvmrc if present
autoload -U add-zsh-hook

load-nvmrc() {
  if nvm --version &> /dev/null; then
    if [ -f .nvmrc ]; then
      nvm use &> /dev/null
    fi
  fi
}

add-zsh-hook chpwd load-nvmrc
load-nvmrc

---

User management

You can create and manage users without using the Rails console. Run these commands in your terminal (not inside rails console).

Task	Command
Create or update any user	[email protected] PASSWORD=yourpassword bundle exec rails users:create
Ensure test user on test server only	bundle exec rails users:seed_test_user
Same, on server (use MySQL)	RAILS_ENV=production bundle exec rails users:seed_test_user (or RAILS_ENV=qa on QA)

• users:create — Replace [email protected] and yourpassword with the real email and password. Use this to add a new login or reset a user’s password (e.g. on a server where you can’t run the console). On the server, use RAILS_ENV=production (or qa) so the app uses MySQL: RAILS_ENV=production EMAIL=... PASSWORD=... bundle exec rails users:create.
• users:seed_test_user — Creates or resets the test login [email protected] / password. It only runs on the test server (hostname contains libappstest); on production it does nothing. Run this on the test server after deploy if you need that test account. On the server, set RAILS_ENV so the app uses MySQL (e.g. RAILS_ENV=production bundle exec rails users:seed_test_user or RAILS_ENV=qa for QA).

Test user on test server: When you run db:seed or users:seed_test_user on libappstest.libraries.uc.edu, the app creates (or resets) [email protected] with password password. This is skipped on production (libapps.libraries.uc.edu) so that login never exists there. If your server hostname differs, you can force creation with SEED_TEST_USER=true bundle exec rails users:seed_test_user.

---

Troubleshooting

MySQL connection: Ensure MySQL is running (brew services start mysql). The app expects a database and config as in config/database.yml (use config/database.yml.example as a template if the file is not committed).

Failed to build gem native extension for mysql2: Check that:

• zstd is installed (brew install zstd)
• You are using Ruby 3.4.7 (rbenv local 3.4.7)
• The Bundler mysql2 config points to your MySQL install (e.g. bundle config build.mysql2 --with-mysql-config=/opt/homebrew/opt/mysql/bin/mysql_config for Homebrew on Apple Silicon)

Environment variables: The app uses dotenv-rails. Copy or create .env.development and .env.test as needed (see existing examples in the repo if present). For client-visible values in JavaScript (none are used today), prefer SHAKAPACKER_PUBLIC_* env vars or an explicit allowlist via SHAKAPACKER_ENV_VARS as described in the Shakapacker v9 docs.

Shakapacker & future SWC option: Shakapacker is currently configured for webpack 5 with Babel (javascript_transpiler: 'babel' in config/shakapacker.yml). A future optimization task could switch to SWC by changing javascript_transpiler to "swc" and adding @swc/core and swc-loader, following the official v9 upgrade guide.