ophix-server-base

The shared foundation every Ophix 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:

pip install ophix-server-base

Install one domain plugin and a database engine plugin alongside it, with recommended extras:

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

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

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)

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

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:

ophix-manage apply_updates

If the upgrade added new .env settings, pull them in first:

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 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).

---

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:

ophix-manage update_docs --include-app-docs ophix.core,ophix_creds,ophix_docs

Substitute the module list for your server type — see 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 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.

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).

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.

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.

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.

ophix-manage apply_updates

prune_access_logs — deletes AccessLog records older than N days. Intended to be run periodically via cron.

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:

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

# 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.

# In your plugin's pyproject.toml:
[project.entry-points."ophix.plugins"]
my_plugin = "my_plugin_module"

To suppress an installed plugin without uninstalling it:

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:

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.