The rancher-compose
tool is a multi-host version of docker-compose
. It operates within the scope of a stack in the Rancher UI, which belongs to one environment and has many hosts. The containers started by rancher-compose
will be deployed on any of the hosts in the environment that satisfy the scheduling rules. If there are no scheduling rules, then the containers of the service are launched on the hosts with the fewest containers. These containers are launched just as if you had started a service in the UI as rancher-compose is making the same API calls.
The rancher-compose
tool works just like the popular docker-compose
and supports the V1 version of docker-compose.yml
files. To enable features that are supported in Rancher, you can also have a rancher-compose.yml
which extends and overwrites the docker-compose.yml
. For example, scale of services and health checks would be in the rancher-compose.yml
file.
The documentation for rancher-compose
expects users to have an understanding of docker-compose
. Please read through the docker-compose documentation before starting to work with rancher-compose
.
The binary can be downloaded directly from the UI. The link can be found in the right hand side of the footer in the UI. We have binaries for Windows, Mac, and Linux.
You can also check the releases page for rancher-compose for direct downloads of the binary.
To enable rancher-compose
to launch services in a Rancher instance, you’ll need to set environment variables or pass these variables as an option in the rancher-compose
command. The environment variables that are required areRANCHER_URL
, RANCHER_ACCESS_KEY
, and RANCHER_SECRET_KEY
. The access key and secret key will be an environment API key.
# Set the url that Rancher is on
$ export RANCHER_URL=http://server_ip:8080/
# Set the access key, i.e. username
$ export RANCHER_ACCESS_KEY=<username_of_environment_api_key>
# Set the secret key, i.e. password
$ export RANCHER_SECRET_KEY=<password_of_environment_api_key>
If you choose not to set the environment variables, you’ll need to pass the same values as options as part of any rancher-compose
command.
$ rancher-compose --url http://server_ip:8080 --access-key <username_of_environment_api_key> --secret-key <password_of_environment_api_key> up
Now, you can use any docker-compose.yml
file with rancher-compose
to launch services. The services will automatically be launched in your Rancher instance in the environment that the environment API key is located in.
To get started, you can create a simple docker-compose.yml
file and optionally a rancher-compose.yml
file. If there is no rancher-compose.yml
file, then all services will start with a scale of 1 container.
Sample docker-compose.yml
service1:
image: nginx
Sample rancher-compose.yml
# Reference the service that you want to extend
service1:
scale: 2
After your files are created, you can launch the services into Rancher server.
# Creating and starting a service without environment variables and selecting a stack
# If no stack is provided, the stack name will be the folder name that the command is running from
# If the stack does not exist in Rancher, it will be created
$ rancher-compose --url URL_of_Rancher --access-key <username_of_environment_api_key> --secret-key <password_of_environment_api_key> -p stack1 up
# Creating and starting a service with environment variables already set
$ rancher-compose -p stack1 up
# To change the scale of an existing service
$ rancher-compose -p stack1 scale service1=3
To read more about the different commands and options, please read our rancher-compose command documentation.
By default, rancher-compose
will not delete containers/services. This means that if you do two up
commands in a row, the second up
will do nothing. This is because the first up will create everything and leave it running. Even if you do not pass -d
to up
, rancher-compose
will not delete your services. To delete a service you must use rm
.
Docker builds are supported in two ways. First is to set build:
to a git or HTTP URL that is compatible with the remote parameter in the Docker Remote API. The second approach is to set build:
to a local directory and the build context will be uploaded to S3 and then built on demand on each node.
For S3 based builds to work you must setup AWS credentials. We’ve provided a detailed example of how to build using S3 in rancher-compose.
With services, you may want to have your service use volumes_from
and net
to point to another service. In order for these to work, you need to set up a sidekick relationship. The sidekick relationship is how Rancher scales and schedules these services as one unit. Example: B is a sidekick of A, so the services will always deploy as a pair and scale of the services will always be the same.
Another time that you may want to define the sidekick relationship is if you have multiple services that always need to be deployed on the same host.
To set a sidekick relationship, you add a label to one of the services. The key of the label will be io.rancher.sidekicks
and the value will be the service(s). If you have multiple services to add as sidekicks, they should be separated with commas. Example: io.rancher.sidekicks: sidekick1, sidekick2, sidekick3
When defining a sidekick to a service, you do not need to link the services in rancher-compose
as services within an environment are automatically DNS-resolvable to each other.
Whichever service contains the sidekick label is considered the primary service, and the sidekicks are considered secondary services. The scale of the primary service will be used as the scale for all services in the sidekicks label. If your scale among all your services are different, then the scale of the primary service will be used for all services.
When using load balancers with services that have sidekicks, you can only target the primary service. A sidekick can not be the target.
Sample configuration docker-compose.yml
test:
tty: true
image: ubuntu:14.04.2
stdin_open: true
volumes_from:
- test-data
labels:
io.rancher.sidekicks: test-data
test-data:
tty: true
command:
- cat
image: ubuntu:14.04.2
stdin_open: true
Sample rancher-compose.yml
test:
scale: 2
test-data:
scale: 2
volumes_from
If you have multiple services that will be using the same container to do a volumes_from
, you can add the second service as a sidekick of the primary service and use the same data container. Since only the primary service can be a target of a load balancer, please make sure the correct service is chosen as the primary service (i.e. the one that will have the sidekick label).
test-data:
tty: true
command:
- cat
image: ubuntu:14.04.2
stdin_open: true
test1:
tty: true
image: ubuntu:14.04.2
stdin_open: true
labels:
io.rancher.sidekicks: test-data, test2
volumes_from:
- test-data
test2:
tty: true
image: ubuntu:14.04.2
stdin_open: true
volumes_from:
- test-data
In Rancher, all services within an environment are DNS resolvable so linking services explicitly is not required, unless you would like to use a specific alias for DNS resolution.
Note: We currently do not support linking sidekick services to the primary service or vice versa. Read more about how Rancher’s internal DNS works.
For services in the same stack, any service is DNS resolvable by it’s native service_name
, if you so wish, you can use links present this service under another alias.
Sample docker-compose.yml
wordpress:
image: wordpress
links:
- db:mysql
db:
image: mysql
In this example, the db
would be resolvable as mysql
. Without the link, db
would be resolvable as db
.
For services in a different stack, the service is DNS already resolvable by service_name.stack_name
. If you’d prefer to use a specific alias for DNS resolution, you can use external_links
in the docker-compose.yml
.
Sample docker-compose.yml
wordpress:
image: wordpress
external_links:
- alldbs/db1:mysql
In this example, the alldbs
stack has a db1
service that the wordpress service will link to. In the wordpress
service, db1
would be resolvable as mysql
. Without the external link, db1
would be resolvable as db1.alldbs
.
Note: Cross stack discovery is limited by environment (by design). Cross environment discovery is not supported.