Building and deploying development images

Your local environment is ready for building and deploying Maximo® Manage into a Podman container after you complete pulling and tagging base images.

Before you begin

Before you begin:

Complete pulling and tagging base images as described in the setup documentation.
Ensure Podman is installed and running on your system.
Have access to your database connection details (URL, credentials, schema owner).
Obtain the correct crypto keys from your cluster deployment if using an existing encrypted database.

Important: The crypto key values in the Docker build file must match your database encryption keys. If you are using the same database as your cluster deployment, both CRYPTO and CRYPTOX key pairs must be set correctly to avoid encryption errors.

About this task

You can use a Docker build file to build new development images.

The development process consists of the following steps:

Make the required changes and customizations to your Java class files.
Copy the class files to the correct folder structure.
Build the new WLP development image by using the Docker build file. Download the build file.
Deploy the new development image in a new Podman container, which starts the MXServer.
Use a browser to access the Manage application.

Procedure

Update the source code and add your customizations.
You can update existing Java™ source files, add custom Java classes, or update configuration files.
1. Organize the compiled Java classes and any other custom files, such as XML configuration files, scripts, or deployment descriptors, into a folder structure that matches the /applications folder structure that is used by Maximo Manage.
2. Ensure that the /applications folder is in the same directory as the ./manage-developer folder, which contains the Docker build file.
  
  Note: The provided Docker build file includes an ADD command that adds all files and subfolders under the /applications folder to the image.

Update the Docker build file that you downloaded.

Edit the following environment variables to reflect your database details.

ENV MXE_DB_URL='jdbc:db2://9.30.213.13:50000/bludb'
ENV MXE_DB_SCHEMAOWNER=maximo
ENV MXE_DB_DRIVER='com.ibm.db2.jcc.DB2Driver'
ENV MXE_SECURITY_OLD_CRYPTO_KEY=SzUwFenwARerIQCMotXkisoU
ENV MXE_SECURITY_CRYPTO_KEY=SzUwFenwARerIQCMotXkisoU
ENV MXE_SECURITY_OLD_CRYPTOX_KEY=SzUwFenwARerIQCMotXkisoU
ENV MXE_SECURITY_CRYPTOX_KEY=SzUwFenwARerIQCMotXkisoU
ENV MXE_DB_USER=maximo
ENV MXE_DB_PASSWORD=maximo

Note: The crypto key values assume that you are using the same database as the cluster deployment. In that case, Maximo Manage is already installed and the database is already encrypted. Therefore, both pairs of CRYPTO and CRYPTOX keys must be set as environment variables.

To access the Maximo Manage local development environment from outside the localhost, add the following commands to the Docker build file before you set the environment variables:

WORKDIR /opt/ibm/wlp/usr/servers/defaultServer
RUN mv server.xml server-BAK.xml
RUN mv server-dev.xml server.xml
WORKDIR /<maximo_home_dir>/deployment/was-liberty-default/config-deployment-descriptors/maximo-all/maximouiweb/webmodule/WEB-INF
RUN mv web-dev.xml web.xml

Run the following command from the directory that contains the ./manage-developer/Dockerfile file.
podman build --build-arg BUNDLE=all --tag managedev:latest -f ./manage-developer/Dockerfile

Note: You can pass the server bundle type as a build argument. In this example, you build the all WLP image. Depending on the bundle image type that you downloaded from the Red Hat® OpenShift® registry, you must pass the appropriate bundle image type argument. Valid bundle types are all, ui, cron, report, and mea. For example, tag the new development image with --tag managedev:latest.
After the build is complete, run the following command to view the images in the local image registry.
podman images
You can see at least three images: manage-all-dev, manage-admin-dev, and managedev.
After you build the development image, run the image in a Podman container. Use the following command to create the container and start the image.
podman run -dt --name maximo_dev -p 9080:9080/tcp localhost/managedev:latest
The -p option maps the host and container TCP ports. In this example, the URL for the Manage application is http://localhost:9080/maximo. The --name flag assigns a name to the container. If you do not set this flag, an arbitrary name is assigned.
To check whether the maximo_dev container is running, run the following command.
podman ps -a
You can see a container named maximo_dev for the managedev image.
Start the maximo_dev container.

The development image is a WebSphere Liberty Profile (WLP) image. It deploys the Manage application to Liberty and starts MXServer. The following command starts the container in interactive mode by using the -i option. Interactive mode is required so that MXServer continues to run until you stop the container.

podman start -a -i maximo_dev
At this point, you can see MXServer starting and services such as BulletinBoard, Workorder, and Scheduler. After the server starts, you can access Manage in a browser.
Note: During testing, the Podman container sometimes displayed an out-of-memory exception during server startup. The cause is not yet known. In most cases, recreating the machine resolves the issue. Adjusting the CPU and memory allocation during machine initialization can also help. The following commands are helpful:
```
podman machine stop
podman machine rm
podman machine init --cpus 2 --memory 2048 --disk-size 20
podman machine start
```
For more information about resolving out-of-memory issues, see How can I increase the number of CPUs?
Tip: Useful Podman commands:
```
podman machine start (or stop)
podman machine ls (status)
podman images
podman machine rm (removes the VM. Will lose local registry and everything else)
podman machine init (initializes and creates a new VM – start fresh)
podman ps -a
```

Results

After completing these steps, you can access the Maximo Manage application at http://localhost:9080/maximo in your browser.

What to do next

If you encounter issues during deployment, review the following troubleshooting guidance:

Crypto key errors: Verify that both MXE_SECURITY_OLD_CRYPTO_KEY and MXE_SECURITY_CRYPTO_KEY match your database encryption keys. If using a new database, both values should be identical. If using an existing encrypted database, obtain the correct keys from your cluster deployment.
CryptoX key errors: Ensure MXE_SECURITY_OLD_CRYPTOX_KEY and MXE_SECURITY_CRYPTOX_KEY are set correctly. These keys are required for additional encryption features and must match your database configuration.
Port mapping errors: Verify the port mapping uses the correct format: -p 9080:9080/tcp. The first port (9080) is the host port, and the second port (9080) is the container port.
Out-of-memory errors: If you encounter out-of-memory exceptions during server startup, try recreating the Podman machine with increased resources as described in the note above, or adjust the JVM memory settings in the Docker build file.