docs: rewrite README in English with standard structure

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -1,37 +1,68 @@
 # NetBox-Export
 
-NetBox-Export ist ein Plugin für NetBox 4.6.x und 4.7.x. Es exportiert einen abgegrenzten
+Export a scoped tenant or site area as a portable ZIP archive and import it into
-Mandanten- oder Standortbereich als portables ZIP-Archiv und importiert ihn in
+a second NetBox instance.
-eine zweite NetBox-Instanz.
 
-Unterstützte Startpunkte:
+| | |
+|---|---|
+| **Plugin name** | `netbox_export` |
+| **Package** | `netbox-export` |
+| **NetBox** | `4.6.0` – `4.7.x` |
+| **Python** | `>=3.12` |
+| **Repository** | <https://git.mrblake.cc/MrBlake/NetBox-Export> |
 
-- Mandantengruppe einschließlich Untergruppen und Mandanten
+## Features
-- einzelner Mandant
-- Region einschließlich Unterregionen und Standorten
-- einzelner Standort
-- Lokation einschließlich Unterlokationen
 
-Der Export folgt den Besitzbeziehungen zu DCIM-, IPAM-, Circuit-,
+Supported starting points:
-Virtualisierungs-, VPN-, Wireless-, Kontakt-, Tag- und Bilddaten. Benötigte
+
-Stammdaten werden als Abhängigkeiten mitgenommen. Primärschlüssel der
+- tenant group including sub-groups and tenants
-Quellinstanz werden nie direkt als Zielschlüssel verwendet.
+- single tenant
+- region including sub-regions and sites
+- single site
+- location including sub-locations
+
+The export follows ownership relations to DCIM, IPAM, circuit, virtualisation,
+VPN, wireless, contact, tag and image data. Required master data is included as
+dependencies. Primary keys of the source instance are never used directly as
+target keys.
+
+## Compatibility
+
+- NetBox `4.6.0` – `4.7.x`
+- Python `>=3.12`
+- Source and target must run the same NetBox version and the same plugins,
+  plugin versions and migrations.
 
 ## Installation
 
-Das Plugin muss auf beiden NetBox-Instanzen installiert sein.
+The plugin must be installed on **both** NetBox instances. All paths assume a
+standard installation under `/opt/netbox`.
+
+### 1. Install the package
 
 ```bash
-cd /opt/netbox
+/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
-source venv/bin/activate
-pip install --upgrade --force-reinstall \
   "git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main"
-
-# Prüfen, ob das Modul im NetBox-venv verfügbar ist
-python -c "import netbox_export; print(netbox_export.__file__)"
 ```
 
-In `configuration.py` ergänzen:
+For reproducible production installs, replace `main` with a release tag or a
+full commit ID.
+
+### 2. Add the plugin to `local_requirements.txt`
+
+This makes `upgrade.sh` reinstall the plugin automatically on every NetBox upgrade:
+
+```bash
+grep -qxF "git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main" /opt/netbox/local_requirements.txt \
+  || echo "git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main" | sudo tee -a /opt/netbox/local_requirements.txt
+```
+
+If the repository is private, the NetBox server needs a read-only deploy token
+or an SSH key. Do not store credentials in `local_requirements.txt`.
+
+### 3. Enable the plugin
+
+In `/opt/netbox/netbox/netbox/configuration.py`:
 
 ```python
 PLUGINS = [
@@ -43,122 +74,140 @@ PLUGINS_CONFIG = {
         "max_objects": 50000,
         "max_archive_size_mb": 250,
         "query_batch_size": 500,
-        # Auf beiden Instanzen identisch setzen, um Archive zu signieren.
+        # Set identically on both instances to sign archives.
-        "archive_signing_key": "eine-lange-zufaellige-geheime-zeichenfolge",
+        "archive_signing_key": "a-long-random-secret-string",
     },
 }
 ```
 
-Anschließend:
+If other plugins are already configured, add `netbox_export` to the existing
+list and dictionary instead of replacing them.
+
+### 4. Apply migrations, collect static files, restart
 
 ```bash
 cd /opt/netbox/netbox
-python manage.py migrate netbox_export
+/opt/netbox/venv/bin/python manage.py migrate netbox_export
-python manage.py collectstatic --no-input
+/opt/netbox/venv/bin/python manage.py collectstatic --no-input
 sudo systemctl restart netbox netbox-rq
 ```
 
