Skip to main content

Installation

Requirements: Python 3.11+. The CLI entry point is edox-ops (edox_ops.cli:app).

From PyPI (operators)​

Install the published package on a VPS, edge host, or your workstation (for remote administration). Use a virtual environment when you prefer an isolated Python env:

python3 -m pip install --upgrade pip
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install edox-ops
edox-ops --version
edox-ops --help

Pin a release:

pip install edox-ops==0.1.0

Package index: pypi.org/project/edox-ops.

bootstrap, doctor, and project commands are intended for Linux targets (Ubuntu 24.04, Debian 12+, and Debian derivatives such as Raspberry Pi OS). You can install the CLI on macOS or Windows to manage remote hosts over SSH.

Upgrade when a new version is published:

pip install --upgrade edox-ops

Development install (Git checkout)​

For contributors working from a clone of this repository:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pre-commit install
pre-commit install --hook-type commit-msg

See Contributing for GitLab access and Cursor setup.

Target host (Ubuntu 24.04 LTS, Debian 12+, or Debian derivatives)​

edox-ops is designed for Ubuntu 24.04, Debian 12+, and Debian derivatives (including Raspberry Pi OS with ID=debian or legacy ID=raspbian) that will serve static documentation with nginx. On the host:

edox-ops bootstrap --yes
edox-ops doctor

Bootstrap installs packages, prepares nginx (including disabling the default site), and records steps in /var/log/edox-ops/bootstrap.log.

Raspberry Pi OS​

Modern Raspberry Pi OS (Debian bookworm base) is supported the same way as Debian: edox-ops doctor should report the detected distribution, and Docker installs use the official Debian apt repository for your architecture (arm64 or armhf). Prefer 64-bit Raspberry Pi OS for documentation hosting and optional GitLab Runner workloads.

GitLab CI runs an integration:arm64 smoke job on the saas-linux-small-arm64 hosted runner (debian:12, native ARM64): bootstrap, host:platform doctor check, and Docker install via the Debian apt repository. For extra confidence on real hardware, run edox-ops bootstrap --yes and edox-ops doctor on the Pi.

Optional GitLab Runner​

For CI deploys or integration tests on the host:

edox-ops gitlab-runner install --yes
export EDOX_RUNNER_TOKEN=…
edox-ops gitlab-runner register --url https://gitlab.example.com
edox-ops gitlab-runner status

See GitLab CI and SSH keys in the contributor guides.

HTTPS (Let's Encrypt)​

edox-ops certs install --yes
edox-ops project certs issue <slug> --email you@example.com --yes
edox-ops project update <slug> --tls
edox-ops project enable <slug>
edox-ops certs setup-auto-renew --yes

doctor and project validate check certificate files before you enable TLS.