Skip to main content

Deploying to a VPS with Nginx

You have a working REST API. Now let us put it on the internet. This chapter covers deploying your Java application to a VPS with nginx as a reverse proxy and HTTPS via Let's Encrypt.

The deployment architecture:

Client (browser, curl, mobile app)
    │
    │  HTTPS (port 443)
    ▼
┌──────────┐
│  nginx   │  reverse proxy -- handles HTTPS, serves static files
└────┬─────┘
     │  HTTP (port 8080, localhost only)
     ▼
┌──────────┐
│ Java API │  your task-api.jar running as a systemd service
└──────────┘

Nginx handles the public-facing connection (HTTPS, compression, rate limiting). It forwards API requests to your Java process running on localhost:8080. This is called a reverse proxy.

Prerequisites​

Before starting, you need:

  1. A VPS running Ubuntu 22.04 LTS (or newer) with SSH access
  2. A non-root user with sudo privileges
  3. A firewall configured to allow SSH, HTTP, and HTTPS
  4. Your task-api.jar file from the previous chapter
  5. Optionally, a domain name pointed to your server's IP

If you have not set up a VPS before, the initial server setup (creating a user, SSH keys, firewall) is covered in the JavaScript guide's deployment chapter. The steps are identical -- follow that guide through Step 2, then return here.

Step 1: install Java on the server​

SSH into your server:

ssh deploy@YOUR_SERVER_IP

Install the JDK:

sudo apt update
sudo apt install openjdk-21-jre-headless -y

We install openjdk-21-jre-headless (not the full JDK) -- the server only needs to run Java, not compile it. This is a smaller installation.

Verify:

java --version

Result:

openjdk 21.0.2 2024-01-16
OpenJDK Runtime Environment (build 21.0.2+13-Ubuntu)
OpenJDK 64-Bit Server VM (build 21.0.2+13-Ubuntu, mixed mode, sharing)

Step 2: upload your JAR​

Create a directory for the application:

sudo mkdir -p /opt/task-api
sudo chown deploy:deploy /opt/task-api

From your local machine, upload the JAR:

rsync -avz task-api.jar deploy@YOUR_SERVER_IP:/opt/task-api/

Or with scp:

scp task-api.jar deploy@YOUR_SERVER_IP:/opt/task-api/

Verify on the server:

ls -la /opt/task-api/

Result:

total 12
drwxr-xr-x 2 deploy deploy 4096 Jan 15 10:00 .
drwxr-xr-x 3 root   root   4096 Jan 15 09:55 ..
-rw-r--r-- 1 deploy deploy 5120 Jan 15 10:00 task-api.jar

Test the JAR on the server​

cd /opt/task-api
java -jar task-api.jar

Open another SSH session and test:

curl http://localhost:8080/api/health

Result:

{"status":"ok"}

Stop the server with Ctrl+C. It works -- now let us run it properly as a service.

Step 3: create a systemd service​

A systemd service runs your Java process in the background, starts it on boot, and restarts it if it crashes.

Create the service file:

sudo nano /etc/systemd/system/task-api.service

Paste this configuration:

[Unit]
Description=Task Manager REST API
After=network.target

[Service]
Type=simple
User=deploy
Group=deploy
WorkingDirectory=/opt/task-api
ExecStart=/usr/bin/java -jar /opt/task-api/task-api.jar
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/task-api

# JVM settings
Environment="JAVA_OPTS=-Xms64m -Xmx256m"

[Install]
WantedBy=multi-user.target

Key settings:

  • User=deploy -- runs as the deploy user, not root
  • Restart=on-failure -- automatically restarts on crashes
  • WorkingDirectory -- sets the working directory so tasks.dat is stored in /opt/task-api/
  • ReadWritePaths -- allows writing only to the app directory (systemd security)
  • JAVA_OPTS -- JVM memory settings (64MB initial, 256MB max -- more than enough for this app)

Enable and start the service​

# Reload systemd to pick up the new service file
sudo systemctl daemon-reload

# Enable the service (starts on boot)
sudo systemctl enable task-api

# Start the service now
sudo systemctl start task-api

# Check status
sudo systemctl status task-api

Result:

● task-api.service - Task Manager REST API
     Loaded: loaded (/etc/systemd/system/task-api.service; enabled)
     Active: active (running) since Mon 2025-01-15 10:05:00 UTC
   Main PID: 12345 (java)
     Memory: 80.0M
        CPU: 2.5s
     CGroup: /system.slice/task-api.service
             └─12345 /usr/bin/java -jar /opt/task-api/task-api.jar

Viewing logs​

# Recent logs
sudo journalctl -u task-api -n 50

# Follow logs in real time
sudo journalctl -u task-api -f

# Logs since last boot
sudo journalctl -u task-api -b

Service management commands​

sudo systemctl start task-api    # start
sudo systemctl stop task-api     # stop
sudo systemctl restart task-api  # restart
sudo systemctl status task-api   # check status

Step 4: install and configure nginx​

sudo apt install nginx -y

Create the nginx configuration:

sudo nano /etc/nginx/sites-available/task-api
server {
    listen 80;
    listen [::]:80;

    server_name YOUR_DOMAIN_OR_IP;

    # Proxy API requests to the Java application
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeouts
        proxy_connect_timeout 10s;
        proxy_send_timeout 30s;
        proxy_read_timeout 30s;
    }

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Deny access to hidden files
    location ~ /\. {
        deny all;
    }
}

Replace YOUR_DOMAIN_OR_IP with your domain or server IP.

Enable the site​

# Create symlink
sudo ln -s /etc/nginx/sites-available/task-api /etc/nginx/sites-enabled/

# Remove default site
sudo rm -f /etc/nginx/sites-enabled/default

# Test configuration
sudo nginx -t

