Update Getting Start With Rails guide to account for Dev Containers

[andrewn617]

Motivation / Background

In Rails 7.2, new apps will be generated with a Dev Container already set up. We also introduced the rails-new tool which allows an app to be generated a machine that does not have Rails, or even Ruby, installed.

This PR updates the Getting Started with Rails guide to account for rails-new and working with Dev Containers in VS Code.

Detail

I updated the "Installing Rails" section of this guide to instead give instructions for installing Docker, VScode and rails-new. The "Creating the Blog Application" has also been updated to show usage of rails-new instead of the rails new command. And, I added a section about opening the app in a dev container within VSCode.

I moved the old section about installing rails and ruby locally to it's own guide, Installing Rails. That guide then links back to the getting started guide's "Hello, Rails!" section so someone reading that guide can continue with the getting started guide once they have Rails installed.

The other option was to keep both sets of instructions (rails local install vs. dev container), but I found it a bit awkward since the "Creating the Blog Application" is slightly different, and the instructions for opening the container need to come after that. So it was hard to structure it without introducing a bunch of duplication, or adding links between sections of the guide. So the separate guide for installing Rails seemed better, but I am open to feedback.

Additional information

Checklist

Before submitting the PR make sure the following are checked:

• This Pull Request is related to one change. Unrelated changes should be opened in separate PRs.
• Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
• Tests are added or updated if you fix a bug or add a feature.
• CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.

[AmandaPerino]

Thank you for making these changes @andrewn617 - I was also discussing this recently when going over the new upcoming tutorial. @Ridhwana will take a look at this on Wednesday (not possible to add you as a reviewer, so commenting instead). Marking this with rails-foundation tag to group current open To-Do's amongst the team.

[Ridhwana]

Hi @andrewn617 this looks really good and it's great to see installation instructions using Dev Container! I left some suggestions and feedback, let me know if anything is unclear.

[Ridhwana]

@andrewn617 I was trying to install this locally to test out the instructions but I don't see any installation instructions in the readme for rails-new?

[andrewn617]

I was chatting with Rafael about this today and it's next on my todo list. I'll have a PR open for it in the next 24 hours.

[andrewn617]

@Ridhwana Thank you for all your feedback! This is really helpful. I took most of your feedback.

One thing I am a bit unsure about: in a few places I had something like "working with your application in a container" and you recommended changing it to "run your application in a container". I avoided using the word "running" here because it makes me think of running the server. But the dev container running and the application running (within the container) are different. I wonder how best to succinctly capture "the container is now running, it's a fully featured development environment from which you can edit code, run tests, boot up the console, or run the application server".

Maybe I am overthinking it and for the audience of the guide this distinction isn't important 🤔 but I wanted to get your thoughts on it. I was trying to stick with saying things "working with your application within the container" or "developing within the container" but I admit the results are a bit awkward.

[Ridhwana]

One thing I am a bit unsure about: in a few places I had something like "working with your application in a container" and you recommended changing it to "run your application in a container". I avoided using the word "running" here because it makes me think of running the server. But the dev container running and the application running (within the container) are different. I wonder how best to succinctly capture "the container is now running, it's a fully featured development environment from which you can edit code, run tests, boot up the console, or run the application server".

Ah, thank you for this clarification! I think it's a valid concern especially when folks are new to all of these tools, I'll go back to where I suggested you change it and see if there's a different type of wording.

[andrewn617]

@Ridhwana Okay, I have pushed a new version which covers all your comments. Take another look when you have a chance :)

[Ridhwana]

@Ridhwana Okay, I have pushed a new version which covers all your comments. Take another look when you have a chance :)

Thanks so much! I'll take a look tomorrow. Also, will you let me know once the installation instructions for rails-new are ready and then I'll test out the setup as well.

[andrewn617]

@Ridhwana Heads up, based on feedback from the Rails Core team I have inverted my approach to updating the guides. I created a new guide called Getting Started with Dev Containers and linked to it from the original getting started guide. The content has stayed pretty much the exact same.

Also I have a PR open with instructions for rails-new rails/rails-new#13

[Ridhwana]

@andrewn617 I tried installing it based on your instructions but I may doing something wrong.

1. I downloaded the tar file from https://github.com/rails/rails-new/releases/tag/v0.3.0, not sure if it's okay to use this pre-release version in the meantime?
2. Then I unzipped the file on my Macbook by using tar -zxvf rails-new-0.3.0.tar.gz
3. I moved the file to usr/local/bin using sudo mv rails-new-0.3.0 /usr/local/bin/ which moves the executable into my path
4. Then I tried running rails-new-0.3.0.

Maybe I'm missing something obvious?

[andrewn617]

