Metadata-Version: 2.4
Name: ophix-server-base
Version: 2026.10.7.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
License-File: LICENSE
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
Dynamic: license-file

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