Configure the URL

Overview

Configuring your application's URLs correctly is vital for generating working links, handling redirects, and ensuring your server is accessible over the network.

In this guide, you will learn how to:

• Set the Public URL (what users see).
• Configure the Listening URL (where the server binds).
• Use environment variables and .env files.
• Set up JopiJS behind a Reverse Proxy.

1. The Public URL (JOPI_WEBSITE_URL)

The Public URL is the address users type in their browser (e.g., https://example.com). JopiJS uses this URL to generate absolute links, handle SEO tags, and manage redirects.

Recommended: Environment Variables

Using environment variables is the most flexible way to configure your project, especially for Docker or CI/CD pipelines.

Using DotEnv files:

JopiJS automatically loads .env files based on your environment:

# The public address of your website
JOPI_WEBSITE_URL=https://my-great-website.com

Alternative: package.json

You can also set a default URL directly in your package.json.

{
    "jopi": {
        "webSiteUrl": "http://localhost:3000"
    }
}

2. The Listening URL (JOPI_WEBSITE_LISTENING_URL)

The Listening URL defines the internal IP and port where the JopiJS server binds.

• Default: value of JOPI_WEBSITE_URL.
• Listening network: http://0.0.0.0:3000 (Listens on all network interfaces on port 3000).
• Listening local only: Typically http://127.0.0.1:3000.

# Forces the server to listen only on localhost, port 8080
JOPI_WEBSITE_LISTENING_URL=http://127.0.0.1:8080

3. Using a Reverse Proxy

In a production environment, you rarely expose your Node.js/Bun server directly to the internet. Instead, you use a Reverse Proxy like Nginx, Apache, or Caddy.

Internal vs. Public URLs

When using a proxy, you must distinguish between your internal and public addresses:

How it works:

1. A user visits https://my-site.com.
2. The Reverse Proxy (Nginx) receives the request.
3. The Proxy "forwards" the request internally to http://127.0.0.1:3000.
4. JopiJS processes the request and sends the response back to the Proxy.