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.
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
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
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.
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 are
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 --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.
service1: image: nginx
# 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.
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
rancher-compose will not delete your services. To delete a service you must use
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.
With services, you may want to have your service use
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.
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
test: scale: 2 test-data: scale: 2
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.
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
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
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
db1 would be resolvable as
mysql. Without the external link,
db1 would be resolvable as
Note: Cross stack discovery is limited by environment (by design). Cross environment discovery is not supported.