chrismytton/shoreman

:shell: foreman in shell

shoreman(1)

A shell implementation of Foreman. Starts the process formations defined in a Procfile.

Install

macOS with Homebrew

brew install chrismytton/formula/shoreman

Standalone

Install as a standalone, change ~/bin/ to any other directory that's in your $PATH if you wish.

curl https://github.com/chrismytton/shoreman/raw/master/shoreman.sh -sLo ~/bin/shoreman && \
chmod 755 ~/bin/shoreman

Usage

Head into a project that has a Procfile in it, then simply run the shoreman command. It will read your Procfile, and start up the processes it finds. If there is a .env file in the directory then environment variables will be read from it, as with foreman.

cd project-with-procfile
shoreman

Running tests

Tests are written using roundup.

To run the tests, go to the root of the repository then run make.

cd shoreman
make

Annotated source code

There's a literate-programming-style annotated version of the source code available at https://www.chrismytton.uk/shoreman/.

Generate documentation from source code

npm install -g docco
docco -l linear shoreman.sh

This puts the documentation in a docs/ directory. You'll then need to manually copy the contents of that directory over to the gh-pages branch and run mv shoreman.html index.html in order to publish it to GitHub Pages.

Projects using shoreman

• dokku-shoreman a plugin for dokku to allow it to run multiple process types.

Contributors

See the contributors section of GitHub Insights for this repository.

Credits

Inspired by the original Foreman by David Dollar (@ddollar).

Copyright (c) Chris Mytton

shoreman's Issues

Optionally logging each process separately

I was thinking we could look into offering a -l, --log flag to shoreman start -l ./logs and it could split each process into an append only file. This feature would be disabled by default.

Thoughts?

Doesn't work on linux

When running the tests on travis-ci an error is given, detailed below. Strangely the script still returns a 0 exit status, despite the failure. I've managed to reproduce this on an Ubuntu VM.

$ ./script/cibuild
Shoreman
trap: ERR: bad trap
+ before
+ :
=========================================================
Tests:    0 | Passed:   0 | Failed:   0

Ctrl-C does not kill child processes

Since fb4a143 , Ctrl-C doesn't kill some child processes.

Procfile

sleep1: sleep 1000
sleep2: sleep 1000

$ ./shoreman.sh
08:29:42 sleep1 | 'sleep 1000' started with pid 5865   # <= these are not sleep command pid but may be piped log pid.
08:29:42 sleep2 | 'sleep 1000' started with pid 5873
^CSIGINT received
sending SIGTERM to all processes
SIGINT received
sending SIGTERM to all processes
$ ps ax | grep sleep
 5871 pts/1    S      0:00 sleep 1000
 5879 pts/1    S      0:00 sleep 1000
 5923 pts/1    S+     0:00 grep sleep

In real situation, I want to stop php-fpm. 5180c1c works fine.

I'm testing with OSX and CentOS 6.5.

Coloring output

Would there be any chance we can get colored output with shoreman? Stuff is starting to bleed together.

does not terminate all others when a single process dies

foo: exit
bar: sleep 10

the sleep keeps running ... this is basic foreman functionality, please add it :)

Randomly failing tests

Sometimes the tests fail randomly, I'm not sure why this is, but I expect it's a bug. Need to investigate further to pinpoint the problem, but it doesn't happen on every run.

Allow tabs in Procfile

Foreman accepts any whitespace after the name. The following Procfile has a tab:

% cat Procfile
asdf:   echo 'derp'

% foreman check
valid procfile detected (asdf)

However, shoreman errors:

% ./shoreman
16:14:06 asdf   | bash: asdf:: command not found
16:14:06 asdf   | 'asdf:        echo 'derp'' started with pid 14528
SIGINT received
sending SIGTERM to all processes

We can use [[:space:]] in extglob to fix:

--- shoreman.orig       2014-08-05 16:14:19.145335921 +0000
+++ shoreman    2014-08-05 16:14:39.546732133 +0000
@@ -78,7 +78,7 @@
 PROCFILE=${1:-'Procfile'}
 while read line || [ -n "$line" ]; do
   name=${line%%:*}
-  command=${line#*: }
+  command=${line#*:[[:space:]]}
   start_command "$command" "${name}"
   echo "'${command}' started with pid ${pid}" | log "${name}"
 done < "$PROCFILE"

% ./shoreman
16:14:41 asdf   | 'echo 'derp'' started with pid 15218
16:14:41 asdf   | derp
SIGINT received
sending SIGTERM to all processes

Starting individual processes

I have a procfile with a few processes described, yet I only want to run one. I can not accomplish this currently with shoreman. I just wanted to get a feel for what others think about this.

does not stop running processes on debian stable

the reason seems that shoreman kill(1)s sh -c ... which forks itself before executing actual command and actual commands does not receive signal and remain running in background. Replacing sh -c ... with bash -c ... fixes the issue but I'm not sure that it's correct.

Add support for multiline strings in .env

see also:
ddollar/foreman#250
nickstenning/honcho#129

Sending Signals to Child Processes

Currently Shoreman traps INT, TERM, and EXIT before sending TERM to all child processes.

In some cases, having the ability to send individual signals (such as USR1) to process(es) would allow them time to cleanup before being killed.

I would definitely use this feature, especially in dokku-shoreman and am curious if this is something you would be interested in as well.

Procfile remains open while running shoreman

This cause problem with Windows VirtualBox.

While Guest OS opening a file, the file can't unlink from Host OS (Windows).
Currently, we have to terminate shoreman before switching git branch which modifies the Procfile.

Foreman close Procfile before starting commands.

• https://github.com/ddollar/foreman/blob/5ef8bbdbe3bf086910f68699149188d775f735dc/lib/foreman/procfile.rb#L85

Roundup dependency

Hello,

This is not really an issue, but I can't find the button to send a message in github anymore (I suppose they removed it).

This is about the documentation that says you need to install Roundup in order run to tests.
I think your Makefile uses a script that removes this mandatory step.
I might be wrong, which is why I did not do a pull request.

Hopefully I'll do more useful contributions to shoreman in the future :-)
I really like it, and the use of roundup for tests is quite cool.

Have a nice day,
mig

Procfile not ending with a line break don't work

Hello,

Just realized Procfiles with no line break at the end don't work.
Probably because of the way the file is split in order to read lines.

I am working on something else right now but will be able to make a pull request with a patch soon if you want.

Have a nice day,
Mig

tab character shows up at '\t'

I'm seeing output like this:

23:32:15 web.1\t| 'node web.js' started with pid 82555

That \t should be an actual tab character.