Skip to main content
Dat 2. semester
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

8. Deployment

Deployment on Droplet with Docker and Caddy

When you have a Javalin project ready to deploy, there are several ways to do it. In the old days, we deployed our Java projects on an Apache Tomcat Server, and we accessed it by http://ip:port. We called it the blue pill solution. But things have changed. So welcome to the days of the red pill solution.

Red or Blue

We want to be able to access our Javalin project through a domain name. And we want to use https. And we also want to host a static page on the main domain name. The idea is that the static webpage can be used as a portfolio content page, that links to your Javalin web applications each running on their own subdomain. The setup will be able to handle a number of Javalin web applications and static webpages, but as a beginning we set up only one. Each web application will run in an isolated Docker container.

Since you are still here, we assume that you are ready to take the next step.

You have chosen the red pill. Good choice. Let’s go!

This is how you can deploy a Javalin webproject on a virtual machine (VM) running Ubuntu and Docker.

Prerequisites

  • A configured Virtual Machine setup up after this tutorial step 1-7. The VM is running on Digital Ocean
  • A Postgresql database running in a docker container on port 5432
  • A Javalin web project ready to run on port 7070
  • A domain name or subdomain with DNS set to the IP of your VM. Video-tutorial is here.
  • A firewall that allows access for port 80 and 443 (http and https). Video-tutorial is here
  • A SSH connection to the VM

Goal

We wish to host the Javalin web application and make it accessible through a subdomain.

We also wish to get access to the web applications through HTTPS. For this we use Caddy Server as a reverse proxy server and static file server. Caddy Server is also running in its own Docker Container.

As a last thing, we also want to use a Postgresql database from our Javalin web application.

Recipe

1. Setup Fourthingsplus demo site

As a showcase we will use this Javalin webapp: Fourthingsplus. Clone the project, follow the instructions and create a database. Finally, try to run the project locally, and see that it works.

2. Build your webproject to create a “fat jar”

The instructions for building a fat jar can be found here.

3. Prepare your VM

SSH to your VM as the jetty user. You should be in the home folder of the jetty user. Now change to the deployment folder.

cd deployment

Take a look. The docker-compose.yml file is there. This is where we will define the services that we want to run in Docker containers plus Caddy. Remember Postgres is already running in a container, and the service is configured in the docker-compose.yml file.

4. Setup the database on the VM

Do like you did on the local Postgres instance: Create a fourthingsplus database and execute the sql statements from the fourthingsplus repo README file. Now the database is ready to be used by the Javalin webapp.

5. Copy the fat jar to the VM using rsync

Open a terminal / shell on the local dev machine in the target folder of the web project. If you use the ls command, you should now be able to see the app.jar file, a.k.a. “the fat jar”. Now copy the file to your VM using rsync (remote sync). The syntax is like this:

scp app.jar jetty@<IP>:~/deployment/fourthings/

That’s it! Now the fat jar is copied to the VM. More precisely into the ~jetty/deployment/fourthingsplus folder.

Check on the VM that the app.jar file has been transferred.

6. Creating a Dockerfile for the Javalin web app

Step into the fourthingsplus folder and create a Dockerfile (use nano):

cd ~jetty/deployment/fourthingsplus
nano Dockerfile

The Dockerfile should look like this:

FROM amazoncorretto:21-alpine
COPY ./app.jar /app.jar
EXPOSE 7070
CMD ["java", "-jar", "/app.jar"]

The Dockerfile defines how to build a Docker image for your Javalin web application.

FROM amazoncorretto:21-alpine
COPY ./app.jar /app.jar
EXPOSE 7070
CMD ["java", "-jar", "/app.jar"]

Can you explain what it does?

In summary: The Dockerfile packages your fat JAR together with a Java runtime into a Docker image. When a container is started from this image, your Javalin application runs on port 7070.

Docker Compose will later use this Dockerfile to build the image and start the container.

7. Fixing Caddyfile

Navigate back to the deployment folder. Open a Caddyfile with nano.

nano Caddyfile

It should look like this (change the email to your own):

{
    email jobe@cphbusiness.dk
}

fourthings.showcode.dk {
  reverse_proxy fourthings:7070
}

showcode.dk {
  root * /srv/
  file_server
}

You should change the showcode.dk to your own domain name. The container name fourthings in front of the port 7070 corresponds to the container name where your Javalin web app is running. We will setup that up in the docker-compose.yml file in a sec. Save and close the Caddyfile.

8. Configure the docker-compose.yml

Open the docker-compose.yml file in nano. Now we will add your Javalin web app to the services, and Caddy as well. Since we already have a Postgres service running, we just add to what is already there. The total file should look like this - and remember to change the password placeholder <your_postgres_password> to a real password:

