How to Install Kepler.gl on Ubuntu 22.04 with Custom Domain and SSL (Step-by-Step Guide) Non-Docker, Production Ready

This tutorial walks you through the complete manual setup of Kepler.gl, including environment configuration, build, HTTPS setup with NGINX Proxy Manager, and deployment on a custom domain like kepler.config-panel.com.

Overview

• Platform: Ubuntu 22.04 (e.g., AWS Lightsail)
• Frontend App: Kepler.gl demo-app
• Domain: kepler.config-panel.com
• Tools Used: Node.js, Yarn, PM2, esbuild, serve, NGINX Proxy Manager, Let’s Encrypt

Prerequisites

• Ubuntu 22.04 server (2 GB RAM or more)
• Domain (e.g., kepler.example.com) pointed to your server’s IP
• Basic SSH access to the server
• NGINX Proxy Manager installed (optional but recommended for SSL)

Step 1: Prepare the System

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl nano

# Optional: Add 8GB swap for performance
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Step 2: Install Node.js and Yarn

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g [email protected]

Step 3: HTTPS on your domain e.g. kepler.example.com

To avoid error like:

Uncaught Error: auth0-spa-js must run on a secure origin.

Why this happens:

Auth0 (and similar services) block their JavaScript SDK from running on public HTTP URLs due to security policies — it will only allow:

• http://localhost
• OR https://your-domain.com

Set up HTTPS using a reverse proxy (like NGINX) + a free certificate (via Let’s Encrypt):

i. Install NGINX and Certbot:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx -y

ii. Create NGINX Config for Kepler.gl:

Create a config

sudo nano /etc/nginx/sites-available/kepler

Paste this and save. (remember to change server_name as per your domain)

server {
    listen 80;
    server_name kepler.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

iii. Enable config and get SSL:

sudo ln -s /etc/nginx/sites-available/kepler /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

iii. Get SSL Certificate (change domain name)

sudo certbot --nginx -d kepler.example.com

Follow the prompts and select redirect HTTP to HTTPS when asked.

Step 4: Clone and Install Kepler.gl

git clone https://github.com/keplergl/kepler.gl.git
cd kepler.gl
yarn install

cd examples/demo-app
yarn install

Step 5: Add Environment Variables

Create the .env file to inject your API keys:

MapboxAccessToken="YOUR_MAPBOX_TOKEN"
DropboxClientId=""
MapboxExportToken=""
CartoClientId=""
FoursquareClientId=""
FoursquareDomain=""
FoursquareAPIURL=""
FoursquareUserMapsURL=""

Replace "YOUR_MAPBOX_TOKEN" with a valid token from mapbox.com.

Step 6: Fix/Patch esbuild.config.mjs to Use .env Values

Modify the define and plugins sections in

cd ~/kepler.gl/examples/demo-app/esbuild.config.mjs

to use environment variables.

define: {
    'process.env.MapboxAccessToken': JSON.stringify(process.env.MapboxAccessToken || ''),
    'process.env.DropboxClientId': JSON.stringify(process.env.DropboxClientId || ''),
    'process.env.MapboxExportToken': JSON.stringify(process.env.MapboxExportToken || ''),
    'process.env.CartoClientId': JSON.stringify(process.env.CartoClientId || ''),
    'process.env.FoursquareClientId': JSON.stringify(process.env.FoursquareClientId || ''),
    'process.env.FoursquareDomain': JSON.stringify(process.env.FoursquareDomain || ''),
    'process.env.FoursquareAPIURL': JSON.stringify(process.env.FoursquareAPIURL || ''),
    'process.env.FoursquareUserMapsURL': JSON.stringify(process.env.FoursquareUserMapsURL || ''),
    'process.env.NODE_ENV': '"production"'
  },

  plugins: [
    replace({
      __PACKAGE_VERSION__: KeplerPackage.version,
      "process.env.MapboxAccessToken": JSON.stringify(process.env.MapboxAccessToken),
      "process.env.DropboxClientId": JSON.stringify(process.env.DropboxClientId),
      "process.env.MapboxExportToken": JSON.stringify(process.env.MapboxExportToken),
      "process.env.CartoClientId": JSON.stringify(process.env.CartoClientId),
      "process.env.FoursquareClientId": JSON.stringify(process.env.FoursquareClientId),
      "process.env.FoursquareDomain": JSON.stringify(process.env.FoursquareDomain),
      "process.env.FoursquareAPIURL": JSON.stringify(process.env.FoursquareAPIURL),
      "process.env.FoursquareUserMapsURL": JSON.stringify(process.env.FoursquareUserMapsURL),
      include: /src/
    })
  ]

Step 7: Build the App

cd ~/kepler.gl/examples/demo-app
yarn build

Step 8: Create Minimal index.html

Some builds may lack a default index.html. Create it manually. (following code will auto create and update that)

cat <<EOF > ~/kepler.gl/examples/demo-app/dist/index.html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Kepler.gl</title>
    <link rel="stylesheet" href="bundle.css">
  </head>
  <body>
    <div id="root"></div>
    <script src="bundle.js"></script>
  </body>
</html>
EOF

Step 9: Serve the App

cd ~/kepler.gl/examples/demo-app/dist
npx serve -l 80

Now visit: kepler.config-panel.com (or what ever your domain is)

Step 10: Keep It Running with PM2

To keep the kepler app running even after closing the console windows:

npm install -g pm2
cd ~/kepler.gl/examples/demo-app/dist
pm2 serve . 80 --name kepler
pm2 startup
pm2 save

Use pm2 logs kepler to see logs if needed, and pm2 restart kepler to restart the app.

Troubleshooting and Fixes

Issue	Fix
process.env.MapboxAccessToken undefined	Added full define: mapping in esbuild.config.mjs
.env not loading	Hard-coded fallbacks in define, and set in .env
Missing index.html	Manually created in dist/ folder
Repeated 404 errors	Ensured bundle.css/js were referenced in new index.html
App not accessible externally	Used serve -l 80 + NGINX Proxy for public routing
HTTPS not working	Install NGINX and Certbot
App stopped on reboot	Used pm2 to persist and autostart

Final Output

✅ App hosted at: kepler.example.com

🔐 Secured with HTTPS

🔁 Auto-start on reboot (via PM2)

📦 Built manually with correct environment variables

---

Let us know in comments if you are facing issues during setup.