1. What is Invoker ?
Invoker is a utility belt for managing processes in development environment. Use it for managing multiple processes with ease. Use it for developing web applications on different local domains without /etc/hosts hacks.
First we need to install invoker gem to get command line utility called invoker, we can do that via:
~> gem install invoker
Currently it only works with Ruby 1.9.3 and 2.0.
You need to start by creating a ini file which will define processes you want to manage using invoker. An example ini file is included in the repo.
[rails] directory = /home/gnufied/god_particle command = bundle exec rails s -p 5000 [dj] directory = /home/gnufied/god_particle command = bundle exec ruby script/delayed_job [events] directory = /home/gnufied/god_particle command = bundle exec ruby script/event_server
After that you can start process manager via:
~> invoker start invoker.ini
Above command will start all your processes in one terminal with their stdout/stderr merged and labelled.
You can access http services managed by invoker via command_label.dev domain locally.
This feature currently works only on Mac OSX .
To make it work though, you need to run following command, just once from anywhere:
~> sudo invoker setup # read below if you are migrating from Pow
Above command installs a local .dev DNS resolver and a port forwarding rule that forwards all incoming requests on 127.0.0.1:80 to Invoker HTTP proxy.
If you decide to remove Invoker, you can remove things installed by Invoker using command
~> sudo invoker uninstall
Now because invoker is making your app server available on a domain. It requires control over port(or needs to know the port) on which your applications will be listening. This can be simply done by replacing specific port number in `ini` file with $PORT or by specifying a port key. For example:
[terminal] directory = /home/gnufied/ayr-terminal port = 3000 command = node app [cms] directory = /home/gnufied/mezzainine command = python manage.py runserver $PORT --noreload [typo] directory = /home/gnufied/typo command = bundle exec rails s -p $PORT
Now these services can be accessed via http://terminal.dev , http://cms.dev http://typo.dev. You can also access them via wildcard subdomains such as *.*.dev.
Since version 1.0.3 Invoker has added support for Procfile. Now If you already have a Procfile you need not even create a ini file for using Invoker.
The only thing to remember is, your Procfile must have $PORT in command - for .dev domain feature to work
rails: cd $HOME/rails_app && bundle exec rails s -p $PORT cms: cd $HOME/cms && python manage.py runserver $PORT
Additionally Invoker allows you to manage individual processes. You can start/stop/restart different processes managed by invoker without affecting others.
# Will try to stop running delayed job by sending SIGINT to the process ~> invoker remove dj # If Process can't be killed by SIGINT send a custom signal ~> invoker remove dj -s 9 # add and start running ~> invoker add dj # List currently running processes managed by invoker ~> invoker list # Restart process given by command Label ~> invoker reload dj # Restart process given by command label using specific signal for killing ~> invoker reload dj -s 9
You can also enable OSX notifications for crashed processes by installing terminal-notifier gem. It is not a dependency, but can be useful if something crashed and you weren't paying attention.
If you are migrating from Pow then first step before running invoker setup is to uninstall Pow:
curl get.pow.cx/uninstall.sh | sh
After that you should run invoker setup as usual. If for some reason you can't uninstall Pow via above command (in case you installed Pow using homebrew), then you should remove Pow daemon manually.
After running invoker setup you will have to switch off wi-fi and then switch it on for resettng OSX network configuration.
The way rbenv and rvm work sometimes creates problems when you are trying to use a process supervisor like invoker. There are couple of things to keep in mind, If you are running invoker with Ruby version x, but your application requires Ruby version Y:
When using rbenv and zsh, remember that .zshrc is not read for commands run via zsh -c. So first add:
and then run it using:
~> cat > ~/.zshenv eval "$(rbenv init -)"
command = RBENV_VERSION=2.0.0-p0 zsh -c "bundle exec rails s"
Unless version of Ruby using which you are running invoker command and version of Ruby you are using in the application is same, you almost always will want to use zsh -c or bash -c. RVM in particular requires a login shell and hence sometimes you may have to use bash -lc. For example:
command = bash -lc "rvm 2.0.0-p0 do bundle exec rails s"
Question : Does Invoker work with pow?
Answer : If you have already installed pow, Invoker will have a conflict with it. You will be prompted to overwrite pow setup with Invoker. You should uninstall pow before running Invoker setup. If DNS does not work after running invoker setup. Try turning wi-fi on and off.
Question : How do I undo Invoker setup?
Answer : Invoker installs a resolver file in /etc/resolver/dev and a firewall rule to port forward incoming requests on port 80 to another port. You can remove Invoker setup by removing /etc/resolver/dev and by running sudo launchctl unload -w com.codemancers.invoker.firewall.plist. Finally remove this file /Library/LaunchDaemons/com.codemancers.invoker.firewall.plist.