Simple development platform with process management & router
Watfish is designed to allow you to easily run multiple processes in various different environments inside the context of a project.
It loads processes from an etc/environments/${env-name}/procfile
inside your project directory and assigns them random ports, which are then routed from a url of your choice defined in a wtf.json
in your home directory.
All processes are provided with your global environment variables, variables defined in etc/environments/${env-name}/env
, and sensitive environments variables (that should not be included in your project), from the wtf.json
.
Environment variables can be used within your procfile (e.g. $PORT
) and will be substituted when the project is started.
It also looks in env/bin
inside your project for suitable commands to run within the project context, so when starting, for example, a python process, it will use the python version that is installed within your virtual environment.
Watfish provides several commands to easily help you setup a project (wtf init
), and define sensitive environment variables in your wtf.json
(wtf env set
, wtf env get
, wtf env del
).
Run the following command from any terminal
npm install watfish -g
Run the following command inside your project directory
wtf init
Then follow the on screen instructions
What is the name of the process you would like to route?
web
From what url would you like to route this process?
url.com
Created config:
{
"routes": {
"web": "url.com"
}
}
Is this correct? [y]
Now you can go ahead and start your project or run arbitrary commands in the project's environment.
wtf start
wtf runtests
Here's some of the commands that are available
Usage: wtf command [<sub-command>] [options]
Commands:
env, e Change local project environment variables
init, i Generate project config (in ~/wtf.json)
run, r Run arbitrary commands in the environment
start, s Start project processes
Options:
--help, -h Display help and usage info
--version, -v Display version
<command> Arbitrary command to run in the environment
Examples:
wtf init
wtf env set KEY value
wtf start
wtf start --env production
wtf run manage.py migrate
Procfiles and env files should be stored in a directory named after the environment you want to run them in, inside etc/environments
within your project. E.g. project/etc/environments/development/procfile
& project/etc/environments/development/env
.
By default watfish will run all processes in the development
environment, but you can start processes in an environment of your choice by providing the --env
argument. E.g. wtf start --env staging
.
An example procfile
might look like the following.
web: http-server ./ -p :$PORT
watch-js: watchify -t babelify src/index.js -o build/index.js
watch-less: watch-less-do-more -u postcss -i src/index.less -o build/index.less
An example env
file might look like the following.
DEBUG=true
ALLOWED_HOSTS=localhost
Routes & sensitive environment variables are loaded from a wtf.json
in your home directory.
If this is your first time running watfish on your machine, or for a new project, you can run wtf init
to setup a route for this project and create a wtf.json
for you.
You can run wtf init
for as many projects as you like and additional config will be added to the wtf.json
.
Each project will receive its own key within the wtf.json
based on the its directory name.
You can also run wtf init
for a single project more than once. This will, however, erase any existing config for that project.
You can manually edit the wtf.json
to add, remove, or adjust routes & environment variables, or use the provided commands.
An example wtf.json
might look like the following.
{
"project-name": {
"routes": {
"web": "sub.domain.com"
},
"env": {
"SECRET_KEY": "********"
}
}
}
Initialize the project:
wtf init
Answer questions about routing:
What is the name of the process you would like to route?
web
From what url would you like to route this process?
example.domain.com
Created config:
{
"routes": {
"web": "example.domain.com"
}
}
Is this correct? [y]
wtf.json written to /Users/user/wtf.json
Add a development environment variable:
wtf env set SECRET_KEY my-secret-key
Created config:
{
"development": {
"SECRET_KEY": "my-secret-key"
}
}
Is this correct? [y]
wtf.json written to /Users/user/wtf.json
Add a production environment variable:
wtf env set SECRET_KEY another-secret-key --env production
Created config:
{
"development": {
"SECRET_KEY": "my-secret-key"
},
"production" : {
"SECRET_KEY": "another-secret-key"
}
}
Is this correct? [y]
wtf.json written to /Users/user/wtf.json
This will have created a wtf.json
in your home directory with the following contents:
{
"project": {
"routes": {
"web": "example.domain.com"
},
"env": {
"development": {
"SECRET_KEY": "my-secret-key"
},
"production" : {
"SECRET_KEY": "another-secret-key"
}
}
}
}