Migration guide from separate services to combined netbird-server

[SuperKali]

Problem

I currently have a NetBird deployment with separate services:

• netbird-management
• netbird-signal
• netbird-relay
• netbird-coturn

I want to migrate to the combined netbird-server container for simpler management, but there's no migration guide available.

Why migrate to combined server

• Simpler deployment and maintenance
• Fewer containers to manage
• Better alignment with official documentation
• Easier upgrades

What's needed

A migration guide covering:

1. Data backup: What data needs to be preserved (users, peers, configurations, keys)
2. Configuration migration: How to convert separate management.json, signal.json, etc. into combined server config
3. Database migration: How to migrate existing data to the new setup
4. External IdP: How to maintain Zitadel/Keycloak/Auth0 integration
5. Downtime strategy: Zero-downtime migration steps if possible
6. Rollback procedure: How to revert if something goes wrong

Current environment

• Deployment: Docker Compose with separate containers
• External IdP: Zitadel
• Reverse proxy: Traefik
• Data: Active users and peers that must be preserved

Expected outcome

Successfully migrate to netbird-server without losing:

• User accounts and permissions
• Peer connections and configurations
• Network policies and routes
• Authentication integration

This would help users who started with separate services and want to simplify their deployment.

[derlaft]

Hi,

I've also encountered an issue migrating as it. Currently, the guide says:

The proxy authenticates with the management server using an access token. Generate one using the management CLI:

docker exec -it netbird-server netbird-mgmt token create --name "my-proxy"

However, since I have a separate container deployment, netbird-server container is not present, and the command fails.

[derlaft]

Ok, It looks like it's supposed to be docker exec -it netbird-management /go/bin/netbird-mgmt token create --name "my-proxy":

• container is netbird-management
• netbird-mgmt is not in PATH

[da-wilky]

I would also love to see a migration guide from the multiple services approach to the simplified new server container!

[da-wilky]

And I somehow cant get the proxy part to work with my multi-service setup. Does anyone else has success with that?
My proxy container logs nothing and within the Dashboard I cannot add anything, because of the missing proxy cluster. I set the extra_host for my dashboard domain to the IP of the management service.

[derlaft]

And I somehow cant get the proxy part to work with my multi-service setup. Does anyone else has success with that?

It might be this issue: #5326

What the documentation is also kinda missing:

• You need a working traefik
• This traefik should actually forward grpc requests to proxy service (Documentation Issue: Missing Traefik Rules for new Reverse Proxy Feature #5326)
• proxy service should point to traefik, not to the management because it currently requres SSL (didn't find an option to disable it)

After all this I got it only partially working:

• Creation of custom domains and proxies works
• GUI still reports proxy agent as down
• proxy reports connection timeout issues via gRPC. probably, the idle timeout for a connection is way too low (a minute by default, in the previous recommended nginx config it was set to 1 day) + there are no keepalives configured in the connection itself

[da-wilky]

Thanks for the advice! It actually was the additional path I needed to add.
I wont ever go back to traefik from caddy - the UX is so much better for me. I got it working now with caddy instead.

If anyone wants to do that too - I use the caddy-l4 plugin (https://github.com/mholt/caddy-l4) and had a firefox bug solved by this issue (mholt/caddy-l4#257).

[quietPL83]

I am also interested in a migration guide to netbird-server.

[shaban00]

@da-wilky Can you share you current working caddy that has support for the Reverse proxy. The documentation says only traefik is supported now. I feel reluctant moving from Caddy to Traefik just because of this

[da-wilky]

@shaban00 Ofc, I added it inside an own issue: #5359
Please be aware that this is not considered production ready. It uses a caddy plugin that is still in development. For me thats fine and I did not encounter any issues yet. Please let me know if you have problems setting it up or if this guide was successfull for you. Also if you encounter any issues running that setup feel free to share :)

[pernetz]

Yeah, this migration guide would be great! I have tried to change over from single services to netbird-server manually, using the migration guides from Netbird docs as support. I failed miserably three times in a row and had to rollback my server. lol
Upvote +1 👍

[SuperKali]

This PR #5350 not resolve at all our issue, we used in past the first script to install netbird on our self hosted instances, with default Zitadel, How can we migrate this without losing anything?

[undes1red]

@SuperKali The netbird team says they are developing a migration tool to make Zitadel an extenal IdP provider, which is needed before we migrate from the old multi-instance setup to the combined one. But they also state "Please contact us at if you are interested in this feature." Issue #5334 asks when this tool will be ready but for now no response from the team.