Deploying Java applications to cloud servers often reveals configuration challenges that don't appear in local development environments. This article documents the key issues encountered while deploying a Spring Boot application with Langchain4j to an Alibaba Cloud server, along with practical solutions that apply broadly to cloud deployments.

Deployment Environment Overview

The target environment consisted of Java 21, Spring Boot, and Langchain4j integrated with static HTML resources. After initially considering direct JAR execution, Docker containerization was chosen for environment isolation and easier scaling. This decision introduced its own set of challenges but ultimately proved more maintainable.

Essential prerequisites included installing either JDK 21 or Docker on the server and properly configuring the Alibaba Cloud security group or lightweight firewall rules to permit external connections.

Resolving External Network Access Issues

One of the most common deployment obstacles involves applications running inside containers but remaining inaccessible from external networks. The following systematic approach helps identify the root cause.

Cloud Platform Firewall Configuration

Alibaba Cloud provides security group controls that act as the first line of defense. Verify that the specific port your application uses (such as 8080) has been explicitly allowed. Navigate to the lightweight server console, access the Security section, and add a new firewall rule permitting TCP traffic on your target port. Without this rule, all external connection attempts will be blocked before reaching your server.

Operating System Firewall

Even after configuring cloud-level rules, the server's internal firewall may still block traffic. Modern Linux distributions typically use firewalld or ufw. To check firewalld status and open a port, execute these commands:

firewall-cmd --add-port=39111/tcp --permanent
firewall-cmd --reload

For systems using ufw, the equivalent configuration would involve allowing the port through that utility. Always reload or restart the firewall service after making changes to ensure rules take effect.

Docker Port Mapping Verification

When running containers, incorrect port mapping prevents external access entirely. Use docker ps to examine running containers and verify the port bindings. A correct mapping appears as 0.0.0.0:39111->39111/tcp, indicating traffic on the host's port 39111 forwards to the container's port 39111.

If your mapping shows unexpected values, remove the existing container and redeploy with proper port specifications using the -p host_port:container_port flag during container startup.

Application Listening Address Configuration

Spring Boot applications default to listening only on localhost (127.0.0.1), which makes them inaccessible from outside the container or server. This configuration must be explicitly changed to bind to all network interfaces. Add the following to your application.yml configuration file:

server:
  address: 0.0.0.0

When bound to 0.0.0.0, the application accepts connections from any network interface, enabling external access through the mapped ports.

Modifying Default Application Ports

Production environments often require using non-standard ports for security through obscurity or compliance with organizational policies. Changing from the default 8080 to a custom port like 39111 involves coordinated changes across multiple layers.

Begin by modifying the Spring Boot configuration to specify the new port while ensuring the listening address remains 0.0.0.0:

server:
  port: 39111
  address: 0.0.0.0

After updating the configuration, rebuild your application JAR and create a new Docker image. Remove any existing containers running the old configuration and launch a fresh container with updated port mappings:

docker run -d -p 39111:39111 --name myapp myregistry/spring-boot-app:v2

A critical point to understand is the relationship between container ports and host ports. The host port determines how external clients connect, while the container port must match what your application actually listens on. If your Spring Boot application listens on 8080 internally but you want external access on 39111, the mapping becomes -p 39111:8080 rather than matching port numbers.

Finally, update both the Alibaba Cloud firewall rules and the server's internal firewall to explicitly permit traffic on the new port number.

Network Troubleshooting Inside Containers

When network issues arise within containers, traditional diagnostic tools may be unavailable. Understanding alternative approaches prevents frustration during troubleshooting sessions.

DNS Resolution Failures

Upon entering a container to investigate connectivity issues, executing package manager commands like apt-get update might fail with DNS resolution errors:

Temporary failure resolving 'archive.ubuntu.com'

This indicates the container lacks proper DNS configuration. Temporary resolution involves modifying the container's DNS resolver file directly:

echo "nameserver 8.8.8.8" >> /etc/resolv.conf

For permanent solutions, specify DNS servers when launching containers. Adding the --dns 8.8.8.8 parameter ensures reliable DNS resolution from container startup:

docker run -d --dns 8.8.8.8 -p 39111:39111 myregistry/spring-boot-app:v2

Inspecting Port Listening Status

Many administrators rely on netstat for checking listening ports, but this tool isn't always available in minimal container images. The ss command, includde in most base Linux images, provides equivalent functionality:

ss -tlnp

This command displays all TCP listening sockets along with the processes owning them. Verify that your application appears in the output listening on 0.0.0.0:39111 rather than 127.0.0.1:39111. If it only binds to localhost, external access remains impossible regardless of firewall configurations.

Key Takeaways

Successful cloud deployment requires attention to several interconnected configuration points. Port consistency across application configuration, Docker port mappings, and firewall rules forms the foundation of accessible deployments. The application must bind to 0.0.0.0 rather than 127.0.0.1 to accept external connections. Both cloud platform firewalls and operating system firewalls must explicitly permit traffic on the designated ports.

When troubleshooting container networking issues, manual DNS configuration often resolves domain resolution problems. The ss command provides reliable network diagnostics without requiring additional package installations. Understanding these fundamental concepts prepares developers for efficient problem resolution in production environments.