Learnings

This app showcases my skills for 37signals. Read more about the project or why you should hire me.

Below are the things I've learned (newest first):

Log New Learning

database deployment-ci environment-setup frontend migration rails-core workflow Clear filter

Deployed changes (Edit link) not appearing on Render

Context: A newly added "Edit" link for learnings appeared locally but not on my deployed Render application, despite logs showing the correct commit deployed and server restarted.
Resolution: I modified the Build Command in Render settings. I changed the order of asset tasks from ...; bundle exec rake assets:precompile; bundle exec rake assets:clean; ... to ...; bundle exec rake assets:clean; bundle exec rake assets:precompile; .... Redeploying with clean before precompile made the link appear.
Learning: The order of asset pipeline tasks in the build command matters, especially with tools like Sprockets or Propshaft. I learned that running assets:clean *before* assets:precompile ensures that stale or conflicting assets from previous builds are removed before new ones are generated. This prevents potential issues where old assets (CSS, JS) might be served by the CDN or web server, causing new code changes or UI elements not to appear as expected in the production environment.

Tags: deployment-ci frontend workflow

Learned on: April 19, 2024 Edit

Render: Running initial migrations on free tier (Build Command workaround)

Context: I needed to run initial database migrations (rails db:migrate) on Render's free tier, which lacks Shell access or explicit Pre-Deploy/Post-Deploy command support. Migrations must run after the code is deployed and dependencies installed but before the server starts taking requests based on the new schema.
Resolution (Workaround): I temporarily added bundle exec rails db:migrate to the *end* of the Build Command in Render settings for the first successful deployment (e.g., bundle install; bundle exec rails assets:precompile; bundle exec rails db:migrate).
Learning: On restricted environments (like PaaS free tiers), essential post-deploy tasks like database migrations might need temporary workarounds, such as including them at the end of the build command. I learned to remember to remove the migration step from the build command after the first successful run to avoid unnecessary migrations on subsequent deploys and potentially slow down builds. Considering using release phase tasks if the platform supports them (Render paid tiers do) is a good idea for the future.

Tags: deployment-ci database migration workflow

Learned on: April 14, 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 deployment stuck (Puma in Build Command)

Context: My deployment got stuck after adding puma to the Build Command in Render settings. The puma command starts a long-running server process, but the Build Command expects tasks that finish (like bundle install, assets:precompile).
Resolution: I removed puma from the Build Command and placed it in the dedicated Start Command field in Render's Web Service settings (e.g., bundle exec puma -C config/puma.rb).
Learning: I learned to distinguish between Build Commands (setup tasks that complete, e.g., installing dependencies, compiling assets) and Start Commands (long-running server processes) in deployment platform configurations like Render.

Tags: deployment-ci workflow

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

Initial Render deployment failed (Static Site vs Web Service)

Context: My initial deployment attempt on Render using the Static Site service type failed. The Static Site service type is only for pre-built HTML/CSS/JS files and does not run a backend server process like Rails requires (Puma).
Resolution: I deleted the Static Site service and created a new Web Service on Render.
Learning: Rails applications require a dynamic backend environment capable of running a server process (like Puma). I learned to use Render's "Web Service" type, not "Static Site", for deploying my Rails app.

Tags: deployment-ci rails-core

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