Overview¶

This guide outlines the steps necessary to get the application up and running locally for development.

System Requirements¶

Ruby 3.x (managed via rbenv)
Node (managed via nvm)
Docker and Docker Compose
PostgreSQL (provided via Docker)
Redis (provided via Docker)
Node.js 18+ and Yarn

Development Setup¶

1. Clone the Repository¶

git clone <repository-url>
cd <repository-name>

2. Ruby & Node Setup¶

We use rbenv to manage Ruby versions. Install the correct Ruby version:

rbenv install $(cat .ruby-version)
rbenv local $(cat .ruby-version)
gem install bundler
bundle install
nvm use
npm install -g yarn
yarn

3. Environment Variables¶

Copy the example environment file:

cp .env.example .env

Update the .env file with your local configuration values.

4. Docker Services¶

Start the required services using Docker Compose with the development profile:

docker compose --profile dev up -d

This will start: - PostgreSQL database - Redis server

5. Database Setup¶

# Create and setup the database
bundle exec rails db:create
bundle exec rails db:setup

# Run migrations
bundle exec rails db:migrate

6. Install JavaScript Dependencies¶

yarn install

Data Setup and Seeding¶

Loading Seed Data¶

# Load all seed data
bundle exec rails db:seed

Active Admin¶

Accessing Active Admin¶

After setting up the application, you can access Active Admin at: http://localhost:3000/admin

Default admin credentials: - Email: admin@example.com - Password: password

Creating New Admin Users¶

# Via Rails console
bundle exec rails c
> AdminUser.create!(email: 'admin@example.com', password: 'password', password_confirmation: 'password')

# Via rake task
bundle exec rails admin:create_user[email@example.com,password]

Customizing Active Admin¶

Admin resource configurations are in app/admin/
Custom admin styles are in app/assets/stylesheets/active_admin.scss
Admin initializer is at config/initializers/active_admin.rb

Database Management¶

Backup and Restore¶

# Get the backup from prod db if necessary

# Restore from backup
# 1. Stop the application
bundle exec rails server stop

# 2. Drop existing database
bundle exec rails db:drop

# 3. Create empty database
bundle exec rails db:create

# 4. Restore from backup file
docker compose exec -T db pg_restore -U postgres -d database_name < backup.dump

# 5. Run any pending migrations
bundle exec rails db:migrate

# 6. Restart the application
bundle exec rails server

Common Issues and Solutions¶

Database Connection Issues¶

If you can't connect to the database, ensure: 1. Docker containers are running (docker compose ps) 2. Database configuration in config/database.yml matches your .env settings 3. Try resetting the database container:

docker compose --profile dev down
docker compose --profile dev up -d

Redis Connection Issues¶

If Redis connection fails: 1. Check if Redis container is running 2. Verify Redis configuration in config/redis.yml 3. Ensure your .env file has the correct Redis URL

Contributing¶

Create a new branch for your feature
Write tests for your changes
Implement your changes
Submit a pull request

Code Style and Linting¶

We use StandardRb for Ruby code style enforcement:

# Run RuboCop
yarn lint:rb