Skip to content

Commit 2bcdfd2

Browse files
andrewn617andrewn617
committed
Update Getting Start With Rails guide to account for Dev Containers
Create a new guide called Getting Started with Dev Containers and link to it from the original Getting Started guide.
1 parent d366a99 commit 2bcdfd2

File tree

3 files changed

+149
-21
lines changed

3 files changed

+149
-21
lines changed

‎guides/source/command_line.md

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -46,27 +46,28 @@ Rails will set up what seems like a huge amount of stuff for such a tiny command
4646

4747
If you wish to skip some files from being generated or skip some libraries, you can append any of the following arguments to your `rails new` command:
4848

49-
| Argument | Description |
50-
| ----------------------- | ----------------------------------------------------------- |
51-
| `--skip-git` | Skip git init, .gitignore, and .gitattributes |
52-
| `--skip-docker` | Skip Dockerfile, .dockerignore and bin/docker-entrypoint |
53-
| `--skip-keeps` | Skip source control .keep files |
54-
| `--skip-action-mailer` | Skip Action Mailer files |
55-
| `--skip-action-mailbox` | Skip Action Mailbox gem |
56-
| `--skip-action-text` | Skip Action Text gem |
57-
| `--skip-active-record` | Skip Active Record files |
58-
| `--skip-active-job` | Skip Active Job |
59-
| `--skip-active-storage` | Skip Active Storage files |
60-
| `--skip-action-cable` | Skip Action Cable files |
61-
| `--skip-asset-pipeline` | Skip Asset Pipeline |
62-
| `--skip-javascript` | Skip JavaScript files |
63-
| `--skip-hotwire` | Skip Hotwire integration |
64-
| `--skip-jbuilder` | Skip jbuilder gem |
65-
| `--skip-test` | Skip test files |
66-
| `--skip-system-test` | Skip system test files |
67-
| `--skip-bootsnap` | Skip bootsnap gem |
68-
| `--skip-dev-gems` | Skip adding development gems |
69-
| `--skip-rubocop` | Skip RuboCop setup |
49+
| Argument | Description |
50+
|-------------------------|----------------------------------------------------------|
51+
| `--skip-git` | Skip git init, .gitignore, and .gitattributes |
52+
| `--skip-docker` | Skip Dockerfile, .dockerignore and bin/docker-entrypoint |
53+
| `--skip-keeps` | Skip source control .keep files |
54+
| `--skip-action-mailer` | Skip Action Mailer files |
55+
| `--skip-action-mailbox` | Skip Action Mailbox gem |
56+
| `--skip-action-text` | Skip Action Text gem |
57+
| `--skip-active-record` | Skip Active Record files |
58+
| `--skip-active-job` | Skip Active Job |
59+
| `--skip-active-storage` | Skip Active Storage files |
60+
| `--skip-action-cable` | Skip Action Cable files |
61+
| `--skip-asset-pipeline` | Skip Asset Pipeline |
62+
| `--skip-javascript` | Skip JavaScript files |
63+
| `--skip-hotwire` | Skip Hotwire integration |
64+
| `--skip-jbuilder` | Skip jbuilder gem |
65+
| `--skip-test` | Skip test files |
66+
| `--skip-system-test` | Skip system test files |
67+
| `--skip-bootsnap` | Skip bootsnap gem |
68+
| `--skip-dev-gems` | Skip adding development gems |
69+
| `--skip-rubocop` | Skip RuboCop setup |
70+
| `--skip-devcontainer` | Skip Dev Container setup |
7071

7172
These are just some of the options that `rails new` accepts. For a full list of options, type `rails new --help`.
7273

‎guides/source/getting_started.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,9 @@ The Rails philosophy includes two major guiding principles:
6464
Creating a New Rails Project
6565
----------------------------
6666

