Basic Server Setup

How to serve your own Java application with CheerpJ

Overview

To run a Java application in the browser with CheerpJ, its files must be served by an HTTP server. Opening the page from the local disk (file://) does not work. This guide covers a few one-line HTTP servers for local testing, and an NGINX configuration for more advanced setups, for example when self-hosting the CheerpJ runtime, which needs a licence.

Important
The configurations in this guide are for testing and are not meant for production. Production deployments must use HTTPS, both for security and because some browser APIs, such as the system clipboard, are only available in a secure context. See deployment for production requirements.

Static one-line servers

One-line HTTP servers run from the terminal with a short command. They are useful for serving static files and testing web applications locally.

One-line servers that have been tested with CheerpJ:

  • npx serve
  • npx http-server

CheerpJ HTTP server requirements

Range requests

CheerpJ uses HTTP Range requests to download resources, such as JAR files, in chunks. The HTTP server hosting the application files must therefore support the Range header. Some servers need extra configuration to enable it, and others do not support it at all. Python’s http.server module, often used for quick testing, does not support it, so CheerpJ cannot run from it.

If the HTTP server does not support the Range header, the browser console shows an error like this:

Network error for http://127.0.0.1:8084/exampleApp.jar: HTTP server does not support the ‘Range’ header. CheerpJ cannot run.

npx serve and npx http-server support range requests without extra configuration, so they are suitable for basic testing. So does NGINX, described later in this guide.

JavaScript library files

Native libraries can be implemented as JavaScript modules, as described in the native libraries guide.

Depending on the size of the JavaScript library file, some browsers, such as Firefox, may show this error:

Network error for http://localhost:8080/library.js: HTTP server returned compressed partial data. That should not happen. CheerpJ cannot run

Firefox sends the Accept-Encoding: gzip header with range requests, and some servers respond by compressing the partial response. This is not well defined: it is unclear whether the response contains part of the compressed file, or a compressed part of the file.

To resolve it, disable compression for range requests, or disable compression entirely. To disable compression in npx serve, use npx serve -u.

npx http-server serves JavaScript library files without compression by default.

NGINX guide

This section does not cover installing NGINX. It covers the configuration NGINX needs to serve a CheerpJ application.

NGINX configuration file

This NGINX configuration template works with most Java applications and CheerpJ for testing.

nginx.conf
worker_processes 1;
error_log nginx_main_error.log info;
pid nginx_user.pid;
daemon off;
events {
worker_connections 1024;
}
http {
access_log nginx_access.log;
error_log nginx_error.log info;
default_type application/octet-stream;
sendfile on;
types {
text/html html;
text/css css;
application/javascript js;
application/wasm wasm;
}
server {
listen 8080;
server_name localhost;
gzip on;
gzip_types application/javascript application/wasm;
charset utf-8;
location / {
# this should point to your root application folder
root /home/path/to/java/app;
autoindex on;
absolute_redirect off;
index index.html index.htm;
}
}
}

The settings that matter for CheerpJ are described below.

The default MIME type for files with no other type is application/octet-stream. This marks the file as binary data, so the browser treats it as raw bytes instead of interpreting it as text or any other format.

default_type application/octet-stream;

The types block defines MIME types for the file extensions CheerpJ uses. NGINX uses it to set the Content-Type header of each response, so the browser interprets the content correctly.

types {
text/html html;
text/css css;
application/javascript js;
application/wasm wasm;
}

The server block enables compression for .js and .wasm files, which make up most of the runtime.

gzip on;
gzip_types application/javascript application/wasm;

The location block turns off absolute redirects, so NGINX generates relative redirects.

absolute_redirect off;

Get rid of 404 not found messages

When self-hosting a runtime build of CheerpJ, the browser console may show 404 not found messages for runtime files that do not exist. To avoid them, use the try_files directive.

location / {
root /home/path/to/cheerpj;
autoindex on;
try_files $uri $uri/ =204;
}

With this try_files directive, NGINX returns a 204 status code for any file that is not found. This means that the request succeeded and there is no content to return.

Build with Java for the browser.