Spoor

Gem Version License: MIT

Spoor is a Docker-based development environment for Ruby on Rails applications, inspired by Laravel Sail. It simplifies setting up and managing a Dockerized development environment, allowing you to focus on building your Rails application.

Prerequisites

Before using Spoor, ensure that Docker is installed and running on your system. You can download Docker from https://www.docker.com/.

Installation

Add the gem to your Rails application's Gemfile:

gem "spoor"

Then run:

bundle install

After installing the gem, set up Spoor in your project:

spoor install

This will generate the necessary docker-compose.yml and .env files. If your project already has a Dockerfile, it will not be overwritten unless you use the --force-dockerfile flag:

spoor install --force-dockerfile

Usage

Start the Environment

To start the Spoor environment, run:

spoor up

This will start the Docker containers in the background.

Stop the Environment

To stop the environment, run:

spoor down

Run Rails Commands

You can run Rails commands inside the Docker container using:

spoor rails <command>

For example:

spoor rails console
spoor rails db:migrate

Run Bundler Commands

To run Bundler commands, use:

spoor bundle <command>

For example:

spoor bundle install

Access the Database

To start a PostgreSQL CLI session, run:

spoor psql

Access Redis

To start a Redis CLI session, run:

spoor redis

Start a Shell in the App Container

To start a Bash shell in the app container, run:

spoor bash

Configuration

Environment Variables

The .env file generated during installation contains the following environment variables:

APP_PORT=3000
FORWARD_DB_PORT=5432
FORWARD_REDIS_PORT=6379
WWWUSER=1000
WWWGROUP=1000

You can customize these values to fit your project's needs.

Docker Compose

The docker-compose.yml file is pre-configured with the following services:

  • web: The Rails application.
  • db: PostgreSQL database.
  • redis: Redis for caching or background jobs.

You can modify this file to add or remove services as needed.

Example Workflow

  1. Install Spoor:
   spoor install
  1. Start the environment:
   spoor up
  1. Run database migrations:
   spoor rails db:migrate
  1. Access the Rails console:
   spoor rails console
  1. Stop the environment when done:
   spoor down

Contributing

Contributions are welcome! If you'd like to contribute to Spoor, please follow these steps:

  1. Fork the repository.
  2. Create a new branch for your feature or bug fix.
  3. Commit your changes.
  4. Submit a pull request.

License

Spoor is open-source software licensed under the MIT License.

Support

If you encounter any issues or have questions, please open an issue on GitHub.