Skip to content

Update backup.mdx - add restore instructions and update backup files#722

Open
paula-coder-646 wants to merge 1 commit intonetbirdio:mainfrom
paula-coder-646:patch-1
Open

Update backup.mdx - add restore instructions and update backup files#722
paula-coder-646 wants to merge 1 commit intonetbirdio:mainfrom
paula-coder-646:patch-1

Conversation

@paula-coder-646
Copy link
Copy Markdown

Hi there,

First of all, thank you for the amazing project. It is really nice that your documentation caters to all user groups, not just pro-level admins, but also beginners :)
In line with this spirit, I noticed that although there is a backup section in the docs, it was missing the newer configuration files created for the netbird-proxy container, as well as the config files for the traefik and crowdsec containers.
Since partial backups can lead to headaches (e.g., needing to regenerate setup tokens for the proxy), I clarified that the backup should contain all files from the directory.

I also added a restore section, as I think it should be included, especially for newer users. I tested it and found it to be working for my setup, but I am happy for suggestions or edits, especially regarding this section.

Thank you for taking the time!
Best,
Paula

TL;DR:

  • Added section about restoring a backup
  • Updated "Back Up" section to include all files currently generated by the installation script (traefik, crowdsec, proxy.env)

- Added section about restoring a backup
- Updated "Back Up" section to include all files currently generated by the installation script (traefik, crowdsec, proxy.env)
Copy link
Copy Markdown
Contributor

@SunsetDrifter SunsetDrifter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested this end-to-end on a self-hosted lab (fresh netbird install, traefik reverse proxy, SQLite store, no CrowdSec). The restore flow conceptually works — wiping the netbird_data volume and walking the steps brought the stack back with store.db / idp.db / events.db intact and dashboard + API responding. Thanks for adding this section, it's a real gap.

A few issues I hit, ranked roughly by severity:

Bugs

  1. Backup cp is missing a destination and fails verbatim:

    cp -r crowdsec proxy.env traefik-dynamic.yaml

    cp treats the last arg as the destination, so this errors with cp: target 'traefik-dynamic.yaml': Not a directory. It should be:

    cp -r crowdsec proxy.env traefik-dynamic.yaml backup/
  2. Duplicate heading# Restore Your Self-Hosted NetBird Installation appears twice in a row in the diff. One needs to be removed.

  3. Heading level should be ##, not # — every other section in this page uses ## (e.g. ## Get In Touch). Using # makes the restore section a page-title-level header.

  4. Service-name inconsistency between backup and restore. The existing backup snippet uses management:

    docker compose cp -a management:/var/lib/netbird/ backup/

    The new restore snippet uses netbird-server:

    docker compose cp -a ./backup/netbird netbird-server:/var/lib/

    Current upstream installs use netbird-server (verified on the lab — management doesn't exist as a service). Recommend updating the backup line to netbird-server too so they match, or this PR will leave the page internally inconsistent.

  5. Typo: "log into the your backend" → "log into your backend".

Concerns

  1. cp -r crowdsec … will hard-fail on installs without CrowdSec. The prose says it depends on install method, but cp exits non-zero before it copies the other files when crowdsec/ is absent (verified: cp: cannot stat '/home/ubuntu/crowdsec': No such file or directory). Safer to either guard each path ([ -d crowdsec ] && cp -r crowdsec backup/) or list each file separately with a note.

  2. Restore omits the Traefik Let's Encrypt volume. After a true disk loss, docker compose up -d will trigger fresh ACME requests and risk hitting LE rate limits (this is easy to do — I've seen it on this lab). The PR could either tell users to back up the *_traefik_letsencrypt volume too (docker run --rm -v <vol>:/data -v $PWD/backup:/backup alpine tar -C /data -czf /backup/traefik-le.tgz .), or at minimum warn that certs will be re-issued.

  3. docker compose create (no args) creates services the user may not want. On the lab, this brought up the netbirdio/reverse-proxy service that wasn't part of the active install (traefik was the chosen reverse proxy), and it immediately went into a restart loop. Recommend explicitly listing services, e.g. docker compose create traefik dashboard netbird-server.

Nits

  1. Trailing whitespace after the closing fence on the restore code block.
  2. The lowercase optionally, between the two backup code blocks reads as a sentence fragment — would suggest making it a complete sentence ("Optionally, also back up …").

What worked

  • docker compose stop netbird-server && docker compose cp -a netbird-server:/var/lib/netbird/ backup/ && docker compose start netbird-server — clean.
  • After docker volume rm <project>_netbird_data, docker compose create then docker compose cp -a backup/netbird netbird-server:/var/lib/ then docker compose up -d restored the management server with intact identity, store, and events DBs. Dashboard returned HTTP 200, TLS cert preserved (since LE volume was kept), API responded normally.

Happy to validate any revisions if helpful.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants