Til Tracker

Routing Error for static files (`/documents/cv.pdf`) in development

Issue: Linking to PDFs I placed in public/documents/ resulted in No route matches [GET] /documents/cv.pdf in the development environment.
Cause: By default, the Rails development environment often doesn't serve static files from the public directory. This is typically enabled only in production for performance reasons.
Resolution:
1. I enabled static file serving in development by setting config.public_file_server.enabled = true in config/environments/development.rb.
2. I ensured the PDF files were correctly placed in til_tracker/public/documents/.
3. I restarted the Rails server (./bin/dev).
Learning: To serve static assets (like PDFs, images) directly from the public folder in the development environment, I learned I must explicitly set config.public_file_server.enabled = true in config/environments/development.rb and restart the server. In production, this is usually handled by the webserver (like Nginx or Apache) or enabled by default in production.rb.

Tags: rails-core environment-setup frontend error-handling debugging

Learned on: April 22, 2024 Edit

Clarification: Use `./bin/dev` not `rbenv exec bin/dev`

Context: I clarified in README.md that ./bin/dev is the preferred command to start the development server, after confirming rbenv exec bin/dev causes issues (previously logged Apr 8 & Apr 13).
Resolution: I updated README.md to reflect ./bin/dev as the primary command and added a note about specifying the PORT environment variable if needed (e.g., PORT=8000 ./bin/dev).
Learning: I learned to ensure documentation (README.md, PLANNING.md) accurately reflects the working commands discovered during troubleshooting and development, including common variations like specifying a port or necessary environment variables. Keeping documentation consistent with learned best practices for my specific project environment is important.

Tags: workflow documentation readme rbenv bin/dev environment-setup

Learned on: April 15, 2024 Edit

`FactoryBot::DuplicateDefinitionError` on dev server startup

Context: My development server (./bin/dev) failed to boot, reporting FactoryBot::DuplicateDefinitionError: Factory already registered: learning.
Cause: The factory_bot_rails gem was included in the group :development, :test do block in the Gemfile. This caused FactoryBot's Railtie to load factory definitions (spec/factories/*.rb) during development environment initialization (e.g., via Spring or initial boot), potentially conflicting with other initializers or running twice.
Resolution: I moved gem "factory_bot_rails" exclusively to the group :test do block in the Gemfile and ran rbenv exec bundle install.
Learning: I learned that gems intended solely for testing (like factory_bot_rails, shoulda-matchers, capybara) should typically only be included in the :test group in the Gemfile. Including them in :development can lead to unexpected behavior, errors during server startup, or unnecessary loading as their initializers might run inappropriately or cause conflicts.

Tags: testing dependencies factorybot gemfile environment-setup workflow

Learned on: April 15, 2024 Edit

Render: Continued socket errors (Missing `DATABASE_URL`)

Context: I continued to see socket connection errors even with the production environment confirmed. The DATABASE_URL environment variable itself was missing from the Web Service configuration.
Cause: The Render PostgreSQL database service was not automatically linked to the Web Service when I created it, or the link was broken/not established. Render doesn't always automatically inject the DATABASE_URL from a linked DB into the web service environment.
Resolution: I manually located the database 'Internal Connection String' from the database service's page in Render and added it as the DATABASE_URL environment variable to the Web Service settings.
Learning: I learned to verify that the DATABASE_URL environment variable exists and is correctly populated in the deployment environment. If using linked services (like Render databases), I need to ensure the link is active and injecting the variable, or manually provide the connection string if necessary.

Tags: deployment-ci database environment-setup

Learned on: April 14, 2024 Edit

Render runtime errors (`ActiveRecord::ConnectionNotEstablished` - Socket)

Context: I encountered runtime errors (ActiveRecord::ConnectionNotEstablished) trying to connect via local socket (/var/run/postgresql/.s.PGSQL.5432). Despite config/database.yml being configured for DATABASE_URL, Rails was not running in the production environment, causing it to default to socket connections defined elsewhere in database.yml (likely development).
Cause 1: The Start Command initially included -e ${RACK_ENV:-development} or similar, overriding the production setting.
Cause 2: The RAILS_ENV environment variable was missing or incorrect in Render.
Cause 3: Puma reported Environment: development or deployment even with RAILS_ENV=production set, suggesting RACK_ENV might take precedence or another override was present.
Resolution:
* I changed the Start Command to bundle exec puma -C config/puma.rb (removing explicit -e).
* I explicitly added both RAILS_ENV=production and RACK_ENV=production environment variables in Render's UI.
Learning: I learned to ensure the Rails environment is correctly set to production on the deployment server via RAILS_ENV (primary) and potentially RACK_ENV environment variables. I need to verify the environment Puma/Rails reports in the logs and check the Start Command for overrides.

Tags: deployment-ci database environment-setup

Learned on: April 14, 2024 Edit

Render build failures (`DatabaseNotDefined`)