-Falls `ModuleNotFoundError: No module named 'netbox_export'` erscheint, wurde
+If `ModuleNotFoundError: No module named 'netbox_export'` appears, the package
-das Paket nicht in `/opt/netbox/venv` installiert. In diesem Fall den obigen
+was not installed into `/opt/netbox/venv`. Check with:
-Installationsblock erneut ausführen und darauf achten, dass
-`/opt/netbox/venv/bin/python` verwendet wird:
 
 ```bash
-/opt/netbox/venv/bin/python -m pip install --upgrade --force-reinstall \
+/opt/netbox/venv/bin/python -c "import netbox_export; print(netbox_export.__file__)"
-  "git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main"
-/opt/netbox/venv/bin/python -c \
-  "import netbox_export; print(netbox_export.__file__)"
 ```
 
-Bei einer Docker-Installation wird das Paket in das eigene NetBox-Image
+For Docker installations, add the package to your NetBox image, rebuild the
-aufgenommen; danach wird der Container mit dem aktivierten Plugin neu gebaut und
+container with the plugin enabled and run the migration.
-die Migration ausgeführt.
 
-## Verwendung
+## Update
 
-Die Oberfläche liegt unter **Plugins > NetBox-Export > Export / Import** und ist
+```bash
-aus Sicherheitsgründen nur für Superuser sichtbar.
+/opt/netbox/venv/bin/pip install --upgrade --force-reinstall \
+  "git+https://git.mrblake.cc/MrBlake/NetBox-Export.git@main"
 
-1. Auf Instanz A den Typ und das konkrete Objekt wählen und das ZIP exportieren.
+cd /opt/netbox/netbox
-2. Auf Instanz B das ZIP zunächst mit **Nur prüfen** verarbeiten.
+/opt/netbox/venv/bin/python manage.py migrate netbox_export
-3. Nach erfolgreichem Prüflauf **Nur prüfen** deaktivieren, den schreibenden
+/opt/netbox/venv/bin/python manage.py collectstatic --no-input
-   Import bestätigen und das Archiv erneut hochladen.
+sudo systemctl restart netbox netbox-rq
+```
 
-Der Import läuft atomar. Bei einem Fehler werden alle Datenbankänderungen
+`--force-reinstall` makes pip pick up branch changes even if the package
-zurückgerollt. Die Konfliktstrategie **Aktualisieren** nutzt zuerst die dauerhaft
+version has not been bumped. Update source and target instance together.
-gespeicherte Zuordnung aus Quellinstanz, Modell und Quell-ID; bei einem ersten
-Import werden vorhandene Objekte über ihre eindeutigen Fachschlüssel erkannt.
 
-## Verhalten und Grenzen
+When NetBox itself is upgraded, `upgrade.sh` reinstalls the plugin from
+`local_requirements.txt` and runs migrations and `collectstatic`:
 
-- Quelle und Ziel müssen dieselbe unterstützte NetBox-Version (4.6.x oder 4.7.x) und dieselben Plugins/Modelle verwenden.
+```bash
-- Benutzerkonten und Berechtigungen werden nicht exportiert. Fehlende oder
+sudo /opt/netbox/upgrade.sh
-  nicht eindeutige Referenzen auf Benutzer und Gruppen werden ausgelassen und
+sudo systemctl restart netbox netbox-rq
-  nach dem Import als Warnung angezeigt. Benötigt ein neuer Datensatz zwingend
+```
-  eine solche Referenz, wird nur dieser Datensatz übersprungen.
-- Der Import erstellt und aktualisiert Objekte. Zielobjekte, die im Archiv nicht
-  vorkommen, werden bewusst nicht gelöscht.
-- Fehlende Bilddateien werden im Archiv vermerkt, können aber nicht rekonstruiert
-  werden.
-- Große Exporte werden synchron verarbeitet. `max_objects` begrenzt Laufzeit und
-  Speicherverbrauch.
-- `query_batch_size` steuert die Größe gebündelter Datenbankabfragen. Der
-  Standardwert `500` ist für typische PostgreSQL-Installationen geeignet;
-  Werte zwischen `250` und `1000` erlauben eine Anpassung an Arbeitsspeicher und
-  Datenbankleistung.
 
