Creating a workbench Liberty server in a Docker container by using developer tools

Use WebSphere® Developer Tools to create a reference in the workbench to a Liberty server that runs in a Docker container. You can use this reference to handle your server requests from the workbench.

Before you begin

Install WebSphere Developer Tools. For more information, see Installing Liberty developer tools and (optionally) Liberty.
Install Docker. The tools support Docker version 1.10.2 and later. For more information about installing Docker, see Docker: Get Started.
Use Docker Tooling to manage Docker images and containers. To use the Docker Tooling feature, install WebSphere Application Server Liberty Docker Tools, which includes Docker Tooling. For more information, see Linux® Tools Project/Docker Tooling/User Guide.
Start a Liberty server in a local Docker container and ensure that both the HTTP and HTTPS ports are mapped to the host. For more information about starting a Liberty server in a local Docker container, see WASdev GitHub.
If you are using macOS, by default Docker commands are located in the /usr/local/bin directory. If you change the location of the Docker commands, complete the following steps so that the tools can find the Docker commands:
1. Add the following line to the eclipse.ini file:
```
-Dcom.ibm.ws.st.envPath=<Docker commands directory>
```
2. Restart Eclipse.

About this task

You can install WebSphere Application Server Liberty and download add-ons in the Liberty Repository from the WASdev community download site. After you install Liberty, you can select your Docker container. Then, you can enter the Liberty server security credentials for your Liberty server to create a workbench reference to your Liberty server in your Docker container.

If a Docker command times out as you complete these steps, you can work around this problem. Set the com.ibm.ws.st.DockerCommandTimeoutInSeconds system property to a time in seconds. By default, this property is set to 10.

Important: You cannot select Clean Server on Next Start for Liberty servers that are running in a Docker container.

Procedure

In the workbench, open the Servers view by clicking the Servers tab.

Tip: If the Servers view is not visible, select Window > Show view > Other... and type Server in the filter text. Then, select Servers.
Right-click the Servers view and select New > Server.
To select your server type, select IBM > Liberty Server.
Enter the localhost value in the Server's host name field.
Click Next.

Note: Ensure that the Liberty runtime environment has the same set of features as the selected Liberty docker image. Also, ensure that they are configured to use the same level of the Java™ runtime environment (JRE). The Liberty runtime environment is used as the target runtime in the development environment. A mismatch between the local system runtime and the JRE used in the Liberty docker image can cause problems from configuration errors to application publishing issues.
If the tools prompt you to install WebSphere Application Server Liberty, either because it is not installed or because you need to input the directory where it is installed, complete one of the following options. Otherwise, skip this step.

You need Liberty to be installed so that you can create a workbench reference to a Liberty server in a Docker container.

If you previously installed Liberty, complete the following steps to select the directory where you installed it:
1. Select Choose an existing installation.
2. In the Path field, type or browse for the directory where you installed the WebSphere Application Server Liberty.
3. On the Liberty Runtime Environment page, click Next.
  
  The application-serving environment is selected. Skip the rest of this step.
If you want to install Liberty from an archive file that was previously downloaded, complete the following steps:
1. Select Install from an archive or repository, and click Next.
2. In the Destination field, type or browse to the directory where you want to install the Liberty runtime environment.
  
  If you type a path that does not exist, then a folder for that path is created automatically at the end of the procedure when you click Finish.
3. Select Install a new runtime environment from an archive.
4. In the Path field, either type or browse to the archive file on the local file system, and click Next.
5. In the Install Add-ons page, click Install or Install Pending to make your selection of add-on archive files that you want to install on the Liberty runtime environment.
  You can install an add-on archive file from your local file system, download an add-on archive file, or use a combination of both when you install multiple add-on archive files.
  
  This download site includes add-ons that you can select from the Liberty Repository, such as runtime features, samples, or open source integration.
  If you want to install add-on archive files from your local file system, complete the following steps:
  1. Click Add Archive.
  2. In the Add-on archive field, type or browse to the add-on archive file on the local file system.
  3. Click OK.
  If you have more add-on archive files to install from your local file system, repeat this procedure until you are done.
  If you want to install add-on files from a custom repository, complete the following steps:
  1. To add the repository, click Configure Repositories.
  2. Click New....
  The files are then added to the list of add-on files.
  After you complete your selection in the Install Add-ons page, click Next.
6. In the License Acceptance page, if you accept the license terms, select I accept the terms of all the license agreements then click Next.
If you want to download and install the no-charge developer edition for Liberty, complete the following steps:
1. Select Install from an archive or repository, and click Next.
2. In the Destination field, type or browse to the directory where you want to install the Liberty runtime environment.
  
  If you type a path that does not exist, then a folder for that path is created automatically at the end of the main procedure when you click Finish.
3. Select Download and install a new runtime environment from ibm.com, choose a runtime environment version, and then click Next.
4. In the Install Add-ons page, click Install or Install Pending to make your selection of add-on archive files that you want to install on the Liberty runtime environment.
  You can install add-on archive files by one of the following methods:
  - From your local file system
  - By downloading files
  - By using a combination of both, when you install multiple add-on archive files
  If you want to install add-on archive files from your local file system, complete the following steps:
  1. Click Add Archive.
  2. In the Add-on archive field, type or browse to the add-on archive file on the local file system.
  3. Click OK.
  If you have more add-on archive files to install from your local file system, repeat this procedure until you are done.
  If you want to install add-on files from a custom repository, complete the following steps:
  1. To add the repository, click Configure Repositories.
  2. Click New....
  The files are then added to the list of add-on files.
  After you complete your selection in the Install Add-ons page, click Next.
5. In the License Acceptance page, if you accept the license terms, select I accept the terms of all the license agreements then click Next.
On the Liberty Server page, select Server in a Docker container.
Select your Docker container from the Container name menu.

Tip: If you do not see your Docker container in the Container name menu, click Refresh to refresh the list.
Enter the Liberty server security credentials.
Your values for the User name and Password fields must correspond to a user that is defined in a user registry that has an administrator role. If the tools cannot find a basic user registry that defines the specified user, the tools display the Security Verification window. If the tools display the Security Verification window, complete one of the following options:
- Select Create to add a basic user registry that defines a user with your values and an administrator role.
- Select Proceed to proceed if the user is defined in another user registry type.
- Select Cancel to change the User name and Password that you entered.
Enter the value for the Secure port field with the HTTPS port that is specified in the server configuration.
Click Finish.

Results

You created a workbench server reference to a server that is running in a Docker container.

To see the server that you created and its server configuration, open the Servers view.
To see the project, the server folder, and the server configuration files, open the Enterprise Explorer view.

What to do next

You can edit the server configuration. For more information, see Editing the Liberty configuration by using developer tools.
Restriction: The tools do not support specifying include files by using absolute paths in the server configuration. To work around this problem, specify include paths by using the predefined server variables such as server.config.dir and shared.config.dir, instead of by using absolute paths.
To start or stop a server, or add or remove applications on the server, right-click your server to use the server context menu or use the tray buttons in the Servers view.
Tip: To access these options, select the Server Entry in the Servers view. Do not select a server configuration such as the Server Configuration or server.xml entry.
You can configure your Liberty server to authenticate users with Tivoli® Directory Server.
1. Right-click Servers.
2. Select Utilities > Add config snippets.
3. Select the snippets and accept the licenses agreements.
The tools download the configuration snippets that you selected and add them to the server.xml file.
You can create and edit your server environment files in the product documentation.