Skip to content

Latest commit

 

History

History
329 lines (265 loc) · 11.5 KB

using.adoc

File metadata and controls

329 lines (265 loc) · 11.5 KB

Using Atomic Developer Bundle

Principles

Consider ADB to be ephemeral and do not store data in it long term. It is recommended that you do the following:

  • Back up your code.

  • Use a source control system.

  • Mount your code into the box from your host system. The ADB Vagrantfiles already mount your home directory from the host into ADB using vagrant-sshfs. Additional shares can also be defined. Refer to the bi-directional folder sync section for more information.

Doing these things is beyond the scope of this document. Consult your Operating System manuals and the Vagrant website for more details.

Once you start ADB you can use it as:

  • a server resource for host-based tools (Eclipse/CLIs) or

  • a Linux virtual machine.

For a quick high level glimpse at ADB and how you can use it refer to the Readme.

For detailed instructions on how to install ADB refer to the Installation Document.

Using ADB with host-based tools (Eclipse and CLIs)

Many users have preferred development environments built from tools running on their development workstation. Even if these workstations are unable to run containers or container-components natively, the user may still want to use their preferred tools, editors, etc. ADB can be used with these tools in a way that makes it seamless to interact with files, preferred development tools, etc.

ADB exposes the docker daemon port and orchestrator access points so that tools like Eclipse and various CLIs can interact with them. For security reasons, some ports, such as the docker daemon port, are TLS protected. Therefore some configuration is required before the service can be accessed. Vagrant-service-manager makes this configuration simple by providing easy access to the TLS certificates and the other environment variables or configuration information.

To use ADB with Host-Based tools:

Install and configure Vagrant and plugins

  1. Install the vagrant-service-manager plugin:

    vagrant plugin install vagrant-service-manager

    More information about the vagrant-service-manager plugin is available in the source repository_.

  2. Enable the desired service(s) in the ADB Vagrantfile as:

    config.servicemanager.services = 'openshift'
    Note

    • Docker is the default service for ADB and does not require any configuration to ensure it is started. Red Hat Enterprise Linux Container Development Kit, which is based on Atomic Developer Bundle, automatically starts OpenShift.

    • You can use a comma-separated list to enable multiple services. For instance: docker, openshift.

  3. Enable the relevant option for the services you have selected in the Vagrantfile as:

    For example, specific versions of OpenShift can be specified using the following variables:

    • config.servicemanager.openshift_docker_registry = "docker.io" - Specifies the registry from where the service should be pulled.

    • config.servicemanager.openshift_image_name = "openshift/origin" - Specifies the image to be used.

    • config.servicemanager.openshift_image_tag = "v1.2.0" - Specifies the version of the image to be used.

  4. Start ADB using vagrant up. You will find detailed installation instructions in the Installation document.

Configure your environment

Configure the environment and download the required TLS certificates using the plugin. The example below shows the command and the output for Linux and Mac OS X. On Microsoft Windows the output may vary depending on the execution environment:

$ vagrant service-manager env
# docker env:
# Set the following environment variables to enable access to the
# docker daemon running inside of the vagrant virtual machine:
export DOCKER_HOST=tcp://10.1.2.2:2376
export DOCKER_CERT_PATH=/foo/bar/.vagrant/machines/default/virtualbox/docker
export DOCKER_TLS_VERIFY=1
export DOCKER_API_VERSION=1.21

# run following command to configure your shell:
# eval "$(vagrant service-manager env)"

Setting these environment variables allows programs, such as Eclipse and the docker CLI to access the docker daemon.

Note

When the OpenShift service is running in the VM, a Docker registry is also started. This Docker registry can be used by external tools such as Eclipse to push or pull images. The Docker registry URL is exported as a variable, and can be accessed by running the following command:

$ vagrant service-manager env openshift
# openshift env:
# You can access the OpenShift console on: https://10.1.2.2:8443/console
# To use OpenShift CLI, run: oc login https://10.1.2.2:8443
export OPENSHIFT_URL=https://10.1.2.2:8443
export OPENSHIFT_WEB_CONSOLE=https://10.1.2.2:8443/console
export DOCKER_REGISTRY=hub.openshift.centos7-adb.10.1.2.2.xip.io

Develop your application with the CLI

If you do not have the docker CLI, you can use the install-cli command:

$ vagrant service-manager install-cli docker

However, if you are using the docker CLI, you can just run it from the command line and it will work as expected.

Note

If you encounter a Docker client and server version mismatch such as:

