bifrost
bifrost is a deployment tool to be used in a simple* Docker setup. bifrost deploy containers based on parameters specified in bifrost.yml
and Dockerfile
.
(Using bifrost for large scale deployments is largely untested)
A simplified idea of how bifrost works by describing what happens during the command b build
:
- Copy folder which includes the
Dockerfile
to the docker host. - SSH into docker host and run
docker build
docker run
with the image which was just created- The container is up now if there were no errors during deployment
bifrost was built because I needed a way to deploy my Docker apps easily with minimal setup. Please read through the README before attempting to use.
Installation
bifrost is basically a bunch of "scripts" which SSH into your Docker host and perform the requested commands. Minimally, you only need a local machine (the deployer) with the dependencies installed, and the target machine with Docker and SSH installed.
Target Machine:
- Install Docker (tested with 1.3)
- A private IP on
eth0
(possible without but untested)
Local Machine:
- Install rsync (already installed on OSX and Ubuntu)
- Node.js, npm and CoffeeScript
- Install bifrost
- Generate SSH key and install on target machine's root user
Install bifrost:
$ npm install -g bifrost-docker
You can now invoke bifrost with either bifrost <args>
or simply just b <args>
.
hipache Integration
bifrost comes with integration with hipache as a dynamic router for web apps deployed in Docker containers. Setting it up is easy:
- Upload your SSL key and cert (
ssl.key
andssl.crt
) into/root/ssl/ssl.key
and/root/ssl/ssl.crt
on your Docker host respectively - On your Docker host:
$ docker run --restart="always" -d --name router -p 80:80 -p 443:443 -v /root/ssl:/etc/ssl ruqqq/hipache
This will expose the Docker host port 80 and 443 to the hipache instance known as router
. Now you can point A records of domains to the Docker host public IP and the requests will be routed by hipache.
In your app bifrost.yml
, configure the hipache
section accordingly. Bifrost will automatically configure hipache to point to the app as a backend when issuing build/start/stop/restart commands. You can deploy as many containers as you want and hipache will load balance between the backends.
Important: Using this integration means you should start/stop/restart/build your containers with bifrost exclusively as the integration mechanism exists in those commands too.
Note: To use hipache without SSL, you'll need to supply your own config.json. Refer to https://github.com/ruqqq/dockerfile-hipache
Usage
Servers YAML
- Servers are configured in a YAML file - A sample is available in
servers-sample/server.sample.yml
- The filename should be the server hostname (i.e.
domain.com.yml
) - Place the file in a folder somewhere (i.e.
~/.bifrost_servers
) and setBIFROST_SERVERS
environment variable:
$ export BIFROST_SERVERS=~/.bifrost_servers
- Alternatively, set this environment in your shell init file
Setting Environment Variables
BIFROST_SERVERS
: Location of your servers yml files (i.e.~/.bifrost_servers
)BIFROST_HOST
: The Docker host to target deployment at. Optionally, you can instead specify--host domain.com
option when running commands. In this example,$BIFROST_SERVERS/domain.com.yml
must exist.
Single Host Deployment
- Ensure your app folder has a
Dockerfile
- Ensure
bifrost.yml
is configured correctly in the app folder (sample insample-app/bifrost.sample.yml
) - Ensure your environment variables are set (see previous section)
- In your app folder, run
$ b build --host domain.com
bifrost will now SSH into the server and build the docker image followed by creating and running the container. If no errors were encountered, you should have your container up an running. Every time you need to update, just run the command again and it'll rebuild the image as needed and start a new container (and delete existing ones).
Multi Host Deployment
bifrost does not support fleet deployment. You'll have to deploy to individual Docker hosts manually. (i.e. running b build
command on the different hosts). To make your --links
directive work properly, refer to Docker Ambassador Pattern.
For hipache-based deployments, you should setup your Docker hosts in a private network. In bifrost.yml
config, expose the ports to your Docker host private IP. hipache will then map the domains to the Docker containers on different hosts via the private IP.
Sample App
TODO: Finish Sample App
Available Commands
The commands are to be run in your app folder which contains bifrost.yml
. You can also run b --help
in the command line for help.
Command | Description |
---|---|
build [--scale num] |
build and deploy image; use --scale to specify how many instances to run |
clean |
stops all containers, remove them and remove all images; kind of like "reformatting" the host |
inspect <container id> |
inspect the specific container id |
logs <container id> [--file file] |
view log for the specific container id; use --file to view log file inside the container |
restart [--c containerid] |
restart the app on the host; use --c to target specific container |
rm [--c containerid] |
remove the app on the host; use --c to target specific container |
sftp |
view sftp folder for the containers |
start [--c containerid] |
start the app on the host; use --c to target specific container |
status [--c containerid] |
view status of the app on the host; use --c to target specific container |
stop [--c containerid] |
stop the app on the host; use --c to target specific container |
trim |
deletes unused images on the host |
update-config |
upload /config to the host |
update-router |
update hipache routing for the app |
Author
- Faruq Rasid me@ruqqq.sg