diff --git a/docs/_includes/os-sidebar.html b/docs/_includes/os-sidebar.html index a8cb10b7..e47851f9 100644 --- a/docs/_includes/os-sidebar.html +++ b/docs/_includes/os-sidebar.html @@ -93,6 +93,8 @@ diff --git a/docs/os/configuration/custom-console/index.md b/docs/os/configuration/custom-console/index.md index c1634f8c..e79fb929 100644 --- a/docs/os/configuration/custom-console/index.md +++ b/docs/os/configuration/custom-console/index.md @@ -18,6 +18,7 @@ When launching RancherOS with a [cloud-config]({[site.baseurl}}/os/configuration Currently, the list of available consoles are: * default +* alpine * centos * debian * fedora @@ -37,6 +38,7 @@ You can easily list the available consoles in RancherOS and what their status is ``` $ sudo ros console list +disabled alpine disabled centos disabled debian current default diff --git a/docs/os/system-services/adding-system-services/index.md b/docs/os/system-services/adding-system-services/index.md index bbb817cf..becfd80e 100644 --- a/docs/os/system-services/adding-system-services/index.md +++ b/docs/os/system-services/adding-system-services/index.md @@ -1,5 +1,5 @@ --- -title: Adding System Services in RancherOS +title: System Services in RancherOS layout: os-default redirect_from: - os/system-services/ @@ -53,81 +53,4 @@ If you want to remove a system service from the list of service, just delete the $ sudo ros service delete ``` -### Custom System Services -You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS. - -#### Launching Services through Cloud-Config - -If you want to boot RancherOS with a system service running, you can add the service to the cloud-config that is passed to RancherOS. When RancherOS starts, this service will automatically be started. - -```yaml -#cloud-config -rancher: - services: - nginxapp: - image: nginx - restart: always -``` - -#### Launching Custom System Services inside RancherOS - -If you already have RancherOS running, you can start a system service by saving a `docker-compose.yml` file at `/var/lib/rancher/conf/`. - -```yaml -nginxapp: - image: nginx - restart: always -``` - -To enable a custom system service from the file location, the command must indicate the file location if saved in RancherOS. If the file is saved at a http(s) url, just use the http(s) url when enabling/disabling. - -``` -# Enable the system service saved in /var/lib/rancher/conf -$ sudo ros service enable /var/lib/rancher/conf/example.yml -# Enable a system service saved at a http(s) url -$ sudo ros service enable https://mydomain.com/example.yml -``` - -
- -After the custom system service is enabled, you can start the service using `sudo ros service up -d `. The `` will be the names of the services inside the `docker-compose.yml`. - -``` -$ sudo ros service up -d nginxapp -# If you have more than 1 service in your docker-compose.yml, add all service names to the command -$ sudo ros service up -d service1 service2 service3 -``` - -### System Docker vs. Docker - -RancherOS uses labels to determine if the container should be deployed in System Docker. By default without the label, the container will be deployed in Docker. - -```yaml -labels: - - io.rancher.os.scope=system -``` - -### Labels - -We use labels to determine how to handle the service containers. - -Key | Value |Description -----|-----|--- -`io.rancher.os.detach` | Default: `true` | Equivalent of `docker run -d`. If set to `false`, equivalent of `docker run --detach=false` -`io.rancher.os.scope` | `system` | Use this label to have the container deployed in System Docker instead of Docker. -`io.rancher.os.before`/`io.rancher.os.after` | Service Names (Comma separated list is accepted) | Used to determine order of when containers should be started. -`io.rancher.os.createonly` | Default: `false` | When set to `true`, only a `docker create` will be performed and not a `docker start`. -`io.rancher.os.reloadconfig` | Default: `false`| When set to `true`, it reloads the configuration. - - -#### Example of how to order container deployment - -```yaml -foo: - labels: - # Start foo before bar is launched - io.rancher.os.before: bar - # Start foo after baz has been launched - io.rancher.os.after: baz -``` diff --git a/docs/os/system-services/custom-system-services/index.md b/docs/os/system-services/custom-system-services/index.md new file mode 100644 index 00000000..e022bc36 --- /dev/null +++ b/docs/os/system-services/custom-system-services/index.md @@ -0,0 +1,107 @@ +--- +title: Custom System Services in RancherOS +layout: os-default +--- + +## Custom System Services + +You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS. + +### Launching Services through Cloud-Config + +If you want to boot RancherOS with a system service running, you can add the service to the cloud-config that is passed to RancherOS. When RancherOS starts, this service will automatically be started. + +```yaml +#cloud-config +rancher: + services: + nginxapp: + image: nginx + restart: always +``` + +### Launching Services using local files + +If you already have RancherOS running, you can start a system service by saving a `docker-compose.yml` file at `/var/lib/rancher/conf/`. + +```yaml +nginxapp: + image: nginx + restart: always +``` + +To enable a custom system service from the file location, the command must indicate the file location if saved in RancherOS. If the file is saved at a http(s) url, just use the http(s) url when enabling/disabling. + +``` +# Enable the system service saved in /var/lib/rancher/conf +$ sudo ros service enable /var/lib/rancher/conf/example.yml +# Enable a system service saved at a http(s) url +$ sudo ros service enable https://mydomain.com/example.yml +``` + +
+ +After the custom system service is enabled, you can start the service using `sudo ros service up -d `. The `` will be the names of the services inside the `docker-compose.yml`. + +``` +$ sudo ros service up -d nginxapp +# If you have more than 1 service in your docker-compose.yml, add all service names to the command +$ sudo ros service up -d service1 service2 service3 +``` + +### Launching Services from a web repository + +The https://github.com/rancher/os-services repository is used for the built-in services, but you can create your own, and configure RancherOS to use it in addition (or to replace) it. + +The config settings to set the url in which `ros` should look for an `index.yml` file is: `rancher.repositories..url`. The `core` repository url is set when a release is made, and any other `` url you add will be listed together when running `ros console list`, `ros servce list` or `ros engine list` + +For example, in RancherOS v0.7.0, the `core` repository is set to `https://raw.githubusercontent.com/rancher/os-services/v0.7.0`. + +### Creating your own Console + +Once you have your own Services repository, you can add a new service to its index.yml, and then add a `.yml` file to the directory starting with the first letter. + +To create your own console images, you need to: + +1 install some basic tools, including an ssh daemon, sudo, and kernel module tools +2 create `rancher` and `docker` users and groups with UID and GID's of `1100` and `1101` respectively +3 add both users to the `docker` and `sudo` groups +4 add both groups into the `/etc/sudoers` file to allow password-less sudo +5 configure sshd to accept logins from users in the `docker` group, and deny `root`. +6 set `ENTRYPOINT ["/usr/bin/ros", "entrypoint"]` + +the `ros` binary, and other host specific configuration files will be bind mounted into the running console container when its launched. + +For examples of existing images, see https://github.com/rancher/os-images. + +## Labels + +We use labels to determine how to handle the service containers. + +Key | Value |Description +----|-----|--- +`io.rancher.os.detach` | Default: `true` | Equivalent of `docker run -d`. If set to `false`, equivalent of `docker run --detach=false` +`io.rancher.os.scope` | `system` | Use this label to have the container deployed in System Docker instead of Docker. +`io.rancher.os.before`/`io.rancher.os.after` | Service Names (Comma separated list is accepted) | Used to determine order of when containers should be started. +`io.rancher.os.createonly` | Default: `false` | When set to `true`, only a `docker create` will be performed and not a `docker start`. +`io.rancher.os.reloadconfig` | Default: `false`| When set to `true`, it reloads the configuration. + + +RancherOS uses labels to determine if the container should be deployed in System Docker. By default without the label, the container will be deployed in User Docker. + +```yaml +labels: + - io.rancher.os.scope=system +``` + + +### Example of how to order container deployment + +```yaml +foo: + labels: + # Start foo before bar is launched + io.rancher.os.before: bar + # Start foo after baz has been launched + io.rancher.os.after: baz +```