Result:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
# Reload nginx
sudo systemctl reload nginx

Test through nginx​

curl http://YOUR_DOMAIN_OR_IP/api/health

Result:

{"status":"ok"}

The request flows: client → nginx (port 80) → Java API (port 8080) → response back.

Step 5: HTTPS with Let's Encrypt​

Install Certbot:

sudo apt install certbot python3-certbot-nginx -y

Obtain a certificate (requires a domain name):

sudo certbot --nginx -d yoursite.com

Certbot will:

  1. Verify domain ownership
  2. Obtain and install the certificate
  3. Update nginx config for HTTPS
  4. Set up HTTP → HTTPS redirect

Test:

curl https://yoursite.com/api/health

Result:

{"status":"ok"}

Automatic renewal​

sudo certbot renew --dry-run

Certbot sets up a systemd timer for automatic renewal every 90 days.

Step 6: restrict the Java server to localhost​

Since nginx handles all public traffic, the Java server should only accept connections from localhost. Update ApiServer.java:

// Bind to localhost only -- nginx will proxy public traffic
HttpServer server = HttpServer.create(
    new InetSocketAddress("127.0.0.1", 8080), 0
);

Rebuild, upload, and restart:

# On your local machine
javac *.java
jar cfm task-api.jar MANIFEST.MF *.class
rsync -avz task-api.jar deploy@YOUR_SERVER_IP:/opt/task-api/

# On the server
sudo systemctl restart task-api

Now port 8080 is not accessible from the outside -- only nginx can reach it.

Deploying updates​

Whenever you update your code:

# 1. Build locally
javac *.java
jar cfm task-api.jar MANIFEST.MF *.class

# 2. Upload
rsync -avz task-api.jar deploy@YOUR_SERVER_IP:/opt/task-api/

# 3. Restart the service
ssh deploy@YOUR_SERVER_IP "sudo systemctl restart task-api"

Deploy script​

Create deploy.sh on your local machine:

#!/bin/bash
set -euo pipefail

SERVER="deploy@YOUR_SERVER_IP"
REMOTE_PATH="/opt/task-api"

echo "Building..."
javac *.java
jar cfm task-api.jar MANIFEST.MF *.class

echo "Uploading..."
rsync -avz task-api.jar "$SERVER:$REMOTE_PATH/"

echo "Restarting service..."
ssh "$SERVER" "sudo systemctl restart task-api"

echo "Checking health..."
sleep 3
curl -sf https://yoursite.com/api/health && echo " -- OK" || echo " -- FAILED"

echo "Deployment complete!"
chmod +x deploy.sh
./deploy.sh

Monitoring​

Check if the service is running​

sudo systemctl status task-api

View application logs​

# Last 100 lines
sudo journalctl -u task-api -n 100

# Follow in real time
sudo journalctl -u task-api -f

# Errors only
sudo journalctl -u task-api -p err

Check resource usage​

# Memory and CPU
ps aux | grep java

# Detailed JVM info
jcmd $(pgrep -f task-api) VM.info

Health check endpoint​

The /api/health endpoint we built lets you verify the API is working. Monitoring services like UptimeRobot or Healthchecks.io can hit this endpoint periodically and alert you if it goes down.

Security checklist​

Review the full server hardening steps from the JavaScript guide's deployment chapter -- the same steps apply here:

  • Non-root user with sudo
  • SSH key authentication (password auth disabled)
  • Firewall (ufw) allowing only SSH, HTTP, HTTPS
  • HTTPS with Let's Encrypt
  • Automatic security updates (unattended-upgrades)
  • Fail2Ban for brute-force protection
  • Java server bound to 127.0.0.1 (not accessible publicly)
  • systemd service with NoNewPrivileges and ProtectSystem

Complete deployment summary​

Local machine                          VPS
┌─────────────┐                ┌──────────────────────────────┐
│ .java files │                │                              │
│      │      │                │   nginx (port 443/80)        │
│   javac     │                │      │                       │
│      │      │                │      ▼  proxy_pass           │
│  .class     │    rsync       │   java -jar task-api.jar     │
│      │      │ ──────────►    │      (port 8080, localhost)  │
│   jar cfm   │                │      │                       │
│      │      │                │   tasks.dat (persistence)    │
│ task-api.jar│                │                              │
└─────────────┘                └──────────────────────────────┘

What comes next​

You now have a Java REST API running in production. The next two chapters cover build tools that make managing dependencies, compiling, and packaging much easier:

  • Maven -- the most widely used Java build tool, with Gson for JSON
  • Gradle -- the modern alternative, with Jackson for JSON

Beyond that, you could:

  • Add a database -- SQLite for simple apps, PostgreSQL for production
  • Use a framework -- Spring Boot, Quarkus, or Micronaut for more features
  • Add authentication -- JWT tokens or session-based auth
  • Containerize with Docker -- consistent deployments across environments
  • Set up CI/CD -- automatic builds and deploys on git push
  • Add logging -- structured logging with SLF4J and Logback
  • Write tests -- JUnit for unit tests, integration tests for API endpoints

Summary​

  • Install openjdk-21-jre-headless on the server (runtime only, no compiler needed).
  • systemd manages the Java process -- start on boot, restart on crash, centralized logging.
  • nginx acts as a reverse proxy -- handles HTTPS, forwards requests to localhost:8080.
  • Let's Encrypt provides free HTTPS certificates with automatic renewal.
  • Bind the Java server to 127.0.0.1 so it is only reachable through nginx.
  • Deploy with a simple rsync + systemctl restart workflow.
  • Monitor with journalctl and a /api/health endpoint.

Your REST API is live. Continue to Maven and Gradle to learn how build tools manage dependencies, simplify packaging, and improve the API project with proper JSON libraries.