Package: crabtools
Crab 🦀crabis a simple unix toolkit for working with local development environments.It is intended to allow developers to run multipletwelve-factorstyle web applications locally and address them via hostnames rather than port numbers. It is deliberately designed to be as simple as possible, and therefore does not attempt to manage multiple processes itself.What does it do?Crab does the following:Understands env files.Understands procfiles.Can manipulate the$PATHenvironment variable.Manages ports and provides a local virtual host router.The crab binary can be called in three ways:With a literal command to run:crab python manage.py shellWith the name of a process from a procfile:crab webAs a special-case to start a virtual host router:crab router(see below).Crab itself is configured entirely through environment variables, and so a developer can set a few simple env vars (in.bashrc, say) to match how their projects are laid out, and then Crab just does the "right thing".Env filesAn env file is a text file containing key/value pairs, like this:SOME_VARIABLE=somevalue
ANOTHER_VARIABLE=anothervalueFollowing12 factorguidelines, an app's config (everything that is likely to vary between different environments) should be stored inenvironment variables. Env files provide a simple way for developers to specify environment variables for a project.By default, Crab will look for an env file called.envinside the project directory (ie wherevercrabis executed from). This can be overridden using theENV_FILEenvironment variable.ENV_FILEcan be a comma-separated list of file paths, which will be parsed in order. For example, you could useconfigs/development/envas your checked-in env file, and then have a local.envto override individual variables. In this case, useexport ENV_FILE=configs/development/env,.env.example:$ echo 'FOO=bar' > .env
$ crab sh -c 'echo $FOO'
barProcfilesA procfile is a text file that defines the processes that need to be running for your application to work. It contains a mapping from process names to commands, like this:web: python manage.py runserver
worker: python manage.py workerBy default, Crab will look for a procfile calledProcfileinside the project directory (ie wherevercrabis executed from). This can be overridden using thePROC_FILEenvironment variable. For exampleexport PROC_FILE=configs/development/procfile. To specify multiple procfile locations, which are used in sequence, useexport PROC_FILE="configs/development/Procfile,configs/development/procfile"To run a process defined in a procfile, usecrab <processname>. For example,crab webwould start thewebprocess defined in the example procfile above. Note that Crab only runs asingleprocess from the procfile. It cannot start all of the processes in the procfile at the same time.This is by design. If you wish to use multiple processes from the procfile, just start each one separately withcrabin a separate terminal split or tab.$PATHTools that are designed to isolate per-project dependency environments often work by making a copy of the language binary and libraries inside a project-specific subdirectory. The main example is Python'svirtualenvtool.Crab can add the path to this virtualenv onto the front of the$PATHenvironment variable. This means that you do not need to "activate" the virtualenv before using it - simply runningcrab python manage.py runserverwill automatically use thepythonbinary inside the virtualenv.By default, the pathenv/binis prepended to$PATH. You can override this by setting theBIN_DIRSenvironment variable.PortsMany developers work on multiple projects and/or multiple services at the same time. When each requires its own web server, each server process requires a different port to bind to. For example, Django'smanage.py runserverbinds to port 8000 by default. If you're working on two Django projects simulateously, you will have to run the second on a different port, saymanage.py runserver 0.0.0.0:8001. Once you're developing on five or ten microservices, this can become very difficult to manage.Crab helps by providing a free port to processes that need one. The port is provided in the environment (as$PORT) as well as substituted into the command. For example:crab python manage.py '0.0.0.0:$PORT'You'll see Django's development server start up with (say):Django version 2.2, using settings 'project.settings'
Starting development server at http://0.0.0.0:63601/
Quit the server with CONTROL-C.A port is provided to any command with the name "web" in a Procfile, or any command containing the string "$PORT". In other circumstances, it can be explicitly requested by setting the environment variableCRAB_PROVIDE_PORT.(Note that for non-procfile commands, the variable must be quoted, or else the shell will try to substitute$PORT, which won't work).Virtual host routingThe ports functionality above is only useful in combination with another component of Crab: the virtual host router. Start this up by typingcrab routerin a separate terminal tab or split. By default, the router binds to port8080(see below for more details on this).Now, if any of the other processes you run have an environment variable calledVIRTUAL_HOST, the router can "see" them and automatically route traffic to the port they've been provided with.You can set this environment variable in the.envfile for your project e.g.VIRTUAL_HOST=mywebsite.localhostThen you can start (or restart) your project, visithttp://mywebsite.localhost:8080in your browser, and the traffic will magically be routed to the right place.(Note that at least Chrome automatically routes everything with the TLD.localhostto 127.0.0.1. Other browsers may or may not follow this standard).The port that the router binds to can be changed by setting theCRAB_ROUTER_PORTenv var. If this is not set, the router will first try to bind to port80, and then fall back to8080if it fails. This means that if you start the router withsudo crab router, you can then just usehttp://mywebsite.localhostin your browser - even better!The router is designed for local development only, so binds to127.0.0.1by default. You can setCRAB_ROUTER_HOSTto customize this.How to install CrabPython doesn't have a great built-in way of installing command line tools. There are a few options:Using homebrewCrab can be downloaded fromour homebrew tap:brew install dabapps/tap/crabThis will also add the router as a service, which can be started withbrew services start crab.Installing globallyYou can trypip install --user crabtools. This will installcraband its dependencies globally. Depending on how you set up your development environment, this may not be desirable.Installing in a virtualenvYou can create a virtualenv somewhere on your machine,pip install crabtoolsinto it, and then put that virtualenv'sbindir on your$PATH(for example, by setting$PATHin your.bashrc) or link the binary onto somewhere that's already on your$PATH(egsudo ln -s /path/to/your/venv/bin/crab /usr/local/bin/crab).Using pipxpipxis a great tool for managing command line programs written in Python. It basically creates and manages virtualenvs containing isolated command line tools. Follow the instructions to installpipxand thenpipx install crabtools.Developing on CrabPlease ensure all code conforms to Black formatting rules. Installblackin your virtualenv and thencrab black crab/ setup.py.