Configuring URL & Ports

When Mediqux starts, the browser needs to know where the backend API lives. That is what BACKEND_URL is for — it is the only URL setting you need to configure.

---

The two variables that matter

Variable	What it does
BACKEND_URL	The full URL your browser uses to reach the API
BACKEND_DOCKER_PORT	The port Docker exposes on your host machine

FRONTEND_DOCKER_PORT controls which port the web UI is served on, but does not affect routing logic.

---

Scenario 1 — Home network / direct access (most common)

You access Mediqux by typing an IP and port directly into your browser (http://192.168.1.10:8080).

.env settings:

BACKEND_URL=http://192.168.1.10:3000/api
FRONTEND_DOCKER_PORT=8080
BACKEND_DOCKER_PORT=3000

The port in BACKEND_URL must match BACKEND_DOCKER_PORT.

---

Scenario 2 — Same machine (localhost)

Running and accessing Mediqux on the same computer.

.env settings:

BACKEND_URL=http://localhost:3000/api
FRONTEND_DOCKER_PORT=8080
BACKEND_DOCKER_PORT=3000

---

Scenario 3 — Behind a reverse proxy (Nginx, Caddy, Traefik, etc.)

Your proxy handles the public URL. Docker still listens internally on port 3000, but the browser never sees that port.

.env settings:

BACKEND_URL=https://mediqux.yourdomain.com/api
FRONTEND_DOCKER_PORT=8080
BACKEND_DOCKER_PORT=3000

The port in BACKEND_URL does not need to match BACKEND_DOCKER_PORT here.

Nginx example:

server {
    listen 443 ssl;
    server_name mediqux.yourdomain.com;

    location / {
        proxy_pass http://localhost:8080;
    }

    location /api/ {
        proxy_pass http://localhost:3000/api/;
    }
}

Caddy example (Caddyfile):

mediqux.yourdomain.com {
    handle /api/* {
        reverse_proxy localhost:3000
    }
    handle {
        reverse_proxy localhost:8080
    }
}

Caddy automatically provisions and renews HTTPS certificates — no extra SSL config needed.

---

Scenario 4 — Cloudflare Tunnel (no open ports)

If you want to expose Mediqux publicly without opening any ports on your router, Cloudflare Tunnel is a popular option for home lab setups.

.env settings:

BACKEND_URL=https://mediqux.yourdomain.com/api
FRONTEND_DOCKER_PORT=8080
BACKEND_DOCKER_PORT=3000

In your Cloudflare Tunnel config, set up two public hostnames:

Public hostname	Service
mediqux.yourdomain.com	http://localhost:8080
mediqux.yourdomain.com/api	http://localhost:3000

Or use a single hostname and route by path if your tunnel config supports it.

---

Scenario 5 — Custom ports

If port 3000 or 8080 are already in use on your machine, you can change them.

.env settings:

BACKEND_URL=http://192.168.1.10:4500/api
FRONTEND_DOCKER_PORT=9090
BACKEND_DOCKER_PORT=4500

You can use any free port. Just keep BACKEND_URL port and BACKEND_DOCKER_PORT in sync for direct access.

---

Quick rule of thumb

Direct access  →  port in BACKEND_URL = BACKEND_DOCKER_PORT
Reverse proxy  →  BACKEND_URL is your public domain, ports don't need to match

---

Common mistakes

Symptom	Cause	Fix
Page loads but login fails	BACKEND_URL set to localhost but accessing from another device	Use your server's IP address
Works on server, broken elsewhere	Same as above	BACKEND_URL=http://192.168.x.x:3000/api
Broken after adding HTTPS	BACKEND_URL still uses http://	Update to https://
API calls fail after changing ports	BACKEND_URL port not updated	Keep BACKEND_URL port and BACKEND_DOCKER_PORT in sync

---

After changing .env, restart:

docker compose down && docker compose up -d