services:

  db:
    image: postgres:16
    container_name: db
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: <your_postgres_password>
    volumes:
    - ./postgres_data:/var/lib/postgresql/data/
    ports:
    - "5432:5432"

  caddy:
    image: caddy:2.7.6
    restart: unless-stopped
    container_name: caddy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./site:/srv
      - ./caddy_data:/data
      - ./caddy_config:/config

  fourthings:
    build:
      context: ./fourthings
      dockerfile: Dockerfile
    container_name: fourthings
    environment:
      - DEPLOYED=PROD
      - JDBC_USER=postgres
      - JDBC_PASSWORD=<your_postgres_password>
      - JDBC_CONNECTION_STRING=jdbc:postgresql://db:5432/%s?currentSchema=public
      - JDBC_DB=fourthingsplus
    ports:
      - "7070:7070"
    restart: unless-stopped

volumes:
  postgres_data:
  caddy_data:
  caddy_config:

You don’t need to change this for now. But notice the container_name is called fourthings. Also, notice that the environment variables:

environment:
      - DEPLOYED=PROD
      - JDBC_USER=postgres
      - JDBC_PASSWORD=datdat2024!
      - JDBC_CONNECTION_STRING=jdbc:postgresql://db:5432/%s?currentSchema=public
      - JDBC_DB=fourthingsplus

are injected into the Javalin container. It’s of course important to match the credentials and database variables with those expected of the Javalin web app. By the way, these a read from the ConnectionPool class in the webapp.

9. Setup a static portfolio page

You can this now - or wait until you feel like it. But it’s a good idea to have a static page that can be used as a portfolio page. This is the main page that will be shown when you access your domain name. The static page can link to your Javalin web apps.

The tutorial for setting up a static page can be found here.

10. Setup your DNS

We want to access our Javalin web application through a subdomain and our static portfolio page through the main domain.

To make this work, we need to create DNS records that point to the public IP address of our Droplet.

Create DNS records

Create the following two A records:

TypeHostnameValue
A@Your Droplet’s public IP address
AfourthingsYour Droplet’s public IP address

For example, if your domain is showcode.dk, these records will allow you to access:

  • https://showcode.dk – Your static portfolio page, served by Caddy.
  • https://fourthings.showcode.dk – Your Javalin web application, accessed through Caddy.

Both domain names point to the same Droplet. Caddy uses the requested domain name to determine which website or application to serve.

Where do you configure DNS?

You must create the DNS records at the provider that manages DNS for your domain.

If your DNS is managed by DigitalOcean:

  1. Log in to DigitalOcean.
  2. Navigate to Networking → Domains.
  3. Select your domain. If it has not been added yet, click Add a Domain.
  4. Create the two A records shown above.
  5. Save your changes.

If your DNS is managed by another provider (e.g. DanDomain):

Log in to your DNS provider and create the same two A records there.

Important: Adding a domain to DigitalOcean does not automatically make DigitalOcean your DNS provider. Your DNS records must be configured at the provider whose nameservers are authoritative for your domain.

Verify your DNS configuration

You can check your DNS records from a terminal on your local computer:

nslookup showcode.dk
nslookup fourthings.showcode.dk

Replace showcode.dk with your own domain name.

Both commands should return the public IP address of your Droplet.

DNS changes may take some time to propagate.

Once your DNS records are working, you are ready to start your Docker containers. Caddy will automatically attempt to obtain HTTPS certificates for your domain names, provided that ports 80 and 443 are accessible.

11. Spin up the docker containers and enjoy the rest

cd ~jetty/deployment
sudo docker compose up -d

12. Debugging and error finding

So what if the setup doesn’t work?

The first shot is to look at the log files of the various containers.

  • sudo docker ps to check if the containers are running (including Postgres)
  • sudo docker logs caddy to check if the reverse proxy or https goes wrong
  • sudo docker logs fourthings to check if the Javalin web app is running

If there is somethings wrong:

  1. Stop the containers: sudo docker compose down
  2. Correct your files
  3. Spin up the containers again: sudo docker compose up -d

If something is wrong with your Javalin project, you need to rebuild the project and copy the fat jar to the VM again - as described in step 5 above.

Once you have built a new fat JAR and copied it to your Droplet, you must:

cd ~/deployment
sudo docker compose up -d --build fourthings

This command:

  1. --build rebuilds the Docker image using your Dockerfile and the updated app.jar.
  2. -d runs the container in the background.
  3. fourthings specifies which service to rebuild and start.
  4. Docker Compose automatically recreates the fourthings container when its image has changed. Your PostgreSQL and Caddy containers can continue running. There is no need to stop them.

Now the updated version of your Javalin web app is up and running.

This can be done in an automated fashion with Continuous Integration and Deployment - but for now we do it manually to avoid more configuration. And for pedagogical reasons, to be able to appreciate each step involved. On 3rd semester you will learn more about CI/CD, and how to automate the process.