-## Plugin-Kompatibilität
+## Uninstall
 
-Der Exportgraph berücksichtigt installierte, mandantenbezogene Modelle und
+1. Remove `"netbox_export"` from `PLUGINS` and `PLUGINS_CONFIG`.
-Dateien aus NetBox-SLM, Netbox-DokiWiki und NetBox-VM-Import. Private oder
+2. Remove the line from `/opt/netbox/local_requirements.txt`.
-temporäre Plugin-Modelle werden nicht exportiert. Die von Netbox-Utilities
+3. Uninstall the package and restart NetBox:
-erzwungene Mandantenpflicht wird beim Import berücksichtigt: Das Zielobjekt wird
-erst gespeichert, nachdem sein Mandant importiert und zugeordnet wurde. Ist kein
-Mandant auflösbar, wird automatisch ein vorhandener Mandant `Auto-Import`
-verwendet oder neu angelegt. Der Importbericht weist darauf hin.
-Beziehungen, die Teil einer Plugin-Datenbankprüfung sind, werden vollständig
-aufgelöst, bevor das Objekt erstmals gespeichert wird. Dies betrifft unter
-anderem die Plattformzuordnung von NetBox-SLM-Softwareinstallationen.
-Eindeutige optionale Beziehungen wie die primären IP-Adressen von Geräten und
-virtuellen Maschinen werden in einer zweiten Phase zugewiesen. Eine veraltete
-Zielzuordnung wird dabei atomar gelöst und als Warnung protokolliert.
-Gespeicherte Importzuordnungen werden bei Wiederholungsimporten gegen den
-aktuellen Fachschlüssel geprüft. Existiert das Objekt bereits unter diesem
-Schlüssel, wird die Zuordnung korrigiert, statt ein Duplikat anzulegen.
-Bei neuen NetBox-Modulen wird die automatische Komponentenreplikation
-deaktiviert. Ports, Interfaces und Bays werden stattdessen ausschließlich aus
-den Archivdatensätzen angelegt beziehungsweise vorhandenen Komponenten
-zugeordnet.
-Geräte werden in einer separaten Abschlussphase im Rack platziert, damit auch
-Positionswechsel ohne temporäre Doppelbelegung funktionieren. Bei fremden
-Belegungen löst **Aktualisieren** das Zielgerät mit Warnung von seiner Position,
-**Überspringen** lässt das importierte Gerät positionslos und **Import abbrechen**
-meldet den Rackplatzkonflikt vor dem Datenbankfehler. Mehr-U- und
-Full-Depth-Belegungen werden dabei berücksichtigt.
-Front-/Rear-Port-Zuordnungen von Patchpanels werden als eigene Datensätze
-exportiert und bei **Aktualisieren** auf den Stand der Quelle gebracht. Nach dem
-Import stößt das Plugin für alle enthaltenen Kabel die NetBox-eigene
-Neuberechnung der Kabelpfade an. Für diese Korrektur muss mit Plugin-Version
-`0.3.12` oder neuer ein neues Archiv auf der Quellinstanz erzeugt werden, da
-ältere Archive keine Portzuordnungen enthalten.
-PostgreSQL-Range-Felder, darunter die erlaubten VLAN-ID-Bereiche einer
-VLAN-Gruppe, werden typisiert im Archiv gespeichert. Der Import erkennt auch
-die von älteren Plugin-Versionen als Text exportierten Range-Werte.
-Bei Bildanhängen werden Breite und Höhe direkt aus der Bilddatei im Archiv
-ermittelt. Dadurch sind die Pflichtfelder von NetBox auch im Prüflauf und bei
-Dateispeichern ohne unmittelbaren Modell-Save gesetzt. Bilder oberhalb des von
-NetBox verwendeten Limits von 25 Millionen Pixeln werden proportional auf
-höchstens 20 Millionen Pixel verkleinert und im Importbericht als Warnung
-ausgewiesen. Zum Schutz des Importprozesses bleibt eine harte Quellgrenze von
-100 Millionen Pixeln bestehen.
 
