3. Running locally

Well, to be honest this section should really be called "Running locally on a Mac".

At this point, you should have a working Ruby installation, a minimum set of running services (at least MySQL, MongoDB and Redis, probably installed using Homebrew), a local copy of Magnet and a basic understanding of how it works and where to find the main configuration files.

What you really need now is a way to boot the application, wait for the bomb to explode, then take a look at the error logs to start tinkering the code, somehow complaining at me (no doubts, I personally did it several times). Ok, let's go deeper a little bit, first.

Application architecture

The application architecture behind Magnet can be roughly divided in three blocks, or parts:

1. The backend Rack/Rails application, allowing users to access metadata (create and manage collections, content feeds and fetched posts). It also exposes a set of APIs, to access both metadata and downloaded contents.
2. The workhorse Sidekiq scheduled jobs, actually fetching contents from any configured channel (content feed)
3. The frontend AngularJS sigle-page applications, using the APIs to deliver and present contents

All the parts are physically coded in the same code-tree, but run in separate contexts: a Rack app in the first case, a Sidekiq job in the second case, a Javascript app running in the client browser, for the third case.

To communicate with each other, an ActionCable websocket server is used as a poor-man-message-broker system.

First step: start the backend application

Being a common Rails application, nothing prevents Magnet to start inside any Rack-compliant web server, such as the bundled webrick development server, with a noticeable exception.

Inside Magnet, API calls are routed to the proper controllers under a subdomain-based constraint (see http://guides.rubyonrails.org/routing.html#request-based-constraints), to allow easier scaling on heavy-loaded production environments where API calls (content reading) are orders of magnitude greater than the web page-rendering calls (backend content management). To invoke any API endpoint on Magnet, clients must thus make a request to the "api" subdomain (e.g. api.mysite.com), and this configuration requires a little bit of tweaking on the server-side.

webrick

Don't forget to add an 'api' subdomain for localhost in the /etc/hosts file:

127.0.0.1 api.localhost

See http://stackoverflow.com/questions/25388948/can-i-make-rails-webrick-recognize-entries-in-etc-hosts-as-subdomains-instea and https://github.com/rails/rails/issues/12438).

Set config/application.yml as follows:

# Public URL
web_host: 'http://localhost:3000'

# Public API URL
api_host: 'http://api.localhost:3000'

Start webrick with rails server (from the project root directory), and open your browser at http://localhost:3000/users/sign_in: you should see something like this. To test the proper API routing, open your browser at http://api.localhost:3000/docs.json: you should see something like this.

Pow

You (like me) don't need to do anything special, since subdomains are automatically handled by Pow itself (see http://pow.cx/manual.html#section_2.1.1).

Stated that you symlinked you pow app as magnet, set config/application.yml as follows:

# Public URL
web_host: 'http://magnet.dev'

# Public API URL
api_host: 'http://api.magnet.dev'

Start pow (if not already running) with powder up (from the project root directory), and open your browser at http://magnet.dev/users/sign_in: you should see something like this. To test the proper API routing, open your browser at http://api.magnet.dev/docs.json: you should see something like this.

Unicorn, Puma, Phusion Passenger

Please take a look at the section (production deployments).

Second step: start Sidekiq

Nothing special here: since Sidekiq configuration is kept under the default path config/sidekiq.yml, simply open a new terminal window and start the service as follows (from the project root directory):

$ bundle exec sidekiq

Sidekiq logs are written in logs/sidekiq.log. In this case, Sidekiq runs as a foreground process in a separate shell (use CTRL-C to stop it); other fancy options (like starting in background with foreman) will be discussed in the next section (production deployments).

---

Next: Running in production