Context: My builds failed related to database configuration (ActiveRecord::DatabaseConfigurations::DatabaseNotDefined: Database configuration "'default'" not defined). The default config/database.yml included a complex multi-database production setup that was incompatible with Render's standard DATABASE_URL environment variable approach.
Resolution: I simplified the production: block in config/database.yml to inherit defaults and rely solely on the DATABASE_URL environment variable provided by Render (e.g., `production:
<<: *default
url: <%= ENV['DATABASE_URL'] %>). Rails 7+ often handles DATABASE_URL` automatically if the production block is simple enough or just inherits defaults.
Learning: For standard PaaS deployments (like Render, Heroku), I learned to configure the production database section in config/database.yml to use the DATABASE_URL environment variable provided by the host. Avoid complex hardcoded setups unless explicitly needed and configured on the host. Rely on Rails conventions.

Tags: deployment-ci database environment-setup

Learned on: April 14, 2024 Edit

Persistent CI failure: `importmap:audit` task not found

Context: The CI job scan_js consistently failed with errors indicating the task importmap:audit could not be found or run, even using rails, rake, or bundle exec.
Resolution: I verified locally using rake -T | grep importmap that the importmap:audit task was not available in my project's current setup (Rails version, importmap-rails version). I removed the entire scan_js job from .github/workflows/ci.yml.
Learning: Before troubleshooting CI command failures extensively, I learned to verify that the command/task actually exists and is available in my project's specific gem/framework versions (rake -T, rails -T). I shouldn't assume standard template tasks are always applicable or available.

Tags: deployment-ci workflow environment-setup

Learned on: April 14, 2024 Edit

Subsequent CI failures (Rubocop style / Importmap command)

Context: After fixing initial errors, CI failed again. Rubocop reported style violations (whitespace, empty lines), and bin/rails importmap:audit resulted in an "Unrecognized command" error.
Resolution:
* Rubocop: I decided to run rbenv exec bundle exec rubocop -A locally before committing to auto-correct style violations. I added this as a step in PLANNING.md/README.md.
* Importmap Audit: I changed the command in .github/workflows/ci.yml to bundle exec rails importmap:audit to ensure the task runs within the correct bundle context.
Learning: Regularly running the linter (rubocop -A) locally prevents style errors from reaching CI. I learned that using bundle exec before Rails/Rake tasks in CI can sometimes resolve environment or command recognition issues by ensuring the command runs within the context of the installed gems.

Tags: deployment-ci workflow environment-setup

Learned on: April 14, 2024 Edit

GitHub Actions CI failing (Rubocop/Importmap missing)

Context: My PR checks failed with errors related to rubocop not being found and bin/importmap command not existing.
Resolution:
* I uncommented the rubocop-rails-omakase gem in the Gemfile (group :development, :test) to include RuboCop in the bundle for the CI environment.
* I corrected the importmap audit command in .github/workflows/ci.yml from bin/importmap audit to the standard Rails command bin/rails importmap:audit.
Learning: I learned that CI environments install dependencies based strictly on Gemfile.lock. I need to ensure all required gems (especially for linting/testing steps) are included in the correct groups. I also learned to double-check the exact commands used in CI workflows against standard Rails commands or existing binstubs.

Tags: deployment-ci environment-setup workflow

Learned on: April 14, 2024 Edit

Inconsistent need for `rbenv exec` with `bin/dev`

Context: rbenv exec bin/dev failed (rbenv: bin/dev: command not found), repeating a similar issue from Apr 8.
My Observation: The bin/dev script itself likely works fine when I execute it directly (./bin/dev) if my PATH includes the rbenv shims correctly.
Learning: The need for rbenv exec seems inconsistent, particularly with binstubs like bin/dev. This likely points to subtle issues in my shell's rbenv init configuration or PATH setup. While rbenv exec is a workaround for rails, bundle, rake, it might interfere with correctly shimmed binstubs. I decided to recommend ./bin/dev as the primary way to start the server, potentially falling back to rbenv exec if ./bin/dev uses the wrong Ruby, and documented the preferred method.

Tags: environment-setup workflow documentation

Learned on: April 13, 2024 Edit

Repeated `gem install bundler` failure (`Gem::FilePermissionError`)

Context: gem install bundler:2.6.7 failed again with Gem::FilePermissionError. The command was still running in the context of the system Ruby, attempting to write to protected system directories (/Library/Ruby/Gems/2.6.0).
Resolution: I had to ensure my terminal session correctly activated the rbenv Ruby version (3.2.2) *before* running gem install bundler -v 2.6.7 and subsequent bundle install.
Learning: Persistent permission errors during gem install strongly indicate the wrong Ruby environment is active. I learned to verify my rbenv (or similar) setup and activation (ruby -v, which ruby, which gem). Using rbenv exec gem install ... can sometimes bypass activation issues but doesn't fix underlying environment problems if my shell init is broken.

Tags: environment-setup workflow error-handling

Learned on: April 13, 2024 Edit

Repeated `bundle install` failure (bundler version mismatch)

Context: After cleanup, bundle install failed again (Could not find 'bundler' (2.6.7)...). My shell environment was attempting to use system Ruby's bundler, not the one associated with my project's rbenv version (3.2.2), and the required version (2.6.7) wasn't installed for the active Ruby.
My Attempt: gem install bundler:2.6.7.
Learning: Gemfile.lock dictates the required Bundler version. I learned to ensure this version is installed *for the correct, active Ruby version* managed by rbenv (or similar). Verifying ruby -v and which gem is key.

Tags: environment-setup

Learned on: April 13, 2024 Edit

Project cleanup: Removed unused gems

What I Did: Reviewed Gemfile and removed unused gems.
Details: I identified and removed solid_queue (no jobs), solid_cable (no Action Cable), jbuilder (no JSON API), kamal (not deployment target), rubocop-rails-omakase (no active linting at the time). Ran bundle install.
Learning: I learned to keep the Gemfile lean by removing dependencies that aren't actively used to speed up builds, reduce potential conflicts, and simplify the project. Running bundle install after changes is important.

Tags: workflow environment-setup

Learned on: April 13, 2024 Edit

`rbenv exec rails db:create` failed (`ActiveRecord::ConnectionNotEstablished`)

Context: rbenv exec rails db:create failed with ActiveRecord::ConnectionNotEstablished. The PostgreSQL server was not running or accessible.
Resolution: I started the PostgreSQL service (e.g., brew services start postgresql).
Learning: I learned to ensure required background services like databases are running before Rails attempts to connect to them (e.g., rails db:create, rails server). Checking service status (brew services list) is important.

Tags: database environment-setup rails-core