@Ridhwana Ah, sorry. You need to download the executable for your platform (eg rails-new-aarch64-apple-darwin.tar.gz for mac m1), not the source code. I'll update the rails new instructions to be more clear on that.

[Ridhwana]

@Ridhwana Ah, sorry. You need to download the executable for your platform (eg rails-new-aarch64-apple-darwin.tar.gz for mac m1), not the source code. I'll update the rails new instructions to be more clear on that.

Hey Andrew! Thanks for your guidance on this. I anticipate we might need to exchange a few messages as I work through the instructions to ensure everyone can smoothly install it without any hiccups. Here's my experience thus far:

I grabbed the executable from this link for version v0.3.0. After that, I followed your steps and relocated the executable to usr/local/bin, which is on the executable path in my system.

Moving forward, I navigated to a different directory and executed rails-new blog. However, I encountered an error stating "'rails-new' can’t be opened because Apple cannot check it for malicious software." After doing some digging, it seems like macOS's Gatekeeper security feature is causing this snag. It's flagging the rails-new-0.3.0 executable due to it being from an unidentified developer or lacking notarization. Do you reckon this will be addressed in the latest release version?

To sidestep this roadblock temporarily and continue testing, I opted to override Gatekeeper using xattr -d com.apple.quarantine /usr/local/bin/rails-new to execute the file.

Afterwards, I retried rails-new blog, and it successfully generated a folder containing all the necessary files 🎉

Following that, I ensured my Docker engine was up and running, and then opened the folder in VSCode. However, I hit an issue. Here's a snapshot of the error message regarding .rbenv ruby version:

Should this have been sorted out by Docker and Dev Containers, from my understanding of what we trying to achieve I should not have to install the rbenv version locally.

[andrewn617]

Hmm did you get that error right when you opened VSCode? Or after you started the container? Opening is VSCode does not automatically start the container, it should give you a pop up that prompts you to open the container:

[Ridhwana]

Hmm did you get that error right when you opened VSCode? Or after you started the container? Opening is VSCode does not automatically start the container, it should give you a pop up that prompts you to open the container:

Does this help?

https://www.loom.com/share/5a0fe7ea1796498483592977531096e4?sid=3a2bea0b-2baa-460c-99bd-4c564869bf92

[andrewn617]

Oh! I see the issue. Rails 7.2 is not released yet but these instructions are written for that release 😅 So you need to add the --main flag when doing rails-new to get the .devcontainer folder. Otherwise it will be your rails gem version (7.1.x). If you try again with rails-new blog --main you should see the .devcontainer! Sorry about that!

[Ridhwana]

@andrewn617 I managed to create a new application based on your instructions, thanks for help!

My final questions and thoughts on this review after testing are:

• Are we planning on waiting to merge this only after we release Rails 7.2 so that the instructions hold true or are we adding a disclaimer for versions earlier than 7.2?
• Are we also waiting for the latest release to be released https://github.com/rails/rails-new/releases/tag/latest before merging or do we have a different plan in place?
• What can we do about Gatekeeper that doesn't allow us to run the executable without overriding it?
• I dropped a comment about possibly mentioning what happens after opening up the blog application in DEV Container.

[Ridhwana]

This section in the Getting Started guide talks about starting up the web server on your development machine, I'm wondering do we need a mention here about what happens once you get you able to open your blog application within Dev Container? Things like how do you run your server and see your application?

[andrewn617]

Nope, everything is the exact same. If you bin/rails s within the container, it will boot the app and be accessible in your browser at http://127.0.0.1:3000.

[andrewn617]

@Ridhwana

Are we planning on waiting to merge this only after we release Rails 7.2 so that the instructions hold true or are we adding a disclaimer for versions earlier than 7.2?

It's my first time contributing the guides, so my understanding might not be exactly right. But I believe once this merges, it will be on the "edge" guides, which are the guides for the latest main branch of Rails. Once Rails 7.2 those guides will be promoted to the official guides (which you can see now are for v7.1.3.2).

Are we also waiting for the latest release to be released https://github.com/rails/rails-new/releases/tag/latest before merging or do we have a different plan in place?

This will have an official release prior to 7.2

What can we do about Gatekeeper that doesn't allow us to run the executable without overriding it?

I believe Rafael is working on that. I will chat with him today about it

I'll answer your other question in line =)

[Ridhwana]

Sounds good, thanks @andrewn617! ✨

@AmandaPerino just a heads up that I've reviewed this, and the instructions have been tested too. These are some of the considerations that may want to be noted.

[Ridhwana]

@andrewn617 it just occurred to me that we need to wrap the file to 80 columns if you have not done that already.

Please exclude line 1 from this wrapping. Thanks!