Self hosted with existing reverse proxy

[jessielw]

Problem

A lot of users will want to run this stack with existing reverse proxies (swag, nginx, caddy, etc.). With the most recent update this is only possible from what I can tell by url hacks and bypassing the internal caddy completely which will only cause issues in the long run.

Has anyone had any success adding this to existing reverse proxies properly? If so mind sharing here so we can collaborate on the proper way to do this? I have it mostly working but there is some issues with the frontend and backend not working correctly in some scenarios.

To the devs amazing work so far I know this is an absolute behemoth of a program!

Proposal

Allow the software to be used with existing reverse proxies more easily or document the steps needed

Notes

No response

Checks

• I searched existing discussions.

[Speykious]

I did it and it was pretty easy to do. I just let Fluxer's Caddy run and put my own Caddy on top of that.
In .env, just set up a port and make the Caddy site address local:

+FLUXER_CADDY_PORT=6767
+FLUXER_CADDY_SITE_ADDRESS=:${FLUXER_CADDY_PORT}
-FLUXER_CADDY_SITE_ADDRESS=chat.example.com

Then in docker-compose.yml, make sure to expose that port in the Caddy service config:

 services:
   caddy:
     image: caddy:2.10-alpine
     restart: unless-stopped
     networks: [fluxer]
+    ports:
+      - "${FLUXER_CADDY_PORT}:${FLUXER_CADDY_PORT}"
     environment:
       FLUXER_CADDY_SITE_ADDRESS: ${FLUXER_CADDY_SITE_ADDRESS:?set FLUXER_CADDY_SITE_ADDRESS in .env}
     volumes:
       - ./Caddyfile:/etc/caddy/Caddyfile:ro
       - caddy-data:/data
       - caddy-config:/config
     depends_on: [api, gateway, media-proxy, static-proxy, admin]

Then just set the reverse proxy to that local port in your outward reverse proxy config:

chat.example.com {
    reverse_proxy :6767
}

And it should work without issue.
Though I've only tested this with Caddy.

[jessielw]

Thanks for the response. I spent several hours attempting to get nginx working properly (using swag) and it is not playing nice. Another user on reddit did some url hack work around - while that worked for him it'll only break later as the shape of the api changes.

I've not used caddy and have considered it but I've been on swag so long it would be a lot of work.

I do believe (at least for now) the right approach is to leave the internal caddy as is like you have done.

[jessielw]

Fluxer Behind SWAG / Nginx (Minimal Setup)

This is a minimal working setup for running Fluxer behind an external reverse proxy like SWAG or nginx.

---

Prerequisites

• Docker / Docker Compose
• Nginx (swag)
• A domain (e.g. fluxer.example.com)

---

1. Download Stack

base=https://raw.githubusercontent.com/fluxerapp/fluxer/main/deploy/self-hosting
mkdir fluxer && cd fluxer

curl -fsSLO "$base/docker-compose.yml"
curl -fsSLO "$base/Caddyfile"
curl -fsSLO "$base/livekit.yaml"
curl -fsSL "$base/.env.example" -o .env

Follow the self hosting guide https://docs.fluxer.app/operator/get-started/

---

2. Configure .env

Relevant parts below

FLUXER_DOMAIN=fluxer.example.com
FLUXER_PUBLIC_SCHEME=https
FLUXER_PUBLIC_PORT=443

# internal caddy (no TLS)
FLUXER_CADDY_PORT=8108
FLUXER_CADDY_SITE_ADDRESS=:${FLUXER_CADDY_PORT}

---

3. Do Not Modify the Caddyfile

Leave the default routing untouched as Fluxer depends on this behavior!

---

4. Fix Docker DNS (Required)

If your containers are named like fluxer-api-1 (dockge will do this if you use it in UnRaid), you must add aliases so Caddy can resolve services.

Update docker-compose.yml:

api:
  networks:
    fluxer:
      aliases: [api]

admin:
  networks:
    fluxer:
      aliases: [admin]

gateway:
  networks:
    fluxer:
      aliases: [gateway]

media-proxy:
  networks:
    fluxer:
      aliases: [media-proxy]

livekit:
  networks:
    fluxer:
      aliases: [livekit]

static-proxy:
  networks:
    fluxer:
      aliases: [static-proxy]

Ensure Caddy is on the same network:

caddy:
  networks:
    fluxer: {}

---

5. Start

docker compose up -d

---

6. SWAG / Nginx Config

Note the port below is the same as the one from step 1

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

    server_name fluxer.example.com;

    include /config/nginx/ssl.conf;

    client_max_body_size 500M;

    location / {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_pass http://fluxer-caddy:8108;
    }
}

