Deploying To Linux With Nginx

You can deploy and serve an Alpas web app behind a proxy server by creating a fat jar using alpas jar command and then copying the jar over to the root of your server.


You can use any Linux server for deploying, but we recommend Ubuntu 18.04 LTS or higher. Here are the pre-requisites for your deployment server.

  • Ubuntu 18.04 or higher
  • Nginx
  • JRE 9 or higher
  • root access

You can use a tool like Cleaver to quickly provision a server and create a new site with SSL certificates ready to go.

Preparing the server - First Run

/alert/The following steps assume that your domain name is, your app name is example, and your web root folder for this app is under /home/cleaver/ Make changes accordingly for your web app.

On your provisioned server -

  1. Install JRE: sudo apt install openjdk-11-jre-headless
  2. Create a service file /etc/systemd/system/ and paste the following contents - note: if you used Cleaver to provision your server, the file exists but you will need to modify it accordingly


ExecStart=/usr/bin/java -jar example.jar


  1. Create a nginx config file for your domain /etc/nginx/sites-available/ and paste the following - note: if the file already exists, you will need to make modifications accordingly

include cleaver-conf/*.conf;

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''   '';

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    include /etc/nginx/h5bp/directive-only/ssl.conf;
    include /etc/nginx/h5bp/directive-only/ssl-stapling.conf;

    ssl_certificate       /etc/nginx/ssl/;
    ssl_certificate_key   /etc/nginx/ssl/;
    ssl_dhparam /etc/nginx/dhparams.pem;

    charset utf-8;

    include cleaver-conf/*.conf;

    client_max_body_size 0;
    client_header_buffer_size 50M;
    proxy_read_timeout     1200;
    proxy_connect_timeout  240;

    access_log off;
    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }
    error_log /var/log/nginx/ error;

    location / {
        proxy_pass              http://localhost:9999;
        proxy_http_version      1.1;
        proxy_set_header        X-Forwarded-For $remote_addr;
        proxy_set_header        X-Forwarded-Proto      $scheme;
        proxy_set_header        X-Forwarded-Host       $http_host;
        proxy_set_header        Upgrade                $http_upgrade;
        proxy_set_header        Connection             $connection_upgrade;

    root /home/cleaver/;
    location ^~ /.well-known/acme-challenge/ {
        allow all;

Make note of the port number 9999 above in proxy_pass http://localhost:9999;. You can change it to any random port number but you'll need this port number value in your .env file later.

  1. Check to see if /etc/nginx/sites-enabled/ exists.

If not, you need to create a link pointing to the above config file we created by running: cd /etc/nginx/sites-enabled && ln -s ../sites-available/ .

  1. Now you need to copy these files from your local project folder over to remote /home/cleaver/ folder:
  • app_log_config.xml
  • console_log_config.xml
  • .env
  • example.jar

You can use scp command to copy from your local machine to the remote server. This is how we'd copy an example.jar file (be sure to run alpas jar command in your project's root to create jar file):

scp -i ~/.ssh/cleaver/<private-ssh-key> ./example.jar cleaver@<server-ip>:/home/cleaver/

<private-ssh-key> is the private ssh key on your local machine that allows you to connect to the remote server.

  1. Open /home/cleaver/ file on the remote server and make few changes:


  1. Let's reload the service file: sudo systemctl daemon-reload.
  2. Let's test nginx config to make sure everything is good: sudo service nginx configtest. If this says [ FAIL ], then something is wrong in your nginx config file. Don't proceed before fixing it.
  3. If step 8 says [ OK ], then run sudo service nginx reload.
  4. Let's restart the actual web app now sudo service restart.

Give it a couple of seconds and your site should now be available at

Subsequent Deployments

The above steps are only for initial run. Once your server is setup, for the subsequent deployments all you have to do is build your jar file locally, copy it over, and then restart the web app service.

  1. To build the jar: ./alpas jar.
  2. To copy the jar: scp -i ~/.ssh/cleaver/<private-ssh-key> ./example.jar cleaver@<server-ip>:/home/cleaver/
  3. To restart the server (from within the remote server and as a root user): sudo service restart.


If you run into any issues, you can check the log files. Most of the times it is because you didn't use the correct port number and somehow mis-configured your nginx config file. Run the following command to check the log messages of your as they come in:

journalctl -f -u