diff --git a/docs/getting-started/start-app.md b/docs/getting-started/start-app.md index 0855d1651..504f6b0e5 100644 --- a/docs/getting-started/start-app.md +++ b/docs/getting-started/start-app.md @@ -2,11 +2,11 @@ title: Starting the Application --- -# Starting the application - We're a Rails app, and we use [Webpacker][webpacker] to manage some of our JavaScript. +# Starting the application + Start the application, Webpack, and our job runner [Sidekiq][sidekiq] by running: @@ -45,5 +45,85 @@ instance/tab of your shell. Current gotchas: potential environment issues with external services need to be worked out. +# Starting the application (advanced) + +To have additional control in your local environment, you might prefer using an +advanced setup to start the application by using [Overmind][overmind]. + +The prerequisite is to install [Overmind][overmind], a process manager which +takes advantage of [tmux][tmux]. + +This will allow you to launch all your app's processes in the same terminal, navigate the logs +of each service separately, restart each service separately and have a better +debugging experience. + +After installing [Overmind][overmind], launch the application: + +```shell +overmind s -f Procfile.dev +``` + +## Debugging the Rails application + +[Overmind][overmind] lets you easily step through the Rails application in a +debugging session. + +Using the `pry` gem, you can add a `binding.pry` to set a breakpoint in the method you're trying to +debug; the application will halt its execution there. You can then connect +to the web server by opening a separate terminal window and typing: + +```shell +overmind c web +``` + +This will open up a [tmux][tmux] window pane at the debugging statement +position, which will look something like this: + +```ruby +pry(#)> whereami + +From: /forem/app/controllers/admin/admin_portals_controller.rb:8 Admin::AdminPortalsController#index: + + 5: def index + 6: a = "Hello debugger" + 7: binding.pry + => 8: end +``` + +## Inspecting the logs of each service + +Overmind launches the various services required for our local setup: `web` (the +Rails web server), `webpacker` (the server managing JavaScript) and `sidekiq` +(the server managing the asynchronous queue). + +If, for example, you want to inspect just the Sidekiq logs, you can open a +separate terminal window to look at those logs specifically: + +```shell +overmind c sidekiq +``` + +This will open a `tmux` console, which will allow you to browse _only_ the Sidekiq logs. + +There are also some handy `tmux` shortcuts that you may find useful. + +* The shortcut `C-b [` (_Control-b-open square bracket_) activates "scroll +mode", which allows you to use the arrows up and down and inspect the logs. +* The shortcut `q` deactivates "scroll mode". + +Please refer to [tmux][tmux] documentation for more information around `tmux` configuration and for additional +shortcuts. + +## Resources + +Other than the official [Overmind][overmind] and [tmux][tmux] +documentation, you may find the following resources useful: + +- [Rails quick tips #6: tmux, tmuxinator and Overmind](https://dev.to/citizen428/rails-quick-tips-6-tmux-tmuxinator-and-overmind-4850) +- [Give Your Terminal Super Powers: tmux Cheatsheet!](https://dev.to/jacobherrington/give-your-terminal-super-powers-tmux-cheatsheet-1p6p) +- [Introducing Overmind and Hivemind](https://evilmartians.com/chronicles/introducing-overmind-and-hivemind) + [sidekiq]: https://github.com/mperham/sidekiq [webpacker]: https://github.com/rails/webpacker +[overmind]: https://github.com/DarthSim/overmind +[tmux]: https://github.com/tmux/tmux/wiki