turbovault-app/.github/DEVELOPMENT.md

Development Setup

Environment Management

This project uses Nix with direnv for reproducible development environments.

What You Get Automatically

When you cd into the project directory, direnv automatically provides:

• Ruby 3.3
• Go Task (task runner)
• Docker & Docker Compose
• PostgreSQL 16 client
• Build tools (gcc, make, pkg-config)
• Required libraries (libyaml, libffi, openssl, zlib)

First Time Setup

1. Install Nix (if not already installed)

   sh <(curl -L https://nixos.org/nix/install) --daemon
   

2. Install direnv (if not already installed)

   # macOS
   brew install direnv
   
   # Or via Nix
   nix-env -iA nixpkgs.direnv
   

3. Configure your shell (add to ~/.bashrc or ~/.zshrc)

   eval "$(direnv hook bash)"  # for bash
   eval "$(direnv hook zsh)"   # for zsh
   

4. Allow direnv in project

   cd turbovault-web
   direnv allow
   

That's it! All dependencies are now available.

Quick Start

# Setup everything
task setup

# Start development
task server

# See all available commands
task

Available Tasks

Run task or task --list to see all available commands.

Key tasks:

• task setup - Complete initial setup
• task server - Start Rails server
• task test - Run tests
• task db:reset - Reset database
• task docker:logs - View PostgreSQL logs

Nix Configuration

The shell.nix file defines all dependencies. If you need to add more tools:

1. Edit shell.nix
2. Reload: direnv reload

Troubleshooting

direnv not loading

direnv allow

Missing dependencies

# Reload Nix shell
direnv reload

# Or exit and re-enter directory
cd .. && cd turbovault-web

Update Nix packages

Edit the nixpkgs URL in shell.nix to a newer version if needed.