Monitoring Hatchbox Rails Deployments with Vigilmon: App Health, TCP Checks, SSL Alerts & Deploy Webhooks

Hatchbox is the simple Rails deployment and hosting platform that lets Ruby on Rails teams deploy to their own servers without managing infrastructure complexity. When your Hatchbox-hosted Rails app goes down, an Nginx misconfiguration blocks traffic, or an SSL certificate expires, users hit errors while Hatchbox itself may show the app as healthy. Vigilmon gives you external visibility from outside your server: the Rails app response, health check endpoint, TCP port availability, SSL certificate expiry, and database connectivity — monitoring everything Hatchbox can't see from the inside.

What You'll Build

• An HTTP monitor on your Rails app's health check endpoint
• An HTTP keyword monitor for your application's main page
• A TCP port check for your Nginx/Puma port
• SSL certificate monitoring for your app's domain
• An alerting setup tuned to Rails deployment failure modes

Prerequisites

• A Rails app deployed via Hatchbox on a VPS (DigitalOcean, Hetzner, Vultr, or similar)
• Your app accessible via a domain with HTTPS (e.g., https://myapp.example.com)
• A free account at vigilmon.online

Step 1: Add a Health Check Endpoint to Your Rails App

Hatchbox runs your Rails app behind Nginx proxying to Puma. Before setting up Vigilmon monitors, add a dedicated health check endpoint to your Rails app so Vigilmon can verify the full stack is operational — not just Nginx:

# config/routes.rb
Rails.application.routes.draw do
  get '/health', to: proc { [200, {}, ['OK']] }
  # ... your existing routes
end

The /health route responds to Rack directly, bypassing most middleware. This makes it fast and reliable — it returns 200 only when the Rails process is running. Deploy this change via Hatchbox before proceeding.

Database health: To verify database connectivity in your health check, use a lightweight query instead:

get '/health', to: proc {
  ActiveRecord::Base.connection.execute('SELECT 1')
  [200, {}, ['OK']]
}

This confirms Rails + Puma + PostgreSQL (or MySQL) are all operational.

Verify the endpoint is live after deployment:

curl https://myapp.example.com/health
# Should return: OK

Step 2: Create a Vigilmon HTTP Monitor for the Health Endpoint

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://myapp.example.com/health.
3. Check interval: 60 seconds.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: OK.
7. Click Save.

This monitor catches:

• Puma process crashes after a failed deployment
• Rails boot errors from a bad migration or missing environment variable
• Database connection pool exhaustion
• Hatchbox deployment failures that leave the app in a broken state
• Memory pressure causing the Puma process to be killed by the OS

Alert sensitivity: Set alerts to trigger after 2 consecutive failures to avoid alerts during the ~30-second Puma restart that Hatchbox performs on deployments.

Step 3: Create a Vigilmon HTTP Monitor for the Main Page

The health endpoint confirms Rails is running, but it does not test Nginx configuration, asset serving, or application-level rendering. Add a monitor for your main page:

1. Add Monitor → HTTP.
2. URL: https://myapp.example.com (or a key landing page like /sign_in).
3. Check interval: 2 minutes.
4. Response timeout: 15 seconds.
5. Expected status: 200.
6. Keyword: a unique string from your app's HTML (e.g., your company name or app title).
7. Label: Rails app main page.
8. Click Save.

When the main page monitor fires but the health check is green, Nginx is serving the app but application-level rendering is broken — this can happen after a failed asset precompilation or a partial deployment.

Authentication-gated pages: If your main route redirects to a login page, use the login page URL and set the keyword to something on that page (e.g., Sign in or Log in). A 302 redirect to the login page is healthy; configure expected status as 200 and point the URL directly at the login page.

Step 4: Create a TCP Monitor for the Nginx Port

Hatchbox configures Nginx to listen on port 80 (HTTP) and 443 (HTTPS). A TCP monitor verifies that Nginx is accepting connections at the network level, independently of what HTTP returns:

# Verify Nginx is accepting connections
nc -zv myapp.example.com 443

1. Add Monitor → TCP.
2. Host: myapp.example.com.
3. Port: 443.
4. Check interval: 2 minutes.
5. Response timeout: 10 seconds.
6. Label: App Nginx port.
7. Click Save.

This monitor fires when:

• Nginx has crashed and is not restarting
• A firewall rule on the VPS is blocking port 443
• The server is unreachable at the network level

When the TCP monitor fires but the HTTP monitors appear green (which can't happen if TCP is blocked — they'd both fire), you have a routing issue upstream. If only the TCP monitor fires, Nginx is down. When all monitors fire together, the server itself is unreachable.

Step 5: Monitor SSL Certificates

Hatchbox integrates with Let's Encrypt for automatic certificate renewal via Certbot or similar. Even with auto-renewal configured, renewal can silently fail if:

• Port 80 is blocked (Let's Encrypt HTTP challenge cannot complete)
• The Certbot cron job is misconfigured
• The domain's DNS changed and no longer points to the server

1. Add Monitor → SSL Certificate.
2. Domain: myapp.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

Let's Encrypt certificates expire every 90 days. A 30-day advance warning gives you two full renewal cycles to fix any issue before the certificate expires and your Rails app shows TLS errors to every user.

Check your current certificate expiry: openssl s_client -connect myapp.example.com:443 2>/dev/null | openssl x509 -noout -dates

Step 6: Monitor Your Background Job Queue

Most Rails apps run Sidekiq or GoodJob alongside the web process. Hatchbox manages these as separate processes, but they can die independently of the Rails web server. If your health endpoint includes background job verification, your existing monitors will catch this. For a dedicated check, add an HTTP endpoint that verifies job queue health:

# config/routes.rb
# If you have Sidekiq Web UI mounted:
require 'sidekiq/web'
mount Sidekiq::Web => '/sidekiq'  # protect this with Devise/authentication in production

Or add a lightweight health check:

get '/health/workers', to: proc {
  queue_size = Sidekiq::Queue.new.size
  status = queue_size < 1000 ? 200 : 503
  [status, {}, ["Workers OK, queue: #{queue_size}"]]
}

1. Add Monitor → HTTP.
2. URL: https://myapp.example.com/health/workers.
3. Check interval: 5 minutes.
4. Expected status: 200.
5. Label: Sidekiq worker health.
6. Click Save.

Step 7: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | Health endpoint | Non-200 or OK missing | Check Puma logs on the VPS; redeploy via Hatchbox if needed | | Main page | Non-200 or keyword missing | Check Nginx config and asset precompilation logs | | TCP port 443 | Connection refused or timeout | Check if Nginx is running: systemctl status nginx; check VPS firewall | | SSL certificate | < 30 days to expiry | Check Certbot renewal: certbot renew --dry-run; verify port 80 is open | | Worker health | Non-200 | Check Sidekiq process status via Hatchbox; look for job queue backup |

Alert after: 2 consecutive failures for HTTP monitors (to avoid alerts during Hatchbox deployments). 1 failure for TCP monitors — TCP failures are almost never transient.

Common Hatchbox Deployment Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Puma crash after bad deployment | Health endpoint + main page fire within 60 s | | Failed migration breaks Rails boot | Health endpoint returns 500; TCP port stays green | | Nginx config error after Hatchbox update | TCP port up; HTTP monitors fire with 502 | | Let's Encrypt renewal failure | SSL monitor alerts at 30-day threshold | | VPS out of memory kills Puma | Health endpoint unreachable; TCP may stay green briefly | | Database connection exhausted | Health endpoint (with DB check) returns 503 | | Sidekiq workers stopped | Worker health monitor fires; web monitors stay green | | VPS rebooted without auto-start | All monitors fire simultaneously | | Firewall blocks port 443 | TCP monitor fires; HTTP monitors cannot connect | | DNS TTL cached after server IP change | All monitors fire; update DNS and wait for TTL expiry |

Hatchbox makes Rails deployment straightforward, but it monitors from inside your server — it can't detect Nginx failures, expired SSL certificates, or network-level issues that prevent users from reaching your app. Vigilmon watches from outside, checking your health endpoint, main page, TCP port, and SSL certificate from external probe locations — so you know the moment something fails, not when a user emails support.

Start monitoring your Hatchbox Rails app in under 5 minutes — register free at vigilmon.online.