$ docker ps
Error response from daemon: client is newer than server (client API version: 1.21, server API version: 1.20)

You will need to download an earlier compatible version of Docker for your host machine. Docker release versions and docker API versions are not the same. Typically, you will need to try the previous release (i.e. if you get this error message using a docker 1.9 CLI, try a docker 1.8 CLI).

Configure Eclipse

If you are using Eclipse, you should follow these steps:

  1. Install the Docker Tooling plugin.

  2. Enable the three Docker Views (Docker Explorer, Docker Containers, and Docker Images) by choosing Windows → Show Views → Others.

  3. Enable the Console by choosing Windows → Show Views → Console.

  4. In the Docker Explorer view, click to add a connection and provide a connection name. If your environment variables are set correctly, the remaining fields will auto-populate. If not, using the output from vagrant service-manager env docker, put the DOCKER_HOST variable in the TCP Connection field and the DOCKER_CERT_PATH variable in the Authentication Section path.

  5. You can test the connection and then accept the results. At this point, you are ready to use ADB with Eclipse.

    Note
    		 Testing has been done with Eclipse 4.5.0.

Using the VM via SSH

You can access the VM by using ssh to login to it with the following command:

vagrant ssh

You are now at a shell prompt inside the Vagrant VM. You can now execute commands and use the tools provided.

Using sccli

You can use sccli to manage the orchestration services inside ADB. With sccli, you can start, stop, restart, and get the status of orchestration providers like OpenShift, Docker, and Kubernetes.

Using Atomic App and Nulecule

You can use Atomic App and Nulecule to run ADB. Details on these projects can be found at:

Note
 Many Nulecule examples expect a working Kubernetes environment. Use the Vagrantfile and refer the corresponding README to set up a single node Kubernetes environment.

Vagrant bi-directional folder sync

For an introduction into Vagrant’s synced folders feature, we recommend you to start with the corresponding Vagrant documentation.

Synced folders enable movement of files (such as, code files) between the host and the Vagrant guest. Apart from the rsync synced folder type, synced folder types are usually bi-directional and continuously sync the folder while the guest is running.

The following synced folder types work out of the box with the ADB Vagrant box, for both Virtualbox as well as Libvirt/KVM :

vagrant-sshfs

vagrant-sshfs works with Linux/GNU, OS X and Microsoft Windows. It is the recommended choice for enabling synced folders and the custom Vagrantfile examples use it per default.

In the suggested default configuration, your home directory on the host (for example, /home/john) is synced to the equivalent path on the guest VM (/home/john). For Windows users, there is a little caveat, their home directory (for example, C:\Users\john) must be mapped to a Unix style path (/c/users/john).

nfs

NFS works with Linux/GNU and OS X.

The following folder types are not officially supported but are available as-is:

SMB

SMB works for Microsoft Windows. This folder type is not officially supported for ADB.

You need to install cifs-utils RPM inside ADB, for the SMB synced folder type to work:

sudo yum install cifs-utils
VirtualBox shared folder

Virtualbox shared folder for Virtualbox users with Virtualbox guest additions. Currently Virtualbox guest additions do not come pre-installed in the ADB Vagrant box.

For installation details, please refer to Virtualbox documentation. You can also use vagrant-vbguest plugin to install Virtualbox guest additions in ADB Vagrant box.

Some useful commands

vagrant halt

Stops the vagrant box temporarily.

You can use vagrant halt to gracefully stop the vagrant box and continue with your work when you start next with vagrant up. This will not cause any loss of data. It is recommended to stop the vagrant box before you shutdown your machine, to save CPU and RAM consumption. Also, powering off your machine without stopping the vagrant box, could cause errors when you resume using it.

vagrant status

Checks the Status of the Vagrant box.

Use vagrant status to check the status of ADB and to check which virtualization provider is being used and the status of the provider.

vagrant destroy

Destroys the Vagrant box permanently.

Warning
 Using vagrant destroy will destroy any data you stored in the Vagrant box. You will not be able to restart this instance and will have to create a new one using vagrant up.
vagrant global-status

Displays the state of all active Vagrant environments on your system. Use this to see the status of your Vagrant environment.
You can use vagrant global-status --prune to prune invalid entries, based on stale results.

vagrant plugin list

Verifies the vagrant plugins installed on your system. Use this to see a list of the vagrant plugins in your system.

vagrant box list

Lists the vagrant boxes on your system. You can use this to verify that your box is installed.

vagrant provision

Use this to provision the service of your choice if it fails to start on Vagrant up.