rails-server

---
name: rails-server
description: Start, stop, restart, and monitor named long-running Rails processes — the Rails server, Sidekiq, Solid Queue, CSS/JS build watchers, and other persistent services. Use whenever the user asks to run the app, restart a service, check logs, or verify the server is up after code changes.
license: MIT
---

# Rails Server — Process Management

Manage named persistent Rails processes: the web server, background job workers, asset build watchers, and any other long-running services the project needs. The equivalent of Replit's workflow manager — bind a name to a command, start it, check its status, read its logs, restart it after changes.

## When to Use

- User asks to "run the app", "start the server", "boot Rails"
- After making code changes that require a server restart
- After adding/changing environment variables
- User asks "is the server running?", "check the logs", "why isn't it starting?"
- Starting background job workers (Sidekiq, Solid Queue, Good Job)
- Setting up a full dev environment with multiple services

## When NOT to Use

- One-off commands (running tests, a migration, a rake task) — use Bash directly
- Debugging application errors — fix the code first, then restart
- Production deployments — use the deploy skill instead

## Named Processes for a Rails App

Define these once per project. Adapt to the project's actual setup.

| Process Name | Command | What it runs |
|-------------|---------|-------------|
| `rails-server` | `bundle exec rails server -p 3000` | Puma web server |
| `sidekiq` | `bundle exec sidekiq` | Sidekiq background workers |
| `solid-queue` | `bundle exec rake solid_queue:start` | Solid Queue workers |
| `good-job` | `bundle exec good_job start` | Good Job workers |
| `css-watch` | `bundle exec rails dartsass:watch` | Dart Sass watcher |
| `js-build` | `node esbuild.config.mjs --watch` | JS build watcher |
| `foreman` | `bundle exec foreman start` | All processes via Procfile |

## Starting Processes

Use `run_in_background: true` for persistent processes. Always assign a meaningful description so you can identify the process later.

### Rails server only
```bash
bundle exec rails server -p 3000 -b 0.0.0.0
```

### Full stack via Procfile (recommended for multi-process projects)
```bash
bundle exec foreman start
```

### Sidekiq alongside Rails
Start both as separate background processes:
```bash
# Terminal 1 — Rails server
bundle exec rails server -p 3000

# Terminal 2 — Sidekiq
bundle exec sidekiq -c 5
```

### Solid Queue (Rails 8 default)
```bash
bundle exec rake solid_queue:start
# or via the Rails runner:
bundle exec rails runner "SolidQueue::Supervisor.start"
```

## Checking Status and Logs

### Is the server running?
```bash
# Check if something is listening on port 3000
lsof -i :3000

# Or check for the Rails pid file
cat tmp/pids/server.pid && ps aux | grep $(cat tmp/pids/server.pid)
```

### Read recent logs
```bash
# Development log (last 50 lines)
tail -50 log/development.log

# Follow log in real time
tail -f log/development.log

# Sidekiq log
tail -50 log/sidekiq.log

# Filter for errors only
grep "ERROR\|FATAL" log/development.log | tail -20
```

### Check background job queue depth
```bash
# Sidekiq
bundle exec rails runner "puts Sidekiq::Queue.all.map { |q| \"#{q.name}: #{q.size}\" }"

# Solid Queue
bundle exec rails runner "puts SolidQueue::Job.where(finished_at: nil).count"
```

## Restarting After Code Changes

### Rails server (Puma)
```bash
# If using pid file
kill -USR2 $(cat tmp/pids/server.pid)

# Or just restart the process
kill $(cat tmp/pids/server.pid) && bundle exec rails server -p 3000
```

### Sidekiq graceful restart
```bash
kill -TSTP $(cat tmp/pids/sidekiq.pid)  # quiet — stop accepting new jobs
kill -TERM $(cat tmp/pids/sidekiq.pid)  # graceful shutdown
bundle exec sidekiq -c 5               # restart
```

### Touch restart (Puma in cluster mode)
```bash
touch tmp/restart.txt
```

## Verifying the Server is Up

After starting, always verify before reporting success:

```bash
# HTTP health check
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/up
# Expect: 200

# If no /up route, try the root
curl -s -o /dev/null -w "%{http_code}" http://localhost:3000/
```

Rails 7.1+ includes a built-in `/up` health check endpoint automatically. For older apps, check the root or any known route.

## Procfile Setup (Multi-Process Projects)

For projects running Rails + workers + asset watchers, define a `Procfile.dev`:

```procfile
web:     bundle exec rails server -p 3000
worker:  bundle exec sidekiq -c 5
css:     bundle exec rails dartsass:watch
js:      node esbuild.config.mjs --watch
```

Start everything with:
```bash
bundle exec foreman start -f Procfile.dev
```

Or use `overmind` for better process management:
```bash
overmind start -f Procfile.dev

# Restart just one process
overmind restart web

# Connect to a process's console
overmind connect web
```

## Common Rails Process Configurations

### API-only Rails app
```procfile
web: bundle exec rails server -p 3000
worker: bundle exec sidekiq -c 10
```

### Rails + Solid Queue (Rails 8)
```procfile
web: bundle exec rails server -p 3000
queue: bundle exec rake solid_queue:start
```

### Rails + webpack (older apps)
```procfile
web: bundle exec rails server -p 3000
webpack: bin/webpack-dev-server
```

### Rails + Vite
```procfile
web: bundle exec rails server -p 3000
vite: bin/vite dev
```

## Workflow: Start the Full Dev Environment

When the user asks to "run the app" or "start the server", follow this sequence:

1. **Check what processes are defined** — look for `Procfile`, `Procfile.dev`, or ask if unknown
2. **Check nothing is already running** — `lsof -i :3000` before starting
3. **Start the process(es)** — prefer `foreman`/`overmind` if Procfile exists, otherwise individual commands
4. **Verify it's up** — `curl http://localhost:3000/up` or equivalent
5. **Report status** — running on port X, log location, how to stop it

## Workflow: Restart After Code Changes

When you've changed server-side code and need to restart:

1. **Identify what's running** — `lsof -i :3000`, check pid files
2. **Graceful stop** — send SIGTERM, not SIGKILL, to let requests finish
3. **Start fresh** — run the same start command
4. **Verify up** — health check before reporting done
5. **Check logs for errors** — `tail -20 log/development.log`

## Best Practices

- **Restart after any server-side code change** — Rails doesn't hot-reload everything (initializers, config, routes need a restart)
- **Use graceful shutdown** — SIGTERM/SIGQUIT not SIGKILL, so in-flight requests complete
- **Keep one Procfile.dev** — single source of truth for which processes the project needs
- **Check logs on failure** — always read the last 20–50 lines before guessing the cause
- **Don't start duplicate processes** — check `lsof -i :PORT` before starting
- **Use `overmind` over `foreman`** if available — better per-process log streaming and individual restart support