ophix-server-base 2026.10.4.1__tar.gz

ophix_server_base-2026.10.4.1/PKG-INFO

@@ -0,0 +1,355 @@
+Metadata-Version: 2.4
+Name: ophix-server-base
+Version: 2026.10.4.1
+Summary: Shared Django base for Ophix fleet management servers
+Author: Ophix Project
+License-Expression: MIT
+Project-URL: Homepage, https://ophix.io
+Project-URL: Documentation, https://github.com/ophixproject/ophix-server-base#readme
+Project-URL: Source, https://github.com/ophixproject/ophix-server-base
+Keywords: django,ophix,fleet management,server
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: Django<6.0,>=4.2; python_version < "3.12"
+Requires-Dist: Django>=4.2; python_version >= "3.12"
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: ophix-admin-interface>=2026.06.08.04
+Requires-Dist: ophix-admin-settings>=2026.06.08.03
+Requires-Dist: django-colorfield>=0.11
+Requires-Dist: django-apptemplates>=1.5
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: Jinja2>=3.0
+Requires-Dist: gunicorn>=21.0
+Requires-Dist: markdown>=3.4
+Requires-Dist: cryptography>=41.0
+
+# ophix-server-base
+
+**The shared foundation every [Ophix](https://ophix.io) server is built on** — a modular, self-hosted fleet management platform.
+
+Managing a fleet of servers usually means picking between a heavyweight all-in-one agent that phones home to someone else's cloud, or stitching together your own scripts for credentials, configs, certificates, and scheduled tasks across every box. Ophix takes a different approach: install only the domains you actually need — credential distribution, configuration management, certificate issuance, task scheduling, DNS management — each running as its own lightweight, independently deployable server and client pair, sharing nothing but this common foundation.
+
+`ophix-server-base` is that foundation: host/client registration, token + IP authentication, the plugin system every domain and extension is built on, and the guided installer that gets a server running.
+
+This package is automatically included in every Ophix server, no need to separately install it.
+
+---
+
+## Installation
+
+Installed automatically with any Ophix domain package (`ophix-creds`, `ophix-tasks`, etc.). To install explicitly:
+
+```bash
+pip install ophix-server-base
+```
+
+Install one domain plugin and a database engine plugin alongside it, with recommended extras:
+
+```bash
+pip install ophix-creds ophix-dbengine-mariadb ophix-docs venv-cmds
+```
+
+- `ophix-dbengine-mariadb` — MariaDB/MySQL driver; install the matching `ophix-dbengine-*`
+  plugin instead if you're using a different engine (Postgres, SQL Server, Oracle, CockroachDB).
+  Every engine needs its plugin installed explicitly — none is bundled by default.
+- `ophix-docs` — inline documentation in the admin UI
+- `venv-cmds` — lists available venv commands and checks for package updates
+
+---
+
+## Guided installation
+
+The recommended way to deploy a new server is the three-step guided installer.
+The examples below use `credserver` / `ophix-creds` — substitute your domain slug
+and package name (`confserver`, `certserver`, etc.) as appropriate. The pattern is
+identical for every domain.
+
+### Step 1 — configure
+
+```bash
+ophix-manage configure_install credserver
+```
+
+Interactive wizard. Prompts for install directory, hostname, TLS certificate paths
+(with CN/SAN validation), database connection (with live connection test), superuser
+credentials, and admin theme. Domain plugins contribute additional prompts — for
+example `ophix-creds` prompts to generate a `CRED_ENCRYPTION_KEY`.
+
+Writes two files:
+
+- `.credserver.conf` — machine-readable install config used by the next step
+- `.env` — complete environment file ready for use
+
+Safe to re-run: existing values are offered as defaults so you can update individual
+settings without re-entering everything.
+
+### Step 2 — install
+
+```bash
+ophix-manage run_install credserver
+```
+
+Reads `.credserver.conf` and performs all non-root steps:
+
+- Creates the install directory structure (`logs/`, `ssl/`, `static/`, etc.)
+- Copies TLS certificate, key, and CA bundle into place
+- Generates `credserver.nginx.conf` and `credserver.service` (systemd unit)
+- Generates `credserver_sudo_install.sh` and `credserver_sudo_uninstall.sh`
+- Runs plugin setup hooks (e.g. writes encryption keys to `.env`)
+- Runs `migrate`, `collectstatic`, and creates the superuser
+- Activates the configured theme and sets the admin title
+
+Options: `--skip-migrate`, `--skip-collectstatic`, `--skip-superuser`
+
+### Step 3 — system integration (as root)
+
+```bash
+sudo bash credserver_sudo_install.sh
+```
+
+Sets file ownership, installs the nginx config and systemd service, and starts the
+server. After this completes the admin UI is available at `https://your.hostname/admin/`.
+
+---
+
+## Routine upgrades
+
+```bash
+pip install --upgrade ophix-server-base ophix-creds   # upgrade packages
+ophix-manage migrate                                   # apply new migrations
+ophix-manage collectstatic --noinput                   # update static files
+sudo systemctl restart credserver                      # restart service
+```
+
+Or use the convenience command that runs all three steps in order:
+
+```bash
+ophix-manage apply_updates
+```
+
+If the upgrade added new `.env` settings, pull them in first:
+
+```bash
+ophix-manage generate_config --append
+```
+
+Do not re-run `configure_install` for routine upgrades — it rewrites `.env` from
+scratch.
+
+---
+
+## Configuration
+
+`.env` is generated by `configure_install` (see above). Key variables:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SERVER_NAME` | *(slug)* | Short name for this server instance |
+| `SERVER_VERSION` | *(domain version)* | Shown in the admin footer |
+| `INSTALL_DIR` | *(prompted)* | Root for runtime data: logs, media, ssl, static |
+| `ALLOWED_HOSTS` | *(hostname)* | Comma-separated hostnames this server accepts |
+| `DEBUG` | `False` | Enable only during development — never in production |
+| `SERVER_READ_ONLY_MODE` | `False` | Reject all API write requests. Use during migration change windows: set on the source server before exporting, leave unset on the target, then update DNS. |
+| `DB_ENGINE` | `mariadb` | `mariadb` \| `mysql` \| `postgres` \| `sqlserver` \| `cockroachdb` |
+| `DB_HOST` | `localhost` | Database host |
+| `DB_PORT` | `3306` | Database port |
+| `DB_NAME` | `ophix_db` | Database name |
+| `DB_USER` | `ophixuser` | Database user |
+| `DB_PASSWORD` | — | Database password |
+| `DB_SSL_CA` | — | Path to DB CA cert — enables TLS for the database connection |
+| `CA_CERT_FILE` | — | Path to internal CA cert served to clients unauthenticated |
+| `TIME_ZONE` | `UTC` | Server timezone. UTC is strongly recommended. If set to a non-UTC value and using MariaDB or MySQL, the database timezone tables must be populated — see [Audit logging](src/ophix/core/docs/server-installation.md#audit-logging) in the installation docs. |
+| `LANGUAGE_CODE` | `en-au` | Django language code |
+| `AUTH_LEAK_INFO` | `False` | Include error detail in API responses — development only |
+| `MINIMUM_TOKEN_ROTATE_TIME` | `3600` | Minimum seconds between token rotations |
+| `OPHIX_DISABLE` | — | Comma-separated plugin modules to suppress |
+
+Domain plugins add their own variables (e.g. `CRED_ENCRYPTION_KEY` from [ophix-creds](https://github.com/ophixproject/ophix-creds)).
+
+---
+
+## Documentation
+
+If `ophix-docs` is installed, documentation for all installed packages is loaded
+automatically at the end of `run_install`. No further action is needed for a fresh install.
+
+To load or refresh docs manually after upgrading packages, run `list_docs_sources`
+to see which app module names to include, then:
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_creds,ophix_docs
+```
+
+Substitute the module list for your server type — see
+[ophix-docs](https://github.com/ophixproject/ophix-docs) for per-server examples and
+the full list of documentation management commands.
+
+---
+
+## Management commands
+
+### Guided installer
+
+| Command | Purpose |
+| --- | --- |
+| `configure_install <slug>` | Interactive wizard — collects all settings, tests the DB connection, writes `.env` and `.<slug>.conf`. Idempotent; safe to re-run. |
+| `run_install <slug>` | Reads `.<slug>.conf`; creates the directory structure, copies TLS files, runs `migrate` / `collectstatic` / superuser, activates the theme, loads docs. |
+| `run_uninstall <slug>` | Regenerates or prints the sudo uninstall script. Data directory is never removed automatically. |
+
+See [Guided installation](#guided-installation) above for the full three-step walkthrough.
+
+---
+
+### Manual / legacy deployment
+
+These commands underpin `configure_install` / `run_install` and remain available for scripted or customised deployments.
+
+**`generate_config`** — generates deployment files from templates:
+
+| Flag | Output |
+| --- | --- |
+| `--env` | `.env.sample` (base settings + all installed plugin env fragments appended) |
+| `--nginx` | `<slug>.nginx.conf` (HTTP redirect + HTTPS reverse proxy) |
+| `--systemd` | `<slug>.service` (gunicorn systemd unit) |
+| `--all` | All three of the above |
+| `--append` | Appends any missing plugin variables to the existing `.env`. Use after installing a new plugin. Never modifies existing values. |
+
+```bash
+ophix-manage generate_config --all \
+    --server-hostname credserver.example.com \
+    --service-user ophix
+
+# After installing a new plugin into an existing deployment:
+ophix-manage generate_config --append
+```
+
+**`configure_database`** — interactive prompt to configure and live-test the database connection, then write the result to `.env`. Live-tests all six supported engines: MariaDB, MySQL, PostgreSQL, CockroachDB, SQL Server, and Oracle. Optional TLS and mutual TLS (not applicable to SQL Server or Oracle — see the driver plugin READMEs).
+
+```bash
+ophix-manage configure_database
+```
+
+---
+
+### Operations
+
+**`list_plugins`** — lists all installed Ophix plugins discovered via the `ophix.plugins` entry point group, plus `ophix-server-base` itself.
+
+```bash
+ophix-manage list_plugins             # names only
+ophix-manage list_plugins --details   # name, package, module, version
+```
+
+**`check_updates`** — checks all installed Ophix plugins against the configured pip index and reports whether newer versions are available. Results are stored in `PackageUpdateRecord` and shown in the admin UI.
+
+```bash
+ophix-manage check_updates
+ophix-manage check_updates --quiet   # suppress output; suitable for cron
+```
+
+**`apply_updates`** — convenience wrapper that runs `migrate`, `collectstatic --noinput`, and `generate_config --append` in sequence, then prints a reminder to restart the service. Run this after `pip install --upgrade`.
+
+```bash
+ophix-manage apply_updates
+```
+
+**`prune_access_logs`** — deletes `AccessLog` records older than N days. Intended to be run periodically via cron.
+
+```bash
+ophix-manage prune_access_logs               # default: 90 days
+ophix-manage prune_access_logs --days 30
+ophix-manage prune_access_logs --days 30 --dry-run
+```
+
+**`archive_access_logs`** — exports `AccessLog` records to a file for long-term retention or compliance. Use `--append` for incremental cron runs (writes newline-delimited JSON). Combine with `prune_access_logs` to archive-then-purge:
+
+```bash
+ophix-manage archive_access_logs --output-file archive.ndjson --days 90 --append
+ophix-manage prune_access_logs --days 90
+```
+
+---
+
+### Host and client backup
+
+**`export_hosts`** / **`import_hosts`** — transfer Host records between servers. Idempotent (matched by name). Both support `--dry-run` and `--quiet`; `import_hosts` supports `--force` to bypass IP conflict checks.
+
+**`export_clients`** / **`import_clients`** — backup and restore Client records including tokens, enabling fleet clients to reconnect to a rebuilt server without re-registering. `export_clients` accepts `--passphrase` to encrypt tokens at rest; `import_clients` requires the same passphrase when the file is encrypted. Both support `--dry-run` and `--quiet`; `import_clients` supports `--force`.
+
+Run `import_hosts` before `import_clients` when doing a full server restore.
+
+---
+
+### Standard Django commands
+
+```bash
+# Using the installed entry point
+ophix-manage migrate
+ophix-manage collectstatic
+ophix-manage createsuperuser
+
+# Or via Python
+python -m ophix.manage migrate
+```
+
+Always set `DJANGO_SETTINGS_MODULE=ophix.settings` (the default).
+
+---
+
+## Plugin system
+
+Any pip-installable package that registers under the `ophix.plugins`
+entry point group is automatically added to `INSTALLED_APPS` and its
+URLs are included.
+
+```toml
+# In your plugin's pyproject.toml:
+[project.entry-points."ophix.plugins"]
+my_plugin = "my_plugin_module"
+```
+
+To suppress an installed plugin without uninstalling it:
+
+```bash
+OPHIX_DISABLE=my_plugin_module
+```
+
+---
+
+## Standard API endpoints
+
+Every OPS server exposes these regardless of installed plugins:
+
+| Method | Path | Auth | Purpose |
+| --- | --- | --- | --- |
+| `GET` | `/api/server/ca-cert/` | None | Download internal CA cert |
+| `POST` | `/api/register/` | None | Register a new client |
+| `GET` | `/api/client/self/` | Token | Client self-inspection |
+| `PATCH` | `/api/client/self/update/` | Token | Update venv/deployment info |
+| `POST` | `/api/client/self/rotate-token/` | Token | Rotate API token |
+
+---
+
+## Authentication
+
+All authenticated endpoints require:
+
+```text
+Authorization: Token <64-char hex token>
+```
+
+Requests are also validated against the client's registered Host IP.
+Both conditions must pass. See `ophix.core.auth.ClientTokenAuthentication`.

ophix_server_base-2026.10.4.1/README.md

@@ -0,0 +1,317 @@
+# ophix-server-base
+
+**The shared foundation every [Ophix](https://ophix.io) server is built on** — a modular, self-hosted fleet management platform.
+
+Managing a fleet of servers usually means picking between a heavyweight all-in-one agent that phones home to someone else's cloud, or stitching together your own scripts for credentials, configs, certificates, and scheduled tasks across every box. Ophix takes a different approach: install only the domains you actually need — credential distribution, configuration management, certificate issuance, task scheduling, DNS management — each running as its own lightweight, independently deployable server and client pair, sharing nothing but this common foundation.
+
+`ophix-server-base` is that foundation: host/client registration, token + IP authentication, the plugin system every domain and extension is built on, and the guided installer that gets a server running.
+
+This package is automatically included in every Ophix server, no need to separately install it.
+
+---
+
+## Installation
+
+Installed automatically with any Ophix domain package (`ophix-creds`, `ophix-tasks`, etc.). To install explicitly:
+
+```bash
+pip install ophix-server-base
+```
+
+Install one domain plugin and a database engine plugin alongside it, with recommended extras:
+
+```bash
+pip install ophix-creds ophix-dbengine-mariadb ophix-docs venv-cmds
+```
+
+- `ophix-dbengine-mariadb` — MariaDB/MySQL driver; install the matching `ophix-dbengine-*`
+  plugin instead if you're using a different engine (Postgres, SQL Server, Oracle, CockroachDB).
+  Every engine needs its plugin installed explicitly — none is bundled by default.
+- `ophix-docs` — inline documentation in the admin UI
+- `venv-cmds` — lists available venv commands and checks for package updates
+
+---
+
+## Guided installation
+
+The recommended way to deploy a new server is the three-step guided installer.
+The examples below use `credserver` / `ophix-creds` — substitute your domain slug
+and package name (`confserver`, `certserver`, etc.) as appropriate. The pattern is
+identical for every domain.
+
+### Step 1 — configure
+
+```bash
+ophix-manage configure_install credserver
+```
+
+Interactive wizard. Prompts for install directory, hostname, TLS certificate paths
+(with CN/SAN validation), database connection (with live connection test), superuser
+credentials, and admin theme. Domain plugins contribute additional prompts — for
+example `ophix-creds` prompts to generate a `CRED_ENCRYPTION_KEY`.
+
+Writes two files:
+
+- `.credserver.conf` — machine-readable install config used by the next step
+- `.env` — complete environment file ready for use
+
+Safe to re-run: existing values are offered as defaults so you can update individual
+settings without re-entering everything.
+
+### Step 2 — install
+
+```bash
+ophix-manage run_install credserver
+```
+
+Reads `.credserver.conf` and performs all non-root steps:
+
+- Creates the install directory structure (`logs/`, `ssl/`, `static/`, etc.)
+- Copies TLS certificate, key, and CA bundle into place
+- Generates `credserver.nginx.conf` and `credserver.service` (systemd unit)
+- Generates `credserver_sudo_install.sh` and `credserver_sudo_uninstall.sh`
+- Runs plugin setup hooks (e.g. writes encryption keys to `.env`)
+- Runs `migrate`, `collectstatic`, and creates the superuser
+- Activates the configured theme and sets the admin title
+
+Options: `--skip-migrate`, `--skip-collectstatic`, `--skip-superuser`
+
+### Step 3 — system integration (as root)
+
+```bash
+sudo bash credserver_sudo_install.sh
+```
+
+Sets file ownership, installs the nginx config and systemd service, and starts the
+server. After this completes the admin UI is available at `https://your.hostname/admin/`.
+
+---
+
+## Routine upgrades
+
+```bash
+pip install --upgrade ophix-server-base ophix-creds   # upgrade packages
+ophix-manage migrate                                   # apply new migrations
+ophix-manage collectstatic --noinput                   # update static files
+sudo systemctl restart credserver                      # restart service
+```
+
+Or use the convenience command that runs all three steps in order:
+
+```bash
+ophix-manage apply_updates
+```
+
+If the upgrade added new `.env` settings, pull them in first:
+
+```bash
+ophix-manage generate_config --append
+```
+
+Do not re-run `configure_install` for routine upgrades — it rewrites `.env` from
+scratch.
+
+---
+
+## Configuration
+
+`.env` is generated by `configure_install` (see above). Key variables:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `SERVER_NAME` | *(slug)* | Short name for this server instance |
+| `SERVER_VERSION` | *(domain version)* | Shown in the admin footer |
+| `INSTALL_DIR` | *(prompted)* | Root for runtime data: logs, media, ssl, static |
+| `ALLOWED_HOSTS` | *(hostname)* | Comma-separated hostnames this server accepts |
+| `DEBUG` | `False` | Enable only during development — never in production |
+| `SERVER_READ_ONLY_MODE` | `False` | Reject all API write requests. Use during migration change windows: set on the source server before exporting, leave unset on the target, then update DNS. |
+| `DB_ENGINE` | `mariadb` | `mariadb` \| `mysql` \| `postgres` \| `sqlserver` \| `cockroachdb` |
+| `DB_HOST` | `localhost` | Database host |
+| `DB_PORT` | `3306` | Database port |
+| `DB_NAME` | `ophix_db` | Database name |
+| `DB_USER` | `ophixuser` | Database user |
+| `DB_PASSWORD` | — | Database password |
+| `DB_SSL_CA` | — | Path to DB CA cert — enables TLS for the database connection |
+| `CA_CERT_FILE` | — | Path to internal CA cert served to clients unauthenticated |
+| `TIME_ZONE` | `UTC` | Server timezone. UTC is strongly recommended. If set to a non-UTC value and using MariaDB or MySQL, the database timezone tables must be populated — see [Audit logging](src/ophix/core/docs/server-installation.md#audit-logging) in the installation docs. |
+| `LANGUAGE_CODE` | `en-au` | Django language code |
+| `AUTH_LEAK_INFO` | `False` | Include error detail in API responses — development only |
+| `MINIMUM_TOKEN_ROTATE_TIME` | `3600` | Minimum seconds between token rotations |
+| `OPHIX_DISABLE` | — | Comma-separated plugin modules to suppress |
+
+Domain plugins add their own variables (e.g. `CRED_ENCRYPTION_KEY` from [ophix-creds](https://github.com/ophixproject/ophix-creds)).
+
+---
+
+## Documentation
+
+If `ophix-docs` is installed, documentation for all installed packages is loaded
+automatically at the end of `run_install`. No further action is needed for a fresh install.
+
+To load or refresh docs manually after upgrading packages, run `list_docs_sources`
+to see which app module names to include, then:
+
+```bash
+ophix-manage update_docs --include-app-docs ophix.core,ophix_creds,ophix_docs
+```
+
+Substitute the module list for your server type — see
+[ophix-docs](https://github.com/ophixproject/ophix-docs) for per-server examples and
+the full list of documentation management commands.
+
+---
+
+## Management commands
+
+### Guided installer
+
+| Command | Purpose |
+| --- | --- |
+| `configure_install <slug>` | Interactive wizard — collects all settings, tests the DB connection, writes `.env` and `.<slug>.conf`. Idempotent; safe to re-run. |
+| `run_install <slug>` | Reads `.<slug>.conf`; creates the directory structure, copies TLS files, runs `migrate` / `collectstatic` / superuser, activates the theme, loads docs. |
+| `run_uninstall <slug>` | Regenerates or prints the sudo uninstall script. Data directory is never removed automatically. |
+
+See [Guided installation](#guided-installation) above for the full three-step walkthrough.
+
+---
+
+### Manual / legacy deployment
+
+These commands underpin `configure_install` / `run_install` and remain available for scripted or customised deployments.
+
+**`generate_config`** — generates deployment files from templates:
+
+| Flag | Output |
+| --- | --- |
+| `--env` | `.env.sample` (base settings + all installed plugin env fragments appended) |
+| `--nginx` | `<slug>.nginx.conf` (HTTP redirect + HTTPS reverse proxy) |
+| `--systemd` | `<slug>.service` (gunicorn systemd unit) |
+| `--all` | All three of the above |
+| `--append` | Appends any missing plugin variables to the existing `.env`. Use after installing a new plugin. Never modifies existing values. |
+
+```bash
+ophix-manage generate_config --all \
+    --server-hostname credserver.example.com \
+    --service-user ophix
+
+# After installing a new plugin into an existing deployment:
+ophix-manage generate_config --append
+```
+
+**`configure_database`** — interactive prompt to configure and live-test the database connection, then write the result to `.env`. Live-tests all six supported engines: MariaDB, MySQL, PostgreSQL, CockroachDB, SQL Server, and Oracle. Optional TLS and mutual TLS (not applicable to SQL Server or Oracle — see the driver plugin READMEs).
+
+```bash
+ophix-manage configure_database
+```
+
+---
+
+### Operations
+
+**`list_plugins`** — lists all installed Ophix plugins discovered via the `ophix.plugins` entry point group, plus `ophix-server-base` itself.
+
+```bash
+ophix-manage list_plugins             # names only
+ophix-manage list_plugins --details   # name, package, module, version
+```
+
+**`check_updates`** — checks all installed Ophix plugins against the configured pip index and reports whether newer versions are available. Results are stored in `PackageUpdateRecord` and shown in the admin UI.
+
+```bash
+ophix-manage check_updates
+ophix-manage check_updates --quiet   # suppress output; suitable for cron
+```
+
+**`apply_updates`** — convenience wrapper that runs `migrate`, `collectstatic --noinput`, and `generate_config --append` in sequence, then prints a reminder to restart the service. Run this after `pip install --upgrade`.
+
+```bash
+ophix-manage apply_updates
+```
+
+**`prune_access_logs`** — deletes `AccessLog` records older than N days. Intended to be run periodically via cron.
+
+```bash
+ophix-manage prune_access_logs               # default: 90 days
+ophix-manage prune_access_logs --days 30
+ophix-manage prune_access_logs --days 30 --dry-run
+```
+
+**`archive_access_logs`** — exports `AccessLog` records to a file for long-term retention or compliance. Use `--append` for incremental cron runs (writes newline-delimited JSON). Combine with `prune_access_logs` to archive-then-purge:
+
+```bash
+ophix-manage archive_access_logs --output-file archive.ndjson --days 90 --append
+ophix-manage prune_access_logs --days 90
+```
+
+---
+
+### Host and client backup
+
+**`export_hosts`** / **`import_hosts`** — transfer Host records between servers. Idempotent (matched by name). Both support `--dry-run` and `--quiet`; `import_hosts` supports `--force` to bypass IP conflict checks.
+
+**`export_clients`** / **`import_clients`** — backup and restore Client records including tokens, enabling fleet clients to reconnect to a rebuilt server without re-registering. `export_clients` accepts `--passphrase` to encrypt tokens at rest; `import_clients` requires the same passphrase when the file is encrypted. Both support `--dry-run` and `--quiet`; `import_clients` supports `--force`.
+
+Run `import_hosts` before `import_clients` when doing a full server restore.
+
+---
+
+### Standard Django commands
+
+```bash
+# Using the installed entry point
+ophix-manage migrate
+ophix-manage collectstatic
+ophix-manage createsuperuser
+
+# Or via Python
+python -m ophix.manage migrate
+```
+
+Always set `DJANGO_SETTINGS_MODULE=ophix.settings` (the default).
+
+---
+
+## Plugin system
+
+Any pip-installable package that registers under the `ophix.plugins`
+entry point group is automatically added to `INSTALLED_APPS` and its
+URLs are included.
+
+```toml
+# In your plugin's pyproject.toml:
+[project.entry-points."ophix.plugins"]
+my_plugin = "my_plugin_module"
+```
+
+To suppress an installed plugin without uninstalling it:
+
+```bash
+OPHIX_DISABLE=my_plugin_module
+```
+
+---
+
+## Standard API endpoints
+
+Every OPS server exposes these regardless of installed plugins:
+
+| Method | Path | Auth | Purpose |
+| --- | --- | --- | --- |
+| `GET` | `/api/server/ca-cert/` | None | Download internal CA cert |
+| `POST` | `/api/register/` | None | Register a new client |
+| `GET` | `/api/client/self/` | Token | Client self-inspection |
+| `PATCH` | `/api/client/self/update/` | Token | Update venv/deployment info |
+| `POST` | `/api/client/self/rotate-token/` | Token | Rotate API token |
+
+---
+
+## Authentication
+
+All authenticated endpoints require:
+
+```text
+Authorization: Token <64-char hex token>
+```
+
+Requests are also validated against the client's registered Host IP.
+Both conditions must pass. See `ophix.core.auth.ClientTokenAuthentication`.