67+
TIP: New Rails apps come with a preconfigured Dev Container development environment. This
68+
is the fastest way to get started with Rails. For instructions see [Getting Start with Dev Containers](getting_started_with_devcontainer.html)
69+
6770
The best way to read this guide is to follow it step by step. All steps are
6871
essential to run this example application and no additional code or steps are
6972
needed.
@@ -194,6 +197,7 @@ of the files and folders that Rails creates by default:
194197
|.gitignore|This file tells git which files (or patterns) it should ignore. See [GitHub - Ignoring files](https://help.github.com/articles/ignoring-files) for more information about ignoring files.|
195198
|.rubocop.yml|This file contains the configuration for RuboCop.|
196199
|.ruby-version|This file contains the default Ruby version.|
200+
|.devcontainer/|This folder contains the Dev Container configuration|
197201

198202
Hello, Rails!
199203
-------------

‎guides/source/getting_started_with_devcontainer.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.**
2+
3+
Getting Started with Dev Containers
4+
===================================
5+
6+
After reading this guide, you know:
7+
8+
* How to create a new Rails application with the `rails-new` tool
9+
* How to begin working with your application in a Dev Container
10+
11+
--------------------------------------------------------------------------------
12+
13+
The best way to read this guide is to follow it step by step. All steps are
14+
essential to run this example application and no additional code or steps are
15+
needed.
16+
17+
This guide helps you get set up with [Developer Containers (or Dev Containers for short)](https://containers.dev/)
18+
for a full-featured development environment. Dev Containers are used to run your
19+
Rails application in a container, without needing to install Rails or its dependencies
20+
directly on your machine. This is the fastest way to get your Rails application up and running.
21+
22+
This is an alternative to installing Ruby and Rails directly on your machine, which is
23+
covered in the [Getting Started guides](getting_started.md#creating-a-new-rails-project).
24+
Once you have completed this guide, you can continue building your application by following
25+
the Getting Started guide.
26+
27+
Setup and Installation
28+
----------------------
29+
30+
To get set up, you will need to install the relevant tools; Docker, VSCode and
31+
`rails-new`. We'll go into detail about each one below.
32+
33+
### Installing Docker
34+
35+
Dev Containers are run using Docker, an open platform for developing, shipping, and
36+
running applications. You can install Docker by following the installation instructions
37+
for your operating system in the [Docker docs](https://docs.docker.com/desktop/).
38+
39+
Once Docker has been installed, launch the Docker Application to begin running
40+
the Docker engine on your machine.
41+
42+
### Installing VSCode
43+
44+
Visual Studio Code (VSCode) is an open source code editor developed by Microsoft. VSCode's Dev Container
45+
extension allows you to open any folder inside (or mounted into) a container and take advantage of
46+
Visual Studio Code's full feature set. A [devcontainer.json](https://code.visualstudio.com/docs/devcontainers/containers#_create-a-devcontainerjson-file)
47+
file in your project tells VS Code how to access (or create) a development container with a
48+
well-defined tool and runtime stack. It allows you to quickly spin up containers, access terminal
49+
commands, debug code, and utilize extensions.
50+
51+
You can install VSCode by downloading it from [the website](https://code.visualstudio.com/).
52+
53+
You can install the Dev Container extension by downloading it from [the marketplace](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).
54+
55+
### Installing rails-new
56+
57+
`rails-new` generates a new Rails application for you without having to install Ruby on
58+
your machine. It uses Docker to generate the Rails application, thus allowing Docker to
59+
take care of installing the correct Ruby and Rails versions for you.
60+
61+
To install rails-new, follow the installation instructions [in the readme](https://github.com/rails/rails-new?tab=readme-ov-file#installation).
62+
63+
Creating the Blog Application
64+
-----------------------------
65+
66+
Rails comes with a number of scripts called generators that are designed to make
67+
your development life easier by creating everything that's necessary to start
68+
working on a particular task. One of these is the new application generator,
69+
which will provide you with the foundation of a fresh Rails application so that
70+
you don't have to write it yourself. The `rails-new` tool uses this generator to
71+
create a new Rails application for you.
72+
73+
NOTE: The examples below use `$` to represent your terminal prompt in a UNIX-like OS,
74+
though it may have been customized to appear differently.
75+
76+
To use `rails-new` to generate your app, open a terminal, navigate to a directory where you have
77+
rights to create files, and run:
78+
79+
```bash
80+
$ rails-new blog
81+
```
82+
83+
This will create a Rails application called Blog in a `blog` directory.
84+
85+
TIP: You can see all of the command line options that the Rails application
86+
generator accepts by running `rails-new --help`.
87+
88+
After you create the blog application, switch to its folder:
89+
90+
```bash
91+
$ cd blog
92+
```
93+
94+
The `blog` directory will have a number of generated files and folders that make
95+
up the structure of a Rails application. Most of the work in this tutorial will
96+
happen in the `app` folder. For a full rundown of everything in your application
97+
see the full [Getting Started guide](getting_started.md#creating-the-blog-application).
98+
99+
Opening the Blog Application in a Dev Container
100+
-----------------------------------------------
101+
102+
Our new Rails application comes with a Dev Container already configured and ready to use.
103+
We will use VSCode to spin up and work with our Dev Container. Start by launching VSCode
104+
and opening your application.
105+
106+
Once the application opens, VSCode should prompt you that a it has found a Dev Container
107+
configuration file, and you can reopen the folder in a Dev Container. Click the green "Reopen
108+
in Container" button to create the Dev Container.
109+
110+
Once the Dev Container setup is complete, your development environment is ready to use,
111+
with Ruby, Rails, and all your dependencies installed.
112+
113+
You can open the terminal within VScode to verify that Rails is installed:
114+
115+
```bash
116+
$ rails --version
117+
Rails 7.2.0
118+
```
119+
120+
You can now continue with the [Getting Started guide](getting_started.md#hello-rails) and
121+
begin building your Blog application. You will be working within VSCode, which serves as
122+
your entry point to your application's Dev Container, where you can run code, run tests and
123+
run your application.

0 commit comments

Comments
 (0)