---

7. Verify

# health
curl https://fluxer.example.com//_health
curl https://fluxer.example.com/api/_health

# static (must be 200)
curl -I https://fluxer.example.com/fonts/ibm-plex.css

# discovery (must return JSON)
curl https://fluxer.example.com/api/.well-known/fluxer

---

8. Finish Setup

Start the app/login and create admin account etc

---

Notes

• Don’t change Fluxer routing
• Fix networking instead
• Let Fluxer’s Caddy handle internal paths

[vulpeace]

If you run your fluxer instance using files from https://github.com/fluxerapp/fluxer/tree/main/deploy/self-hosting (maybe you're talking about some other way, dunno), you can just nuke caddy altogether. Here's how i've replaced it with nginx (there's a ui somewhere on digitalocean's website where you can tweak and generate your own nginx configuration that uses this modular approach).

fluxer.conf

server {
    listen 443 ssl;
    http2 on;
    server_name fluxer.example.com;

    access_log /var/log/nginx/fluxer.access.log main if=$loggable;

    include parts/security.conf;
    include parts/general.conf;
    client_max_body_size 1G;

    location /api/ {
        proxy_pass http://api:8080/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location = /gateway {
        proxy_pass http://gateway:8080/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location /gateway/ {
        proxy_pass http://gateway:8080/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location /media/ {
        proxy_pass http://media-proxy:8080/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location /livekit/ {
        proxy_pass http://livekit:7880/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location = /admin {
        proxy_pass http://admin:8080/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location /admin/ {
        proxy_pass http://admin:8080/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location ~ ^/(fonts|web|emoji|libs|avatars|badges|desktop|embeds)/ {
        proxy_pass http://static-proxy:8080;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }

    location / {
        proxy_pass http://app-proxy:8080;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }
}

server {
    listen 8088;

    location /api/ {
        proxy_pass http://api:8080/;
        include    parts/proxy.conf;
        include    parts/ws.conf;
    }
}

ws.conf

proxy_http_version 1.1;
proxy_cache_bypass $http_upgrade;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

proxy.conf

proxy_ssl_server_name              on;
proxy_set_header Host              $host;
proxy_set_header Forwarded         $proxy_add_forwarded;
proxy_set_header X-Real-IP         $proxy_protocol_addr;
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host  $host;
proxy_set_header X-Forwarded-Port  $server_port;

[jessielw]

This is a viable and interesting approach and really might be the best way to go about it. The only down side I can think of is having to maintain the endpoints if/when things change. But I guess that would be the same way if using the built in caddy server as well.

[InsertDisc]

I did this with Nginx Proxy Manager which didn't require a lot of these changes.

.env per the cloudflared tunnel instructions:

FLUXER_DOMAIN=chat.example.com
FLUXER_PUBLIC_SCHEME=https
FLUXER_PUBLIC_PORT=443
FLUXER_CADDY_SITE_ADDRESS=:80

Compose file with only one port for caddy

services:
  caddy:
    image: caddy:2.10-alpine
    restart: unless-stopped
    networks: [fluxer]
    ports:
      - "8180:80"
    environment:

Then just pointed my reverse proxy domain name at 192.168.x.x:8180
No issues so far.

Edit: As others have mentioned, there are a couple additional changes to be made to make everything work as it should. I didn't list them before as they weren't directly responsible for getting your existing reverse proxy to work.

1. To get the proper client ip address to be passed., add

{
        servers {
                trusted_proxies static private_ranges
        }
}

to the very top of your Caddyfile. The local ip of your reverse proxy can be specified in place of "private_ranges". I.E. (assuming your existing reverse proxy ip is 192.168.10.9

{
        servers {
                trusted_proxies static 192.168.10.9
        }
}

2. To take care of the error when clicking the "Connect" button under your server address add this .well-known path in with the other handlers in the same file. I left the beginning of the section in to give you an idea of the placement.

{$FLUXER_CADDY_SITE_ADDRESS} {
        encode zstd gzip

        handle /.well-known/* {
                reverse_proxy api:8080
        }

[Serephucus]

I've followed your changes here - though I'm not using a CF tunnel - but fluxer-api doesn't start:
✘ Container fluxer-api-1 Error dependency api failed to start

From its logs:
api-1 | {"level":"fatal","time":"2026-06-22T19:12:43.115Z","service":"fluxer-api","env":"production","error":{"type":"TypeError","message":"fetch failed: getaddrinfo ENOTFOUND meilisearch","stack":"TypeError: fetch failed\ncaused by: Error: getaddrinfo ENOTFOUND meilisearch\n at GetAddrInfoReqWrap.onlookupall [as oncomplete] (node:dns:122:26)"},"msg":"Failed to start Fluxer API"} api-1 | {"level":"warn","time":"2026-06-22T19:12:48.742Z","service":"fluxer-api","env":"production","msg":"Twilio inbound SMS webhook not configured (need integrations.sms.inbound_webhook_auth_token + integrations.sms.inbound_webhook_public_url); skipping installation"}

I'll be the first to admit that etworking is not my strong suit. Any guidance would be great.

[Hamarius]

I also have NPM running and the solution that @InsertDisc suggested worked for me, the only Problem i’m having, is that the real client IP is not forwarded, its always showing me the IP of NPM. I tried the headers that @vulpeace used but then Fluxer is not reachable any more.
I also tried only those:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Host $host;

but the second I add
proxy_set_header Host $host;

it breaks.

[jessielw]

I think to circumvent this you'd have to do it this way https://github.com/orgs/fluxerapp/discussions/1041#discussioncomment-17336693

[Hamarius]

Ok someone else asked for a log but in the meantime I guess the comment was deleted.

2026-06-20T17:10:21.789Z [fluxer-caddy-1] {"level":"warn","ts":1781975421.7897482,"logger":"http.handlers.reverse_proxy","msg":"aborting with incomplete response","upstream":"media-proxy:8080","duration":0.001349123,"request":{"remote_ip":"192.168.10.4","remote_port":"53954","client_ip":"192.168.10.4","proto":"HTTP/1.1","method":"GET","host":"chat.REDACTED.REDACTED","uri":"/attachments/1517866685141352451/1517919245088849920/E64DAACB-A696-4D9A-9547-455103682CDD.mp4","headers":{"Range":["bytes=0-"],"User-Agent":["Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.0.0 Safari/537.36"],"Accept-Language":["de-DE,de;q=0.9,en-US;q=0.8,en;q=0.7"],"Sec-Ch-Ua":["\"Chromium\";v=\"149\", \"Not)A;Brand\";v=\"24\""],"Downlink":["10"],"Sec-Ch-Ua-Platform":["\"Linux\""],"Sec-Fetch-Site":["same-origin"],"Via":["1.1 Caddy"],"X-Forwarded-Scheme":["https"],"Referer":["https://chat.REDACTED.REDACTED/channels/1517866685141352448/1517866685141352451"],"X-Forwarded-Proto":["http"],"X-Forwarded-For":["192.168.10.4"],"Accept":["*/*"],"Ect":["4g"],"Sec-Fetch-Mode":["no-cors"],"Priority":["i"],"Sec-Ch-Dpr":["1"],"Dpr":["1"],"X-Forwarded-Host":["chat.REDACTED.REDACTED"],"Sec-Ch-Ua-Mobile":["?0"],"Accept-Encoding":["identity;q=1, *;q=0"],"X-Real-Ip":["192.168.1.46"],"Sec-Fetch-Dest":["video"]}},"error":"writing: write tcp 172.29.0.22:80->192.168.10.4:53954: write: broken pipe"}
this is without any headers but what I'm already noticing is that the real client IP is listed with "X-Real-Ip" so caddy should already have the real IP. if any other logs from other containers would be relevant, just let me know. Im honestly a little bit overwhelmed with how many containers came with that stack.

Because from my Understanding is that its currently Fluxer -> Caddy -> NPM -> Client, if I am not wrong.

Well I could try the solution from @vulpeace as you suggested @jessielw

EDIT:

found a solution:

had to add this to my caddy file:

{
	servers {
		trusted_proxies static 192.168.10.4
	}
}

so the whole file looks like this:

{
	servers {
		trusted_proxies static 192.168.10.4
	}
}

{$FLUXER_CADDY_SITE_ADDRESS} {
	encode zstd gzip

	handle_path /api/* {
		reverse_proxy api:8080
	}

	handle /gateway {
		rewrite * /
		reverse_proxy gateway:8080
	}

	handle_path /gateway/* {
		reverse_proxy gateway:8080
	}

	handle_path /media/* {
		reverse_proxy media-proxy:8080
	}

	handle_path /livekit/* {
		reverse_proxy livekit:7880
	}

	handle /admin {
		rewrite * /
		reverse_proxy admin:8080
	}

	handle_path /admin/* {
		reverse_proxy admin:8080
	}

	@staticAssets path /fonts/* /web/* /emoji/* /libs/* /avatars/* /badges/* /desktop/* /embeds/*
	handle @staticAssets {
		reverse_proxy static-proxy:8080
	}

	handle {
		reverse_proxy app-proxy:8080
	}
}

:8088 {
	handle_path /api/* {
		reverse_proxy api:8080
	}
}