Crear y arrancar un nuevo proyecto en Ruby on Rails
Vamos a hacer el Hola Mundo de Ruby on Rails: crear un proyecto vacío con rails new, arrancarlo con bin/rails server, verlo funcionar en el navegador y dejar un test que lo compruebe. Rails te da la estructura de la aplicación hecha, como cuando compras un piso con la cocina ya montada: no empiezas por los cimientos, sino por decidir qué guardas en cada armario.
Antes de empezar
Necesitas Ruby instalado. Rails 8.1 pide Ruby 3.2 o superior; compruébalo con:
ruby -v
ruby 3.4.12 (2026-10-23 revision 366f5fdc00) +PRISM [x86_64-linux]
Si no lo tienes, sigue Instalación de Ruby en Ubuntu. Después instala Rails, que es una gema (una librería de Ruby):
gem install rails
rails -v
Rails 8.1.4.1
Paso a paso
- Sitúate en la carpeta donde quieras crear el proyecto.
- Crea el proyecto.
- Entra en su carpeta y arranca el servidor.
- Ábrelo en el navegador.
- Añade una página y un test que la compruebe.
1. Crea el proyecto
rails new mi_app
Rails crea la carpeta mi_app con toda la estructura e instala las dependencias, así que tarda un poco la primera vez. Por defecto usa SQLite como base de datos y no necesitas instalar nada más para empezar. Si quieres otra, indícalo al crear: rails new mi_app --database=postgresql. Cómo ajustarla después: configurar la base de datos en Rails.
Mira lo que ha creado dentro de app/:
cd mi_app
ls app
assets
controllers
helpers
javascript
jobs
mailers
models
views
Tres de esas carpetas aparecen en todo proyecto Rails: models, views y controllers. Son las piezas del patrón modelo vista controlador: los datos, lo que ve el usuario y quien coordina a los dos.
2. Arranca el servidor con rails server
Desde la carpeta mi_app:
bin/rails server
También vale la forma corta, bin/rails s. La terminal se queda ocupada con el servidor y muestra algo así (Rails 8.1.4.1 y Ruby 3.4.12):
=> Booting Puma
=> Rails 8.1.4.1 application starting in development
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 8.0.2 ("Into the Arena")
* Ruby version: ruby 3.4.12 (2026-10-23 revision 366f5fdc00) +PRISM [x86_64-linux]
* Min threads: 3
* Max threads: 3
* Environment: development
* PID: 1304
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop
Lo que importa está en las líneas Listening on: el servidor escucha en el puerto 3000 y solo en tu propio equipo (127.0.0.1 y [::1]).
Así se veía en 2018, con Rails 5.2.0
=> Booting Puma
=> Rails 5.2.0 application starting in development
=> Run `rails server -h` for more startup options
Puma starting in single mode...
* Version 3.12.0 (ruby 2.5.1-p57), codename: Llamas in Pajamas
* Min threads: 5, max threads: 5
* Environment: development
* Listening on tcp://0.0.0.0:3000
Use Ctrl-C to stop
3. Ábrelo en el navegador
Entra en http://localhost:3000. En Rails 8.1 verás la página de bienvenida: el logo de Rails, la pestaña titulada «Ruby on Rails 8.1.4.1» y, abajo, las versiones con las que se ejecuta la aplicación:
Rails version: 8.1.4.1
Rack version: 3.2.8
Ruby version: ruby 3.4.12 (2026-10-23 revision 366f5fdc00) +PRISM [x86_64-linux]
Si trabajas sin navegador (por ejemplo, en un servidor o en un contenedor), compruébalo desde otra terminal con curl, que pide la página y muestra el código de respuesta:
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/
200
Un 200 significa que la página ha respondido bien.
4. Añade tu primera página con su test
La página de bienvenida solo sale mientras no tienes una portada propia. Crea un controlador con una acción; desde otra terminal, en la carpeta mi_app:
bin/rails generate controller Saludos hola
create app/controllers/saludos_controller.rb
route get "saludos/hola"
invoke erb
create app/views/saludos
create app/views/saludos/hola.html.erb
invoke test_unit
create test/controllers/saludos_controller_test.rb
invoke helper
create app/helpers/saludos_helper.rb
invoke test_unit
Haz que sea la portada. En config/routes.rb, añade la línea root justo debajo de la primera:
Rails.application.routes.draw do
root "saludos#hola"
get "saludos/hola"
# …el resto de rutas que ya trae el fichero
end
Sustituye el contenido de app/views/saludos/hola.html.erb por:
<h1>Hola, Rails</h1>
Recarga http://localhost:3000 y verás el saludo. Para que no tengas que comprobarlo a mano cada vez, deja un test. Sustituye el contenido de test/controllers/saludos_controller_test.rb por:
require "test_helper"
class SaludosControllerTest < ActionDispatch::IntegrationTest
test "la portada saluda" do
get root_url
assert_response :success
assert_select "h1", "Hola, Rails"
end
end
bin/rails test
1 runs, 3 assertions, 0 failures, 0 errors, 0 skips
El test pide la portada como lo haría un navegador y comprueba que responde y que el título dice lo que esperas. Rails ya trae Minitest configurado: no hay que instalar nada.
5. Para el servidor
Pulsa Ctrl + C en la terminal donde se está ejecutando.
Errores frecuentes
1. rails: command not found. La terminal no encuentra el programa rails:
bash: rails: command not found
Pasa por una de estas tres causas:
- No has instalado la gema: ejecuta
gem install rails. - Usas un gestor de versiones de Ruby (rbenv, asdf, chruby…) y no está cargado en esa terminal, o has instalado Rails con otra versión de Ruby. Abre una terminal nueva y vuelve a mirar
ruby -v. - La carpeta donde
gemdeja los programas no está en tuPATH. Búscala congem enven la líneaEXECUTABLE DIRECTORY.
Dentro de un proyecto ya creado no lo necesitas: usa siempre bin/rails, que arranca la versión de Rails de ese proyecto.
2. Tu versión de Ruby es demasiado antigua. Este error no avisa. Con Ruby 3.1, gem install rails no falla: instala la última versión de Rails compatible con tu Ruby, que es la 7.2, y no la 8.1:
gem install rails
rails -v
Successfully installed rails-7.2.4
49 gems installed
Rails 7.2.4
Por eso conviene mirar rails -v después de instalar. El error solo aparece si pides la versión exacta:
gem install rails -v 8.1.4.1
ERROR: Error installing rails:
rails-8.1.4.1 requires Ruby version >= 3.2.0. The current ruby version is 3.1.7.
Actualiza Ruby (con tu gestor de versiones o como se explica en Instalación de Ruby en Ubuntu) y vuelve a instalar la gema.
3. El puerto 3000 está ocupado. Hay dos casos y el mensaje te dice cuál es. Si ya tienes ese mismo proyecto arrancado en otra terminal, Rails ni lo intenta:
A server is already running (pid: 1304, file: /tmp/mi_app/tmp/pids/server.pid).
Exiting
Ve a esa terminal y páralo con Ctrl + C. Si el puerto lo usa otro programa (otro proyecto Rails, un servidor de Node…), Puma falla al intentar ocuparlo:
Exiting
/usr/local/bundle/gems/puma-8.0.2/lib/puma/binder.rb:344:in 'TCPServer#initialize': Address already in use - bind(2) for "127.0.0.1" port 3000 (Errno::EADDRINUSE)
Arranca en otro puerto:
bin/rails server -p 3001
* Listening on http://127.0.0.1:3001
* Listening on http://[::1]:3001
O busca el programa que ocupa el 3000 y ciérralo, como se explica en Matar un proceso en Linux.
4. No puedes abrirlo desde otro equipo o desde fuera de un contenedor Docker. Como has visto en la salida, el servidor solo escucha en tu propio equipo. Para aceptar conexiones de fuera, arráncalo con bin/rails server -b 0.0.0.0. Hazlo solo en desarrollo y en una red de confianza.
Cuándo no usar rails new tal cual
rails new sin opciones prepara una aplicación completa para producción: además de modelos, vistas y controladores, trae Dockerfile, configuración de despliegue con Kamal y colas de tareas. Para aprender está bien, pero si solo quieres probar algo, sobra la mitad. Tienes dos alternativas:
| Opción | Qué hace, según rails new --help |
Cuándo |
|---|---|---|
rails new mi_app --minimal |
Prepara una aplicación mínima | Pruebas rápidas y ejemplos |
rails new mi_api --api |
Prepara una pila más pequeña para aplicaciones que solo son una API | Un backend que responde datos a otra aplicación, sin páginas HTML |
Y si lo que necesitas es una página estática o un script, Rails es demasiado: es un marco para aplicaciones web con base de datos.
rails new te da la casa montada; bin/rails test te dice si sigue en pie.
Ejercicio de cinco minutos
- Añade al test un segundo caso que pida
/adiosy espereassert_response :success. Ejecutabin/rails testy comprueba que falla. - Haz que pase: añade la ruta
get "adios", to: "saludos#adios", un métodoadiosvacío enSaludosControllery su vista,app/views/saludos/adios.html.erb. - Vuelve a ejecutar los tests hasta que los dos pasen.
Sigue leyendo
- Crear modelos en Ruby on Rails, el siguiente paso para guardar datos.
- Consola de Ruby on Rails, para probar el código sin pasar por el navegador.
- Migraciones en Ruby on Rails, para crear y cambiar las tablas.
- Generar un CRUD completo con scaffold, para tener listado, alta, edición y borrado de un recurso con un solo comando.
Fuentes
- Getting Started with Rails, guía oficial de Rails 8.1: requisito de Ruby 3.2 o superior, SQLite por defecto y uso de
bin/rails. - rails en RubyGems: 8.1.4.1 es la última versión estable, publicada el 4 de noviembre de 2026.
rails new --helpde Rails 8.1.4.1: opciones--minimal,--apiy--database.
Ejecutado el 12 de noviembre de 2026 en Docker con las imágenes oficiales ruby:3.4 (Ruby 3.4.12) y ruby:4.0 (Ruby 4.0.9), con Rails 8.1.4.1 y Puma 8.0.2: la instalación, rails new, el arranque del servidor, la página de bienvenida, el controlador con su test y los errores de este artículo. Los dos casos de versión de Ruby insuficiente se obtuvieron con la imagen ruby:3.1 (Ruby 3.1.7): gem install rails, que instaló Rails 7.2.4, y gem install rails -v 8.1.4.1, que dio el error. Las salidas son las reales con Ruby 3.4.12. Con Ruby 4.0.9 se repitieron la instalación, rails new, el arranque y la página de bienvenida, con el mismo resultado salvo la versión de Ruby. La salida de 2018 es la del artículo original, con Rails 5.2.0 y Ruby 2.5.1.