Start Up is a simple deployment tool that performs given set of commands on multiple hosts in parallel. It reads Stupfile, a YAML configuration file, which defines networks (groups of hosts), commands and targets.
$ make dist
$ stup [OPTIONS] NETWORK COMMAND [...]
||Custom path to Stupfile|
||Set environment variables|
||Filter hosts matching regexp|
||Filter out hosts matching regexp|
||Enable debug/verbose mode|
||Disable hostname prefix|
A group of hosts.
# Stupfile networks: production: hosts: - api1.example.com - api2.example.com - api3.example.com staging: # fetch dynamic list of hosts inventory: curl http://example.com/latest/meta-data/hostname
$ stup production COMMAND will run COMMAND on
api3 hosts in parallel.
A shell command(s) to be run remotely.
# Stupfile commands: restart: desc: Restart example Docker container run: sudo docker restart example tail-logs: desc: Watch tail of Docker logs from all hosts run: sudo docker logs --tail=20 -f example
$ stup staging restart will restart all staging Docker containers in parallel.
$ stup production tail-logs will tail Docker logs from all production containers in parallel.
Serial command (a.k.a. Rolling Update)
serial: N constraints a command to be run on
N hosts at a time at maximum. Rolling Update for free!
# Stupfile commands: restart: desc: Restart example Docker container run: sudo docker restart example serial: 2
$ stup production restart will restart all Docker containers, two at a time at maximum.
Once command (one host only)
once: true constraints a command to be run only on one host. Useful for one-time tasks.
# Stupfile commands: build: desc: Build Docker image and push to registry run: sudo docker build -t image:latest . && sudo docker push image:latest once: true # one host only pull: desc: Pull latest Docker image from registry run: sudo docker pull image:latest
$ stup production build pull will build Docker image on one production host only and spread it to all hosts.
Runs command always on localhost.
# Stupfile commands: prepare: desc: Prepare to upload local: npm run build
Uploads files/directories to all remote hosts. Uses
tar under the hood.
# Stupfile commands: upload: desc: Upload dist files to all hosts upload: - src: ./dist dst: /tmp/
Interactive Bash on all hosts
Do you want to interact with multiple hosts at once? Sure!
# Stupfile commands: bash: desc: Interactive Bash on all hosts stdin: true run: bash
$ stup production bash # # type in commands and see output from all hosts! # ^C
Passing prepared commands to all hosts:
$ echo 'sudo apt-get update -y' | stup production bash # or: $ stup production bash <<< 'sudo apt-get update -y' # or: $ cat <<EOF | stup production bash sudo apt-get update -y date uname -a EOF
Interactive Docker Exec on all hosts
# Stupfile commands: exec: desc: Exec into Docker container on all hosts stdin: true run: sudo docker exec -i $CONTAINER bash
$ stup production exec ps aux strace -p 1 # trace system calls and signals on all your production hosts
Target is an alias for multiple commands. Each command will be run on all hosts in parallel,
stup will check return status from all hosts, and run subsequent commands on success only
(thus any error on any host will interrupt the process).
# Stupfile targets: deploy: - build - pull - migrate-db-up - stop-rm-run - health - slack-notify
$ stup production deploy
is equivalent to
$ stup production build pull migrate-db-up stop-rm-run health slack-notify airbrake-notify
See example Stupfile.
# Stupfile --- version: 1 # Global environment variables env: NAME: api IMAGE: example/api networks: local: hosts: - address: localhost staging: hosts: - address: stg1.example.com production: hosts: - address: api1.example.com - address: api2.example.com user: ec2-user sudo: true commands: echo: desc: Print some env vars run: echo $NAME $IMAGE $STUP_NETWORK date: desc: Print OS name and current date/time run: uname -a; date targets: all: - echo - date
Default environment variables available in Stupfile
$STUP_HOST- Current host.
$STUP_NETWORK- Current network.
$STUP_USER- User who invoked stup command.
$STUP_TIME- Date/time of stup command invocation.
$STUP_ENV- Environment variables provided on stup command invocation. You can pass
dockercommands in your Stupfile.
Running stup from Stupfile
Stupfile doesn't let you import another Stupfile. Instead, it lets you run
stup sub-process from inside your Stupfile. This is how you can structure larger projects:
./Stupfile ./database/Stupfile ./services/scheduler/Stupfile
Top-level Stupfile calls
stup with Stupfiles from sub-projects:
restart-scheduler: desc: Restart scheduler local: > stup -f ./services/scheduler/Stupfile $STUP_ENV $STUP_NETWORK restart db-up: desc: Migrate database local: > stup -f ./database/Stupfile $STUP_ENV $STUP_NETWORK up
Common SSH Problem
if for some reason stup doesn't connect and you get the following error,
connecting to clients failed: connecting to remote host failed: Connect("email@example.com"): ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain
it means that your
ssh-agent dosen't have access to your public and private keys. in order to fix this issue, follow the below instructions:
- run the following command and make sure you have a key register with
if you see something like
The agent has no identities. it means that you need to manually add your key to
in order to do that, run the following command
you should now be able to use stup with your ssh key.
- add secret vault database
- add host manage plugin
- add service manage plugin
- add package manage plugin
fork it, hack it.. $ make build create new Pull Request
Licensed under the MIT License.