-Auf Quelle und Ziel müssen jeweils dieselben Plugin-Versionen und Migrationen
+```bash
-installiert sein. Verschlüsselte Zugangsdaten von NetBox-VM-Import sind nur bei
+/opt/netbox/venv/bin/pip uninstall netbox-export
-identischem Django-`SECRET_KEY` direkt nutzbar; andernfalls muss das Kennwort am
+sudo systemctl restart netbox netbox-rq
-Ziel neu gesetzt werden.
+```
 
-## Tests
+## Configuration
+
+| Key | Default | Description |
+|---|---|---|
+| `max_objects` | `50000` | Upper limit of objects per export (runtime and memory) |
+| `max_archive_size_mb` | `250` | Maximum archive size |
+| `query_batch_size` | `500` | Size of batched database queries; `250`–`1000` is reasonable |
+| `archive_signing_key` | – | Shared secret to sign archives; must be identical on both instances |
+
+## Usage
+
+The UI is located under **Plugins > NetBox-Export > Export / Import** and, for
+security reasons, is only visible to superusers.
+
+1. On instance A, choose the type and the specific object and export the ZIP.
+2. On instance B, first process the ZIP with **Dry run only**.
+3. After a successful dry run, disable **Dry run only**, confirm the writing
+   import and upload the archive again.
+
+The import is atomic: on error, all database changes are rolled back. The
+conflict strategy **Update** first uses the stored mapping of source instance,
+model and source ID; on a first import, existing objects are matched by their
+unique natural keys.
+
+### Behaviour and limits
+
+- User accounts and permissions are not exported. Missing or ambiguous user and
+  group references are omitted and reported as warnings; if a new record
+  strictly requires such a reference, only that record is skipped.
+- The import creates and updates objects. Target objects not contained in the
+  archive are intentionally **not** deleted.
+- Missing image files are noted in the archive but cannot be reconstructed.
+- Large exports are processed synchronously; `max_objects` limits runtime and memory.
+
+### Plugin compatibility
+
+- Tenant-related models and files of NetBox-SLM, Netbox-Documentation and
+  NetBox-VM-Import are included. Private or temporary plugin models are not exported.
+- The mandatory tenant assignment of Netbox-Utilities is respected: an object is
+  only saved after its tenant has been imported. If no tenant can be resolved,
+  an existing tenant `Auto-Import` is used or created, and the import report
+  says so.
+- Relations checked by plugin database constraints (e.g. the platform of
+  NetBox-SLM software installations) are resolved before the first save.
+- Unique optional relations such as primary IPs of devices and VMs are assigned
+  in a second phase; stale target assignments are released atomically and logged.
+- Stored import mappings are validated against the current natural key on
+  repeated imports, correcting the mapping instead of creating duplicates.
+- Automatic component replication is disabled for new modules; ports,
+  interfaces and bays are created solely from archive records.
+- Devices are placed in racks in a separate final phase so position swaps work
+  without temporary double occupancy. For foreign occupants, **Update** releases
+  the target device with a warning, **Skip** leaves the imported device without
+  a position, and **Abort import** reports the rack conflict. Multi-U and
+  full-depth occupancy are considered.
+- Front/rear port mappings of patch panels are exported as separate records and
+  synced on **Update**; cable paths are recalculated after import. This requires
+  an archive created with version `0.3.12` or newer.
+- PostgreSQL range fields (e.g. VLAN ID ranges of VLAN groups) are stored typed;
+  text values from older versions are still recognised.
+- Image width and height are read from the archived file. Images above NetBox's
+  25-megapixel limit are scaled down to at most 20 megapixels with a warning; a
+  hard source limit of 100 megapixels applies.
+- Encrypted credentials of NetBox-VM-Import are only usable with an identical
+  Django `SECRET_KEY`; otherwise set the password again on the target.
+
+## Development and tests
 
 ```bash
 python -m pytest
 ```
+
+## License
+
+Apache License 2.0 — see [LICENSE](LICENSE).